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. (The 228.Nm ls 229command is the only command where the 230.Fl H 231and 232.Fl L 233options affect its behavior even though it is not doing a walk of 234a file tree.) 235.Pp 236The 237.Xr file 1 238command is also an exception to this rule. 239The 240.Xr file 1 241command does not follow symbolic links named as argument by default. 242The 243.Xr file 1 244command does follow symbolic links named as argument if 245.Fl L 246option is specified. 247.Pp 248The 249.Bx 4.4 250system differs from historical 251.Bx 4 252systems in that the 253.Nm chown 254and 255.Nm chgrp 256commands follow symbolic links specified on the command line. 257.Ss Commands traversing a file tree. 258The following commands either optionally or always traverse file trees: 259.Xr chflags 1 , 260.Xr chgrp 1 , 261.Xr chmod 1 , 262.Xr cp 1 , 263.Xr du 1 , 264.Xr find 1 , 265.Xr ls 1 , 266.Xr pax 1 , 267.Xr rm 1 , 268.Xr tar 1 269and 270.Xr chown 8 . 271.Pp 272It is important to realize that the following rules apply equally to 273symbolic links encountered during the file tree traversal and symbolic 274links listed as command line arguments. 275.Pp 276The first rule applies to symbolic links that reference files that are 277not of type directory. 278Operations that apply to symbolic links are performed on the links 279themselves, but otherwise the links are ignored. 280.Pp 281The command 282.Dq Li "rm -r slink directory" 283will remove 284.Dq Li slink , 285as well as any symbolic links encountered in the tree traversal of 286.Dq Li directory , 287because symbolic links may be removed. 288In no case will 289.Nm rm 290affect the file which 291.Dq Li slink 292references in any way. 293.Pp 294The second rule applies to symbolic links that reference files of type 295directory. 296Symbolic links which reference files of type directory are never 297.Dq followed 298by default. 299This is often referred to as a 300.Dq physical 301walk, as opposed to a 302.Dq logical 303walk (where symbolic links referencing directories are followed). 304.Pp 305As consistently as possible, you can make commands doing a file tree 306walk follow any symbolic links named on the command line, regardless 307of the type of file they reference, by specifying the 308.Fl H 309(for 310.Dq half\-logical ) 311flag. 312This flag is intended to make the command line name space look 313like the logical name space. 314(Note, for commands that do not always do file tree traversals, the 315.Fl H 316flag will be ignored if the 317.Fl R 318flag is not also specified.) 319.Pp 320For example, the command 321.Dq Li "chown -HR user slink" 322will traverse the file hierarchy rooted in the file pointed to by 323.Dq Li slink . 324Note, the 325.Fl H 326is not the same as the previously discussed 327.Fl h 328flag. 329The 330.Fl H 331flag causes symbolic links specified on the command line to be 332dereferenced both for the purposes of the action to be performed 333and the tree walk, and it is as if the user had specified the 334name of the file to which the symbolic link pointed. 335.Pp 336As consistently as possible, you can make commands doing a file tree 337walk follow any symbolic links named on the command line, as well as 338any symbolic links encountered during the traversal, regardless of 339the type of file they reference, by specifying the 340.Fl L 341(for 342.Dq logical ) 343flag. 344This flag is intended to make the entire name space look like 345the logical name space. 346(Note, for commands that do not always do file tree traversals, the 347.Fl L 348flag will be ignored if the 349.Fl R 350flag is not also specified.) 351.Pp 352For example, the command 353.Dq Li "chown -LR user slink" 354will change the owner of the file referenced by 355.Dq Li slink . 356If 357.Dq Li slink 358references a directory, 359.Nm chown 360will traverse the file hierarchy rooted in the directory that it 361references. 362In addition, if any symbolic links are encountered in any file tree that 363.Nm chown 364traverses, they will be treated in the same fashion as 365.Dq Li slink . 366.Pp 367As consistently as possible, you can specify the default behavior by 368specifying the 369.Fl P 370(for 371.Dq physical ) 372flag. 373This flag is intended to make the entire name space look like the 374physical name space. 375.Pp 376For commands that do not by default do file tree traversals, the 377.Fl H , 378.Fl L 379and 380.Fl P 381flags are ignored if the 382.Fl R 383flag is not also specified. 384In addition, you may specify the 385.Fl H , 386.Fl L 387and 388.Fl P 389options more than once; the last one specified determines the 390command's behavior. 391This is intended to permit you to alias commands to behave one way 392or the other, and then override that behavior on the command line. 393.Pp 394The 395.Xr ls 1 396and 397.Xr rm 1 398commands have exceptions to these rules. 399The 400.Nm rm 401command operates on the symbolic link, and not the file it references, 402and therefore never follows a symbolic link. 403The 404.Nm rm 405command does not support the 406.Fl H , 407.Fl L 408or 409.Fl P 410options. 411.Pp 412To maintain compatibility with historic systems, 413the 414.Nm ls 415command acts a little differently. If you do not specify the 416.Fl F , 417.Fl d 418or 419.Fl l 420options, 421.Nm ls 422will follow symbolic links specified on the command line. If the 423.Fl L 424flag is specified, 425.Nm ls 426follows all symbolic links, 427regardless of their type, 428whether specified on the command line or encountered in the tree walk. 429.Sh SEE ALSO 430.Xr chflags 1 , 431.Xr chgrp 1 , 432.Xr chmod 1 , 433.Xr cp 1 , 434.Xr du 1 , 435.Xr find 1 , 436.Xr ln 1 , 437.Xr ls 1 , 438.Xr mv 1 , 439.Xr pax 1 , 440.Xr rm 1 , 441.Xr tar 1 , 442.Xr lchflags 2 , 443.Xr lchmod 2 , 444.Xr lchown 2 , 445.Xr lstat 2 , 446.Xr lutimes 2 , 447.Xr readlink 2 , 448.Xr rename 2 , 449.Xr symlink 2 , 450.Xr unlink 2 , 451.Xr fts 3 , 452.Xr remove 3 , 453.Xr chown 8 454