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