1.\" $NetBSD: symlink.7,v 1.17 2009/06/26 15:50:17 christos 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. Neither the name of the University nor the names of its contributors 15.\" may be used to endorse or promote products derived from this software 16.\" without specific prior written permission. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 28.\" SUCH DAMAGE. 29.\" 30.\" @(#)symlink.7 8.3 (Berkeley) 3/31/94 31.\" 32.Dd June 26, 2009 33.Dt SYMLINK 7 34.Os 35.Sh NAME 36.Nm symlink 37.Nd symbolic link handling 38.Sh DESCRIPTION 39Symbolic links are files that act as pointers to other files. 40To understand their behavior, you must first understand how hard links 41work. 42.Pp 43A hard link to a file is indistinguishable from the original file because 44it is a reference to the object underlying the original file name. 45Changes to a file are independent of the name used to reference the 46file. 47Hard links may not refer to directories and may not reference files 48on different file systems. 49.Pp 50A symbolic link contains the name of the file to which it is linked, 51i.e. 52it is a pointer to another name, and not to an underlying object. 53For this reason, symbolic links may reference directories and may span 54file systems. 55.Pp 56Because a symbolic link and its referenced object coexist in the filesystem 57name space, confusion can arise in distinguishing between the link itself 58and the referenced object. 59Historically, commands and system calls have adopted their own link 60following conventions in a somewhat ad-hoc fashion. 61Rules for more a uniform approach, as they are implemented in this system, 62are outlined here. 63It is important that local applications conform to these rules, too, 64so that the user interface can be as consistent as possible. 65.Pp 66Symbolic links are handled either by operating on the link itself, 67or by operating on the object referenced by the link. 68In the latter case, 69an application or system call is said to 70.Qq follow 71the link. 72.Pp 73Symbolic links may reference other symbolic links, 74in which case the links are dereferenced until an object that is 75not a symbolic link is found, 76a symbolic link which references a file which doesn't exist is found, 77or a loop is detected. 78Loop detection is done by placing an upper limit on the number of 79links that may be followed, and an error results if this limit is 80exceeded. 81.Pp 82There are three separate areas that need to be discussed. 83They are as follows: 84.Pp 85.Bl -enum -compact -offset indent 86.It 87Symbolic links used as file name arguments for system calls. 88.It 89Symbolic links specified as command line arguments to utilities that 90are not traversing a file tree. 91.It 92Symbolic links encountered by utilities that are traversing a file tree 93(either specified on the command line or encountered as part of the 94file hierarchy walk). 95.El 96.Ss System calls 97The first area is symbolic links used as file name arguments for 98system calls. 99.Pp 100Except as noted below, all system calls follow symbolic links. 101For example, if there were a symbolic link 102.Qq Li slink 103which pointed to a file named 104.Qq Li afile , 105the system call 106.Qq Li open("slink" ...) 107would return a file descriptor to the file 108.Qq afile . 109.Pp 110There are eight system calls that do not follow links, and which operate 111on the symbolic link itself. 112They are: 113.Xr lchflags 2 , 114.Xr lchmod 2 , 115.Xr lchown 2 , 116.Xr lstat 2 , 117.Xr lutimes 2 , 118.Xr readlink 2 , 119.Xr rename 2 , 120and 121.Xr unlink 2 . 122Because 123.Xr remove 3 124is an alias for 125.Xr unlink 2 , 126it also does not follow symbolic links. 127.Pp 128The 129.Bx 4.4 130system differs from historical 131.Bx 4 132systems in that the system call 133.Xr chown 2 134has been changed to follow symbolic links. 135.Pp 136If the filesystem is mounted with the 137.Em symperm 138.Xr mount 8 139option, the symbolic link file permission bits have the following effects: 140.Pp 141The 142.Xr readlink 2 143system call requires read permissions on the symbolic link. 144.Pp 145System calls that follow symbolic links will fail without execute/search 146permissions on all the symbolic links followed. 147.Pp 148The write, sticky, set-user-ID-on-execution and set-group-ID-on-execution 149symbolic link mode bits have no effect on any system calls 150.Po 151including 152.Xr execve 2 153.Pc . 154.Ss Commands not traversing a file tree 155The second area is symbolic links, specified as command line file 156name arguments, to commands which are not traversing a file tree. 157.Pp 158Except as noted below, commands follow symbolic links named as command 159line arguments. 160For example, if there were a symbolic link 161.Qq Li slink 162which pointed to a file named 163.Qq Li afile , 164the command 165.Qq Li cat slink 166would display the contents of the file 167.Qq Li afile . 168.Pp 169It is important to realize that this rule includes commands which may 170optionally traverse file trees, e.g. 171the command 172.Qq Li "chown file" 173is included in this rule, while the command 174.Qq 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.Qq Li "file slink" 181display the type of file that 182.Qq Li slink 183is, whether it is a symbolic link or not, the 184.Fl h 185option should be used. 186In the above example, 187.Qq Li "file slink" 188would report the type of the file referenced by 189.Qq Li slink , 190while 191.Qq Li "file -h slink" 192would report that 193.Qq Li slink 194was a symbolic link. 195.Pp 196There are three 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. 213the 214.Fl R 215option is not specified), 216the 217.Nm ls 218command follows symbolic links named as arguments if the 219.Fl L 220option is specified, 221or if the 222.Fl F , 223.Fl d 224or 225.Fl l 226options are not specified. 227(If the 228.Fl L 229option is specified, 230.Nm ls 231always follows symbolic links. 232.Nm ls 233is the only command where the 234.Fl L 235option affects its behavior even though it is not doing a walk of 236a file tree). 237.Pp 238The 239.Bx 4.4 240system differs from historical 241.Bx 4 242systems in that the 243.Nm chown , 244.Nm chgrp 245and 246.Nm file 247commands follow symbolic links specified on the command line. 248.Ss Commands traversing a file tree 249The following commands either optionally or always traverse file trees: 250.Xr chflags 1 , 251.Xr chgrp 1 , 252.Xr chmod 1 , 253.Xr cp 1 , 254.Xr du 1 , 255.Xr find 1 , 256.Xr ls 1 , 257.Xr pax 1 , 258.Xr rm 1 , 259.Xr tar 1 260and 261.Xr chown 8 . 262.Pp 263It is important to realize that the following rules apply equally to 264symbolic links encountered during the file tree traversal and symbolic 265links listed as command line arguments. 266.Pp 267The first rule applies to symbolic links that reference files that are 268not of type directory. 269Operations that apply to symbolic links are performed on the links 270themselves, but otherwise the links are ignored. 271.Pp 272For example, the command 273.Qq Li "chown -R user slink directory" 274will ignore 275.Qq Li slink , 276because the 277.Fl h 278flag must be used to change owners of symbolic links. 279Any symbolic links encountered during the tree traversal will also be 280ignored. 281The command 282.Qq Li "rm -r slink directory" 283will remove 284.Qq Li slink , 285as well as any symbolic links encountered in the tree traversal of 286.Qq Li directory , 287because symbolic links may be removed. 288In no case will either 289.Nm chown 290or 291.Nm rm 292affect the file which 293.Qq 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.Qq followed 300by default. 301This is often referred to as a 302.Qq physical 303walk, as opposed to a 304.Qq 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.Qq 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.Qq Li "chown -HR user slink" 324will traverse the file hierarchy rooted in the file pointed to by 325.Qq 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.Qq 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.Qq Li "chown -LR user slink" 356will change the owner of the file referenced by 357.Qq Li slink . 358If 359.Qq 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.Qq Li slink . 368.Pp 369As consistently as possible, you can specify the default behavior by 370specifying the 371.Fl P 372(for 373.Qq 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 never follows symbolic links unless the 418.Fl L 419flag is specified. 420If the 421.Fl L 422flag is specified, 423.Nm ls 424follows all symbolic links, 425regardless of their type, 426whether specified on the command line or encountered in the tree walk. 427The 428.Nm ls 429command does not support the 430.Fl H 431or 432.Fl P 433options. 434.Sh MAGIC SYMLINKS 435Magic symlinks can be enabled by setting 436.Dq vfs.generic.magiclinks 437with 438.Xr sysctl 8 . 439When magic symlinks are enabled 440.Dq magic 441patterns in symlinks are expanded. 442Those patterns begin with 443.Dq @ 444.Pq an at-sign , 445and end at the end of the pathname component 446.Po 447i.e. at the next 448.Dq / , 449or at the end of the symbolic link if there are no more slashes 450.Pc . 451.Pp 452To illustrate the pattern matching rules, assume that 453.Dq @foo 454is a valid magic string: 455.Pp 456.Bl -tag -width @foo/barxxxxx -offset indent -compact 457.It @foo 458would be matched 459.It @foo/bar 460would be matched 461.It bar@foo 462would be matched 463.It @foobar 464would not be matched 465.El 466.Pp 467Magic strings may also be delimited with 468.Sq { 469and 470.Sq } 471characters, allowing for more complex patterns in symbolic links such as: 472.Bd -literal -offset indent 473@{var1}-@{var2}.@{var3} 474.Ed 475.Pp 476The following patterns are supported: 477.Bl -tag -width @machine_arch 478.It @domainname 479Expands to the machine's domain name, as set by 480.Xr setdomainname 3 . 481.It @hostname 482Expands to the machine's host name, as set by 483.Xr sethostname 3 . 484.It @emul 485Expands to the name of the current process's emulation. 486.It @kernel_ident 487Expands to the name of the 488.Xr config 1 489file used to generate the running kernel. 490.It @machine 491Expands to the value of 492.Li MACHINE 493for the system 494.Po 495equivalent to the output of 496.Dq uname -m 497.Pc . 498.It @machine_arch 499Expands to the value of 500.Li MACHINE_ARCH 501for the system 502.Po 503equivalent to the output of 504.Dq uname -p 505.Pc . 506.It @osrelease 507Expands to the operating system release of the running kernel 508.Po 509equivalent to the output of 510.Dq uname -r 511.Pc . 512.It @ostype 513Expands to the operating system type of the running kernel 514.Po 515equivalent to the output of 516.Dq uname -s 517.Pc . 518This will always be 519.Dq NetBSD 520on 521.Nx 522systems. 523.It @ruid 524Expands to the real user-id of the process. 525.It @uid 526Expands to the effective user-id of the process. 527.It @rgid 528Expands to the real group-id of the process. 529.It @gid 530Expands to the effective group-id of the process. 531.El 532.Sh SEE ALSO 533.Xr chflags 1 , 534.Xr chgrp 1 , 535.Xr chmod 1 , 536.Xr cp 1 , 537.Xr du 1 , 538.Xr find 1 , 539.Xr ln 1 , 540.Xr ls 1 , 541.Xr mv 1 , 542.Xr pax 1 , 543.Xr rm 1 , 544.Xr tar 1 , 545.Xr uname 1 , 546.Xr chown 2 , 547.Xr execve 2 , 548.Xr lchflags 2 , 549.Xr lchmod 2 , 550.Xr lchown 2 , 551.Xr lstat 2 , 552.Xr lutimes 2 , 553.Xr mount 2 , 554.Xr readlink 2 , 555.Xr rename 2 , 556.Xr symlink 2 , 557.Xr unlink 2 , 558.Xr fts 3 , 559.Xr remove 3 , 560.Xr chown 8 , 561.Xr mount 8 562.Sh HISTORY 563Magic symlinks appeared in 564.Nx 4.0 . 565