1.\" Copyright (c) 1992, 1993, 1994 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" %sccs.include.redist.roff% 5.\" 6.\" @(#)symlink.7 8.3 (Berkeley) 03/31/94 7.\" 8.Dd 9.Dt SYMLINK 7 10.Os BSD 4 11.Sh NAME 12.Nm symlink 13.Nd symbolic link handling 14.Sh SYMBOLIC LINK HANDLING 15Symbolic links are files that act as pointers to other files. 16To understand their behavior, you must first understand how hard links 17work. 18A hard link to a file is indistinguishable from the original file because 19it is a reference to the object underlying the original file name. 20Changes to a file are independent of the name used to reference the 21file. 22Hard links may not refer to directories and may not reference files 23on different file systems. 24A symbolic link contains the name of the file to which it is linked, 25i.e. it is a pointer to another name, and not to an underlying object. 26For this reason, symbolic links may reference directories and may span 27file systems. 28.Pp 29Because a symbolic link and its referenced object coexist in the filesystem 30name space, confusion can arise in distinguishing between the link itself 31and the referenced object. 32Historically, commands and system calls have adopted their own link 33following conventions in a somewhat ad-hoc fashion. 34Rules for more a uniform approach, as they are implemented in this system, 35are outlined here. 36It is important that local applications conform to these rules, too, 37so that the user interface can be as consistent as possible. 38.Pp 39Symbolic links are handled either by operating on the link itself, 40or by operating on the object referenced by the link. 41In the latter case, 42an application or system call is said to 43.Dq follow 44the link. 45Symbolic links may reference other symbolic links, 46in which case the links are dereferenced until an object that is 47not a symbolic link is found, 48a symbolic link which references a file which doesn't exist is found, 49or a loop is detected. 50(Loop detection is done by placing an upper limit on the number of 51links that may be followed, and an error results if this limit is 52exceeded.) 53.Pp 54There are three separate areas that need to be discussed. 55They are as follows: 56.sp 57.Bl -enum -compact -offset indent 58.It 59Symbolic links used as file name arguments for system calls. 60.It 61Symbolic links specified as command line arguments to utilities that 62are not traversing a file tree. 63.It 64Symbolic links encountered by utilities that are traversing a file tree 65(either specified on the command line or encountered as part of the 66file hierarchy walk). 67.El 68.Ss System calls. 69The first area is symbolic links used as file name arguments for 70system calls. 71.Pp 72Except as noted below, all system calls follow symbolic links. 73For example, if there were a symbolic link 74.Dq Li slink 75which pointed to a file named 76.Dq Li afile , 77the system call 78.Dq Li open("slink" ...) 79would return a file descriptor to the file 80.Dq afile . 81.Pp 82There are four system calls that do not follow links, and which operate 83on the symbolic link itself. 84They are: 85.Xr lstat 2 , 86.Xr readlink 2 , 87.Xr rename 2 , 88and 89.Xr unlink 2 . 90Because 91.Xr remove 3 92is an alias for 93.Xr unlink 2 , 94it also does not follow symbolic links. 95.Pp 96Unlike other filesystem objects, symbolic links do not have an owner, 97group, permissions, access and modification times, etc. 98The only attributes returned from an 99.Xr lstat 2 100that refer to the symbolic link itself are the file type (S_IFLNK), 101size, blocks, and link count (always 1). 102The other attributes are filled in from the directory that contains 103the link. 104For portability reasons, you should be aware that other implementations 105(including historic implementations of 4BSD), implement symbolic links 106such that they have the same attributes as any other file. 107.Pp 108The 109.Bx 4.4 110system differs from historical 4BSD systems in that the system call 111.Xr chown 2 112has been changed to follow symbolic links. 113.Ss Commands not traversing a file tree. 114The second area is symbolic links, specified as command line file 115name arguments, to commands which are not traversing a file tree. 116.Pp 117Except as noted below, commands follow symbolic links named as command 118line arguments. 119For example, if there were a symbolic link 120.Dq Li slink 121which pointed to a file named 122.Dq Li afile , 123the command 124.Dq Li cat slink 125would display the contents of the file 126.Dq Li afile . 127.Pp 128It is important to realize that this rule includes commands which may 129optionally traverse file trees, e.g. the command 130.Dq Li "chown file" 131is included in this rule, while the command 132.Dq Li "chown -R file" 133is not. 134(The latter is described in the third area, below.) 135.Pp 136If it is explicitly intended that the command operate on the symbolic 137link instead of following the symbolic link, e.g., it is desired that 138.Dq Li "file slink" 139display the type of file that 140.Dq Li slink 141is, whether it is a symbolic link or not, the 142.Fl h 143option should be used. 144In the above example, 145.Dq Li "file slink" 146would report the type of the file referenced by 147.Dq Li slink , 148while 149.Dq Li "file -h slink" 150would report that 151.Dq Li slink 152was a symbolic link. 153.Pp 154There are three exceptions to this rule. 155The 156.Xr mv 1 157and 158.Xr rm 1 159commands do not follow symbolic links named as arguments, 160but respectively attempt to rename and delete them. 161(Note, if the symbolic link references a file via a relative path, 162moving it to another directory may very well cause it to stop working, 163since the path may no longer be correct.) 164.Pp 165The 166.Xr ls 1 167command is also an exception to this rule. 168For compatibility with historic systems (when 169.Nm ls 170is not doing a tree walk, i.e. the 171.Fl R 172option is not specified), 173the 174.Nm ls 175command follows symbolic links named as arguments if the 176.Fl L 177option is specified, 178or if the 179.Fl F , 180.Fl d 181or 182.Fl l 183options are not specified. 184(If the 185.Fl L 186option is specified, 187.Nm ls 188always follows symbolic links. 189.Nm Ls 190is the only command where the 191.Fl L 192option affects its behavior even though it is not doing a walk of 193a file tree.) 194.Pp 195The 196.Bx 4.4 197system differs from historical 4BSD systems in that the 198.Nm chown , 199.Nm chgrp 200and 201.Nm file 202commands follow symbolic links specified on the command line. 203.Ss Commands traversing a file tree. 204The following commands either optionally or always traverse file trees: 205.Xr chflags 1 , 206.Xr chgrp 1 , 207.Xr chmod 1 , 208.Xr cp 1 , 209.Xr du 1 , 210.Xr find 1 , 211.Xr ls 1 , 212.Xr pax 1 , 213.Xr rm 1 , 214.Xr tar 1 215and 216.Xr chown 8 . 217.Pp 218It is important to realize that the following rules apply equally to 219symbolic links encountered during the file tree traversal and symbolic 220links listed as command line arguments. 221.Pp 222The first rule applies to symbolic links that reference files that are 223not of type directory. 224Operations that apply to symbolic links are performed on the links 225themselves, but otherwise the links are ignored. 226.Pp 227For example, the command 228.Dq Li "chown -R user slink directory" 229will ignore 230.Dq Li slink , 231because symbolic links in this system do not have owners. 232Any symbolic links encountered during the tree traversal will also be 233ignored. 234The command 235.Dq Li "rm -r slink directory" 236will remove 237.Dq Li slink , 238as well as any symbolic links encountered in the tree traversal of 239.Dq Li directory , 240because symbolic links may be removed. 241In no case will either 242.Nm chown 243or 244.Nm rm 245affect the file which 246.Dq Li slink 247references in any way. 248.Pp 249The second rule applies to symbolic links that reference files of type 250directory. 251Symbolic links which reference files of type directory are never 252.Dq followed 253by default. 254This is often referred to as a 255.Dq physical 256walk, as opposed to a 257.Dq logical 258walk (where symbolic links referencing directories are followed). 259.Pp 260As consistently as possible, you can make commands doing a file tree 261walk follow any symbolic links named on the command line, regardless 262of the type of file they reference, by specifying the 263.Fl H 264(for 265.Dq half\-logical ) 266flag. 267This flag is intended to make the command line name space look 268like the logical name space. 269(Note, for commands that do not always do file tree traversals, the 270.Fl H 271flag will be ignored if the 272.Fl R 273flag is not also specified.) 274.Pp 275For example, the command 276.Dq Li "chown -HR user slink" 277will traverse the file hierarchy rooted in the file pointed to by 278.Dq Li slink . 279Note, the 280.Fl H 281is not the same as the previously discussed 282.Fl h 283flag. 284The 285.Fl H 286flag causes symbolic links specified on the command line to be 287dereferenced both for the purposes of the action to be performed 288and the tree walk, and it is as if the user had specified the 289name of the file to which the symbolic link pointed. 290.Pp 291As consistently as possible, you can make commands doing a file tree 292walk follow any symbolic links named on the command line, as well as 293any symbolic links encountered during the traversal, regardless of 294the type of file they reference, by specifying the 295.Fl L 296(for 297.Dq logical ) 298flag. 299This flag is intended to make the entire name space look like 300the logical name space. 301(Note, for commands that do not always do file tree traversals, the 302.Fl L 303flag will be ignored if the 304.Fl R 305flag is not also specified.) 306.Pp 307For example, the command 308.Dq Li "chown -LR user slink" 309will change the owner of the file referenced by 310.Dq Li slink . 311If 312.Dq Li slink 313references a directory, 314.Nm chown 315will traverse the file hierarchy rooted in the directory that it 316references. 317In addition, if any symbolic links are encountered in any file tree that 318.Nm chown 319traverses, they will be treated in the same fashion as 320.Dq Li slink . 321.Pp 322As consistently as possible, you can specify the default behavior by 323specifying the 324.Fl P 325(for 326.Dq physical ) 327flag. 328This flag is intended to make the entire name space look like the 329physical name space. 330.Pp 331For commands that do not by default do file tree traversals, the 332.Fl H , 333.Fl L 334and 335.Fl P 336flags are ignored if the 337.Fl R 338flag is not also specified. 339In addition, you may specify the 340.Fl H , 341.Fl L 342and 343.Fl P 344options more than once; the last one specified determines the 345command's behavior. 346This is intended to permit you to alias commands to behave one way 347or the other, and then override that behavior on the command line. 348.Pp 349The 350.Xr ls 1 351and 352.Xr rm 1 353commands have exceptions to these rules. 354The 355.Nm rm 356command operates on the symbolic link, and not the file it references, 357and therefore never follows a symbolic link. 358The 359.Nm rm 360command does not support the 361.Fl H , 362.Fl L 363or 364.Fl P 365options. 366.Pp 367To maintain compatibility with historic systems, 368the 369.Nm ls 370command never follows symbolic links unless the 371.Fl L 372flag is specified. 373If the 374.Fl L 375flag is specified, 376.Nm ls 377follows all symbolic links, 378regardless of their type, 379whether specified on the command line or encountered in the tree walk. 380The 381.Nm ls 382command does not support the 383.Fl H 384or 385.Fl P 386options. 387.Sh SEE ALSO 388.Xr chflags 1 , 389.Xr chgrp 1 , 390.Xr chmod 1 , 391.Xr cp 1 , 392.Xr du 1 , 393.Xr find 1 , 394.Xr ln 1 , 395.Xr ls 1 , 396.Xr mv 1 , 397.Xr pax 1 , 398.Xr rm 1 , 399.Xr tar 1 , 400.Xr lstat 2 , 401.Xr readlink 2 , 402.Xr rename 2 , 403.Xr unlink 2 , 404.Xr fts 3 , 405.Xr remove 3 , 406.Xr chown 8 407