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