1.\"- 2.\" Copyright (c) 1992, 1993, 1994 3.\" The Regents of the University of California. All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 4. Neither the name of the University nor the names of its contributors 14.\" may be used to endorse or promote products derived from this software 15.\" without specific prior written permission. 16.\" 17.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 18.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 19.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 20.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 21.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 22.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 23.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 24.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 25.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 26.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 27.\" SUCH DAMAGE. 28.\" 29.\" @(#)symlink.7 8.3 (Berkeley) 3/31/94 30.\" $FreeBSD$ 31.\" 32.Dd March 31, 1994 33.Dt SYMLINK 7 34.Os 35.Sh NAME 36.Nm symlink 37.Nd symbolic link handling 38.Sh SYMBOLIC LINK HANDLING 39Symbolic links are files that act as pointers to other files. 40To understand their behavior, you must first understand how hard links 41work. 42A hard link to a file is indistinguishable from the original file because 43it is a reference to the object underlying the original file name. 44Changes to a file are independent of the name used to reference the 45file. 46Hard links may not refer to directories and may not reference files 47on different file systems. 48A symbolic link contains the name of the file to which it is linked, 49i.e., it is a pointer to another name, and not to an underlying object. 50For this reason, symbolic links may reference directories and may span 51file systems. 52.Pp 53Because a symbolic link and its referenced object coexist in the file system 54name space, confusion can arise in distinguishing between the link itself 55and the referenced object. 56Historically, commands and system calls have adopted their own link 57following conventions in a somewhat ad-hoc fashion. 58Rules for more a uniform approach, as they are implemented in this system, 59are outlined here. 60It is important that local applications conform to these rules, too, 61so that the user interface can be as consistent as possible. 62.Pp 63Symbolic links are handled either by operating on the link itself, 64or by operating on the object referenced by the link. 65In the latter case, 66an application or system call is said to 67.Dq follow 68the link. 69Symbolic links may reference other symbolic links, 70in which case the links are dereferenced until an object that is 71not a symbolic link is found, 72a symbolic link which references a file which does not exist is found, 73or a loop is detected. 74(Loop detection is done by placing an upper limit on the number of 75links that may be followed, and an error results if this limit is 76exceeded.) 77.Pp 78There are three separate areas that need to be discussed. 79They are as follows: 80.Pp 81.Bl -enum -compact -offset indent 82.It 83Symbolic links used as file name arguments for system calls. 84.It 85Symbolic links specified as command line arguments to utilities that 86are not traversing a file tree. 87.It 88Symbolic links encountered by utilities that are traversing a file tree 89(either specified on the command line or encountered as part of the 90file hierarchy walk). 91.El 92.Ss System calls. 93The first area is symbolic links used as file name arguments for 94system calls. 95.Pp 96Except as noted below, all system calls follow symbolic links. 97For example, if there were a symbolic link 98.Dq Li slink 99which pointed to a file named 100.Dq Li afile , 101the system call 102.Dq Li open("slink" ...\&) 103would return a file descriptor to the file 104.Dq afile . 105.Pp 106There are nine system calls that do not follow links, and which operate 107on the symbolic link itself. 108They are: 109.Xr lchflags 2 , 110.Xr lchmod 2 , 111.Xr lchown 2 , 112.Xr lstat 2 , 113.Xr lutimes 2 , 114.Xr readlink 2 , 115.Xr rename 2 , 116.Xr rmdir 2 , 117and 118.Xr unlink 2 . 119Because 120.Xr remove 3 121is an alias for 122.Xr unlink 2 , 123it also does not follow symbolic links. 124When 125.Xr rmdir 2 126is applied to a symbolic link, it fails with the error 127.Er ENOTDIR . 128.Pp 129The owner and group of an existing symbolic link can be changed by 130means of the 131.Xr lchown 2 132system call. 133The flags, access permissions, owner/group and modification time of 134an existing symbolic link can be changed by means of the 135.Xr lchflags 2 , 136.Xr lchmod 2 , 137.Xr lchown 2 , 138and 139.Xr lutimes 2 140system calls, respectively. 141Of these, only the flags are used by the system; 142the access permissions and ownership are ignored. 143.Pp 144The 145.Bx 4.4 146system differs from historical 147.Bx 4 148systems in that the system call 149.Xr chown 2 150has been changed to follow symbolic links. 151The 152.Xr lchown 2 153system call was added later when the limitations of the new 154.Xr chown 2 155became apparent. 156.Ss Commands not traversing a file tree. 157The second area is symbolic links, specified as command line file 158name arguments, to commands which are not traversing a file tree. 159.Pp 160Except as noted below, commands follow symbolic links named as command 161line arguments. 162For example, if there were a symbolic link 163.Dq Li slink 164which pointed to a file named 165.Dq Li afile , 166the command 167.Dq Li cat slink 168would display the contents of the file 169.Dq Li afile . 170.Pp 171It is important to realize that this rule includes commands which may 172optionally traverse file trees, e.g.\& the command 173.Dq Li "chown file" 174is included in this rule, while the command 175.Dq Li "chown -R file" 176is not. 177(The latter is described in the third area, below.) 178.Pp 179If it is explicitly intended that the command operate on the symbolic 180link instead of following the symbolic link, e.g., it is desired that 181.Dq Li "chown slink" 182change the ownership of the file that 183.Dq Li slink 184is, whether it is a symbolic link or not, the 185.Fl h 186option should be used. 187In the above example, 188.Dq Li "chown root slink" 189would change the ownership of the file referenced by 190.Dq Li slink , 191while 192.Dq Li "chown -h root slink" 193would change the ownership of 194.Dq Li slink 195itself. 196.Pp 197There are four exceptions to this rule. 198The 199.Xr mv 1 200and 201.Xr rm 1 202commands do not follow symbolic links named as arguments, 203but respectively attempt to rename and delete them. 204(Note, if the symbolic link references a file via a relative path, 205moving it to another directory may very well cause it to stop working, 206since the path may no longer be correct.) 207.Pp 208The 209.Xr ls 1 210command is also an exception to this rule. 211For compatibility with historic systems (when 212.Nm ls 213is not doing a tree walk, i.e., the 214.Fl R 215option is not specified), 216the 217.Nm ls 218command follows symbolic links named as arguments if the 219.Fl H 220or 221.Fl L 222option is specified, 223or if the 224.Fl F , 225.Fl d 226or 227.Fl l 228options are not specified. 229(The 230.Nm ls 231command is the only command where the 232.Fl H 233and 234.Fl L 235options affect its behavior even though it is not doing a walk of 236a file tree.) 237.Pp 238The 239.Xr file 1 240command is also an exception to this rule. 241The 242.Xr file 1 243command does not follow symbolic links named as argument by default. 244The 245.Xr file 1 246command does follow symbolic links named as argument if 247.Fl L 248option is specified. 249.Pp 250The 251.Bx 4.4 252system differs from historical 253.Bx 4 254systems in that the 255.Nm chown 256and 257.Nm chgrp 258commands follow symbolic links specified on the command line. 259.Ss Commands traversing a file tree. 260The following commands either optionally or always traverse file trees: 261.Xr chflags 1 , 262.Xr chgrp 1 , 263.Xr chmod 1 , 264.Xr cp 1 , 265.Xr du 1 , 266.Xr find 1 , 267.Xr ls 1 , 268.Xr pax 1 , 269.Xr rm 1 , 270.Xr tar 1 271and 272.Xr chown 8 . 273.Pp 274It is important to realize that the following rules apply equally to 275symbolic links encountered during the file tree traversal and symbolic 276links listed as command line arguments. 277.Pp 278The first rule applies to symbolic links that reference files that are 279not of type directory. 280Operations that apply to symbolic links are performed on the links 281themselves, but otherwise the links are ignored. 282.Pp 283The command 284.Dq Li "rm -r slink directory" 285will remove 286.Dq Li slink , 287as well as any symbolic links encountered in the tree traversal of 288.Dq Li directory , 289because symbolic links may be removed. 290In no case will 291.Nm rm 292affect the file which 293.Dq Li slink 294references in any way. 295.Pp 296The second rule applies to symbolic links that reference files of type 297directory. 298Symbolic links which reference files of type directory are never 299.Dq followed 300by default. 301This is often referred to as a 302.Dq physical 303walk, as opposed to a 304.Dq logical 305walk (where symbolic links referencing directories are followed). 306.Pp 307As consistently as possible, you can make commands doing a file tree 308walk follow any symbolic links named on the command line, regardless 309of the type of file they reference, by specifying the 310.Fl H 311(for 312.Dq half\-logical ) 313flag. 314This flag is intended to make the command line name space look 315like the logical name space. 316(Note, for commands that do not always do file tree traversals, the 317.Fl H 318flag will be ignored if the 319.Fl R 320flag is not also specified.) 321.Pp 322For example, the command 323.Dq Li "chown -HR user slink" 324will traverse the file hierarchy rooted in the file pointed to by 325.Dq Li slink . 326Note, the 327.Fl H 328is not the same as the previously discussed 329.Fl h 330flag. 331The 332.Fl H 333flag causes symbolic links specified on the command line to be 334dereferenced both for the purposes of the action to be performed 335and the tree walk, and it is as if the user had specified the 336name of the file to which the symbolic link pointed. 337.Pp 338As consistently as possible, you can make commands doing a file tree 339walk follow any symbolic links named on the command line, as well as 340any symbolic links encountered during the traversal, regardless of 341the type of file they reference, by specifying the 342.Fl L 343(for 344.Dq logical ) 345flag. 346This flag is intended to make the entire name space look like 347the logical name space. 348(Note, for commands that do not always do file tree traversals, the 349.Fl L 350flag will be ignored if the 351.Fl R 352flag is not also specified.) 353.Pp 354For example, the command 355.Dq Li "chown -LR user slink" 356will change the owner of the file referenced by 357.Dq Li slink . 358If 359.Dq Li slink 360references a directory, 361.Nm chown 362will traverse the file hierarchy rooted in the directory that it 363references. 364In addition, if any symbolic links are encountered in any file tree that 365.Nm chown 366traverses, they will be treated in the same fashion as 367.Dq Li slink . 368.Pp 369As consistently as possible, you can specify the default behavior by 370specifying the 371.Fl P 372(for 373.Dq physical ) 374flag. 375This flag is intended to make the entire name space look like the 376physical name space. 377.Pp 378For commands that do not by default do file tree traversals, the 379.Fl H , 380.Fl L 381and 382.Fl P 383flags are ignored if the 384.Fl R 385flag is not also specified. 386In addition, you may specify the 387.Fl H , 388.Fl L 389and 390.Fl P 391options more than once; the last one specified determines the 392command's behavior. 393This is intended to permit you to alias commands to behave one way 394or the other, and then override that behavior on the command line. 395.Pp 396The 397.Xr ls 1 398and 399.Xr rm 1 400commands have exceptions to these rules. 401The 402.Nm rm 403command operates on the symbolic link, and not the file it references, 404and therefore never follows a symbolic link. 405The 406.Nm rm 407command does not support the 408.Fl H , 409.Fl L 410or 411.Fl P 412options. 413.Pp 414To maintain compatibility with historic systems, 415the 416.Nm ls 417command acts a little differently. 418If you do not specify the 419.Fl F , 420.Fl d 421or 422.Fl l 423options, 424.Nm ls 425will follow symbolic links specified on the command line. 426If the 427.Fl L 428flag is specified, 429.Nm ls 430follows all symbolic links, 431regardless of their type, 432whether specified on the command line or encountered in the tree walk. 433.Sh SEE ALSO 434.Xr chflags 1 , 435.Xr chgrp 1 , 436.Xr chmod 1 , 437.Xr cp 1 , 438.Xr du 1 , 439.Xr find 1 , 440.Xr ln 1 , 441.Xr ls 1 , 442.Xr mv 1 , 443.Xr pax 1 , 444.Xr rm 1 , 445.Xr tar 1 , 446.Xr lchflags 2 , 447.Xr lchmod 2 , 448.Xr lchown 2 , 449.Xr lstat 2 , 450.Xr lutimes 2 , 451.Xr readlink 2 , 452.Xr rename 2 , 453.Xr symlink 2 , 454.Xr unlink 2 , 455.Xr fts 3 , 456.Xr remove 3 , 457.Xr chown 8 458