1.\" $NetBSD: symlink.7,v 1.4 2002/03/06 14:43:03 wiz 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 seven system calls that do not follow links, and which operate 115on the symbolic link itself. 116They are: 117.Xr lchmod 2 , 118.Xr lchown 2 , 119.Xr lstat 2 , 120.Xr lutimes 2 , 121.Xr readlink 2 , 122.Xr rename 2 , 123and 124.Xr unlink 2 . 125Because 126.Xr remove 3 127is an alias for 128.Xr unlink 2 , 129it also does not follow symbolic links. 130.Pp 131The 132.Bx 4.4 133system differs from historical 134.Bx 4 135systems in that the system call 136.Xr chown 2 137has been changed to follow symbolic links. 138.Pp 139If the filesystem is mounted with the 140.Em symperm 141.Xr mount 8 142option, the symbolic link file permission bits have the following effects: 143.Pp 144The 145.Xr readlink 2 146system call requires read permissions on the symbolic link. 147.Pp 148System calls that follow symbolic links will fail without execute/search 149permissions on all the symbolic links followed. 150.Pp 151The write, sticky, set-user-ID-on-execution and set-group-ID-on-execution 152symbolic link mode bits have no effect on any system calls 153.Po 154including 155.Xr execve 2 156.Pc . 157.Ss Commands not traversing a file tree 158The second area is symbolic links, specified as command line file 159name arguments, to commands which are not traversing a file tree. 160.Pp 161Except as noted below, commands follow symbolic links named as command 162line arguments. 163For example, if there were a symbolic link 164.Qq Li slink 165which pointed to a file named 166.Qq Li afile , 167the command 168.Qq Li cat slink 169would display the contents of the file 170.Qq Li afile . 171.Pp 172It is important to realize that this rule includes commands which may 173optionally traverse file trees, e.g. 174the command 175.Qq Li "chown file" 176is included in this rule, while the command 177.Qq Li "chown -R file" 178is not 179(The latter is described in the third area, below). 180.Pp 181If it is explicitly intended that the command operate on the symbolic 182link instead of following the symbolic link, e.g., it is desired that 183.Qq Li "file slink" 184display the type of file that 185.Qq Li slink 186is, whether it is a symbolic link or not, the 187.Fl h 188option should be used. 189In the above example, 190.Qq Li "file slink" 191would report the type of the file referenced by 192.Qq Li slink , 193while 194.Qq Li "file -h slink" 195would report that 196.Qq Li slink 197was a symbolic link. 198.Pp 199There are three exceptions to this rule. 200The 201.Xr mv 1 202and 203.Xr rm 1 204commands do not follow symbolic links named as arguments, 205but respectively attempt to rename and delete them. 206(Note, if the symbolic link references a file via a relative path, 207moving it to another directory may very well cause it to stop working, 208since the path may no longer be correct). 209.Pp 210The 211.Xr ls 1 212command is also an exception to this rule. 213For compatibility with historic systems (when 214.Nm ls 215is not doing a tree walk, i.e. 216the 217.Fl R 218option is not specified), 219the 220.Nm ls 221command follows symbolic links named as arguments if the 222.Fl L 223option is specified, 224or if the 225.Fl F , 226.Fl d 227or 228.Fl l 229options are not specified. 230(If the 231.Fl L 232option is specified, 233.Nm ls 234always follows symbolic links. 235.Nm ls 236is the only command where the 237.Fl L 238option affects its behavior even though it is not doing a walk of 239a file tree). 240.Pp 241The 242.Bx 4.4 243system differs from historical 244.Bx 4 245systems in that the 246.Nm chown , 247.Nm chgrp 248and 249.Nm file 250commands follow symbolic links specified on the command line. 251.Ss Commands traversing a file tree 252The following commands either optionally or always traverse file trees: 253.Xr chflags 1 , 254.Xr chgrp 1 , 255.Xr chmod 1 , 256.Xr cp 1 , 257.Xr du 1 , 258.Xr find 1 , 259.Xr ls 1 , 260.Xr pax 1 , 261.Xr rm 1 , 262.Xr tar 1 263and 264.Xr chown 8 . 265.Pp 266It is important to realize that the following rules apply equally to 267symbolic links encountered during the file tree traversal and symbolic 268links listed as command line arguments. 269.Pp 270The first rule applies to symbolic links that reference files that are 271not of type directory. 272Operations that apply to symbolic links are performed on the links 273themselves, but otherwise the links are ignored. 274.Pp 275For example, the command 276.Qq Li "chown -R user slink directory" 277will ignore 278.Qq Li slink , 279because the 280.Fl h 281flag must be used to change owners of symbolic links. 282Any symbolic links encountered during the tree traversal will also be 283ignored. 284The command 285.Qq Li "rm -r slink directory" 286will remove 287.Qq Li slink , 288as well as any symbolic links encountered in the tree traversal of 289.Qq Li directory , 290because symbolic links may be removed. 291In no case will either 292.Nm chown 293or 294.Nm rm 295affect the file which 296.Qq Li slink 297references in any way. 298.Pp 299The second rule applies to symbolic links that reference files of type 300directory. 301Symbolic links which reference files of type directory are never 302.Qq followed 303by default. 304This is often referred to as a 305.Qq physical 306walk, as opposed to a 307.Qq logical 308walk (where symbolic links referencing directories are followed). 309.Pp 310As consistently as possible, you can make commands doing a file tree 311walk follow any symbolic links named on the command line, regardless 312of the type of file they reference, by specifying the 313.Fl H 314(for 315.Qq half\-logical ) 316flag. 317This flag is intended to make the command line name space look 318like the logical name space. 319(Note, for commands that do not always do file tree traversals, the 320.Fl H 321flag will be ignored if the 322.Fl R 323flag is not also specified). 324.Pp 325For example, the command 326.Qq Li "chown -HR user slink" 327will traverse the file hierarchy rooted in the file pointed to by 328.Qq Li slink . 329Note, the 330.Fl H 331is not the same as the previously discussed 332.Fl h 333flag. 334The 335.Fl H 336flag causes symbolic links specified on the command line to be 337dereferenced both for the purposes of the action to be performed 338and the tree walk, and it is as if the user had specified the 339name of the file to which the symbolic link pointed. 340.Pp 341As consistently as possible, you can make commands doing a file tree 342walk follow any symbolic links named on the command line, as well as 343any symbolic links encountered during the traversal, regardless of 344the type of file they reference, by specifying the 345.Fl L 346(for 347.Qq logical ) 348flag. 349This flag is intended to make the entire name space look like 350the logical name space. 351(Note, for commands that do not always do file tree traversals, the 352.Fl L 353flag will be ignored if the 354.Fl R 355flag is not also specified). 356.Pp 357For example, the command 358.Qq Li "chown -LR user slink" 359will change the owner of the file referenced by 360.Qq Li slink . 361If 362.Qq Li slink 363references a directory, 364.Nm chown 365will traverse the file hierarchy rooted in the directory that it 366references. 367In addition, if any symbolic links are encountered in any file tree that 368.Nm chown 369traverses, they will be treated in the same fashion as 370.Qq Li slink . 371.Pp 372As consistently as possible, you can specify the default behavior by 373specifying the 374.Fl P 375(for 376.Qq physical ) 377flag. 378This flag is intended to make the entire name space look like the 379physical name space. 380.Pp 381For commands that do not by default do file tree traversals, the 382.Fl H , 383.Fl L 384and 385.Fl P 386flags are ignored if the 387.Fl R 388flag is not also specified. 389In addition, you may specify the 390.Fl H , 391.Fl L 392and 393.Fl P 394options more than once; the last one specified determines the 395command's behavior. 396This is intended to permit you to alias commands to behave one way 397or the other, and then override that behavior on the command line. 398.Pp 399The 400.Xr ls 1 401and 402.Xr rm 1 403commands have exceptions to these rules. 404The 405.Nm rm 406command operates on the symbolic link, and not the file it references, 407and therefore never follows a symbolic link. 408The 409.Nm rm 410command does not support the 411.Fl H , 412.Fl L 413or 414.Fl P 415options. 416.Pp 417To maintain compatibility with historic systems, 418the 419.Nm ls 420command never follows symbolic links unless the 421.Fl L 422flag is specified. 423If the 424.Fl L 425flag is specified, 426.Nm ls 427follows all symbolic links, 428regardless of their type, 429whether specified on the command line or encountered in the tree walk. 430The 431.Nm ls 432command does not support the 433.Fl H 434or 435.Fl P 436options. 437.Sh SEE ALSO 438.Xr chflags 1 , 439.Xr chgrp 1 , 440.Xr chmod 1 , 441.Xr cp 1 , 442.Xr du 1 , 443.Xr find 1 , 444.Xr ln 1 , 445.Xr ls 1 , 446.Xr mv 1 , 447.Xr pax 1 , 448.Xr rm 1 , 449.Xr tar 1 , 450.Xr chown 2 , 451.Xr execve 2 , 452.Xr lchmod 2 , 453.Xr lchown 2 , 454.Xr lstat 2 , 455.Xr lutimes 2 , 456.Xr mount 2 , 457.Xr readlink 2 , 458.Xr rename 2 , 459.Xr symlink 2 , 460.Xr unlink 2 , 461.Xr fts 3 , 462.Xr remove 3 , 463.Xr chown 8 , 464.Xr mount 8 465