1.\" $NetBSD: symlink.7,v 1.29 2019/03/25 19:24:30 maxv 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 March 25, 2019 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 eleven 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 lpathconf 2 , 117.Xr lstat 2 , 118.Xr lutimes 2 , 119.Xr readlink 2 , 120.Xr readlinkat 2 , 121.Xr rename 2 , 122.Xr renameat 2 , 123.Xr unlinkat 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. 131When 132.Xr rmdir 2 133or 134.Xr unlinkat 2 135with the 136.Dv AT_REMOVEDIR 137flag 138is applied to a symbolic link, it fails with the error 139.Er ENOTDIR . 140.Pp 141The 142.Xr linkat 2 143system call does not follow symbolic links 144unless given the 145.Dv AT_SYMLINK_FOLLOW 146flag. 147.Pp 148The following system calls follow symbolic links 149unless given the 150.Dv AT_SYMLINK_NOFOLLOW 151flag: 152.\" .Xr chflagsat 2 , 153.Xr fchmodat 2 , 154.Xr fchownat 2 , 155.Xr fstatat 2 , 156and 157.Xr utimensat 2 . 158.Pp 159The owner and group of an existing symbolic link can be changed by 160means of the 161.Xr lchown 2 162system call. 163The flags, access permissions, owner/group and modification time of 164an existing symbolic link can be changed by means of the 165.Xr lchflags 2 , 166.Xr lchmod 2 , 167.Xr lchown 2 , 168and 169.Xr lutimes 2 170system calls, respectively. 171Of these, only the flags and ownership are used by the system; 172the access permissions are ignored. 173.Pp 174The 175.Bx 4.4 176system differs from historical 177.Bx 4 178systems in that the system call 179.Xr chown 2 180has been changed to follow symbolic links. 181The 182.Xr lchown 2 183system call was added later when the limitations of the new 184.Xr chown 2 185became apparent. 186.Pp 187If the filesystem is mounted with the 188.Em symperm 189.Xr mount 8 190option, the symbolic link file permission bits have the following effects: 191.Pp 192The 193.Xr readlink 2 194system call requires read permissions on the symbolic link. 195.Pp 196System calls that follow symbolic links will fail without execute/search 197permissions on all the symbolic links followed. 198.Pp 199The write, sticky, set-user-ID-on-execution and set-group-ID-on-execution 200symbolic link mode bits have no effect on any system calls 201.Po 202including 203.Xr execve 2 204.Pc . 205.Ss Commands not traversing a file tree 206The second area is symbolic links, specified as command line file 207name arguments, to commands which are not traversing a file tree. 208.Pp 209Except as noted below, commands follow symbolic links named as command 210line arguments. 211For example, if there were a symbolic link 212.Qq Li slink 213which pointed to a file named 214.Qq Li afile , 215the command 216.Qq Li cat slink 217would display the contents of the file 218.Qq Li afile . 219.Pp 220It is important to realize that this rule includes commands which may 221optionally traverse file trees, e.g. 222the command 223.Qq Li "chown file" 224is included in this rule, while the command 225.Qq Li "chown -R file" 226is not 227(The latter is described in the third area, below). 228.Pp 229If it is explicitly intended that the command operate on the symbolic 230link instead of following the symbolic link, e.g., it is desired that 231.Qq Li "file slink" 232display the type of file that 233.Qq Li slink 234is, whether it is a symbolic link or not, the 235.Fl h 236option should be used. 237In the above example, 238.Qq Li "file slink" 239would report the type of the file referenced by 240.Qq Li slink , 241while 242.Qq Li "file -h slink" 243would report that 244.Qq Li slink 245was a symbolic link. 246.Pp 247There are five exceptions to this rule. 248The 249.Xr mv 1 250and 251.Xr rm 1 252commands do not follow symbolic links named as arguments, 253but respectively attempt to rename and delete them. 254(Note, if the symbolic link references a file via a relative path, 255moving it to another directory may very well cause it to stop working, 256since the path may no longer be correct). 257.Pp 258The 259.Xr ls 1 260command is also an exception to this rule. 261For compatibility with historic systems (when 262.Nm ls 263is not doing a tree walk, i.e. 264the 265.Fl R 266option is not specified), 267the 268.Nm ls 269command follows symbolic links named as arguments if the 270.\" .Fl H 271.\" or 272.Fl L 273option is specified, 274or if the 275.Fl F , 276.Fl d , 277or 278.Fl l 279options are not specified. 280(If the 281.Fl L 282option is specified, 283.Nm ls 284always follows symbolic links. 285.Nm ls 286is the only command where the 287.\" .Fl H 288.\" and 289.Fl L 290option affects its behavior even though it is not doing a walk of 291a file tree). 292.Pp 293The 294.Xr file 1 295and 296.Xr stat 1 297commands are also exceptions to this rule. 298These 299commands do not follow symbolic links named as argument by default, 300but do follow symbolic links named as argument if the 301.Fl L 302option is specified. 303.Pp 304The 305.Bx 4.4 306system differs from historical 307.Bx 4 308systems in that the 309.Nm chown 310and 311.Nm chgrp 312commands follow symbolic links specified on the command line. 313.Ss Commands traversing a file tree 314The following commands either optionally or always traverse file trees: 315.Xr chflags 1 , 316.Xr chgrp 1 , 317.Xr chmod 1 , 318.Xr cp 1 , 319.Xr du 1 , 320.Xr find 1 , 321.Xr ls 1 , 322.Xr pax 1 , 323.Xr rm 1 , 324.Xr tar 1 , 325and 326.Xr chown 8 . 327.Pp 328It is important to realize that the following rules apply equally to 329symbolic links encountered during the file tree traversal and symbolic 330links listed as command line arguments. 331.Pp 332The first rule applies to symbolic links that reference files that are 333not of type directory. 334Operations that apply to symbolic links are performed on the links 335themselves, but otherwise the links are ignored. 336.Pp 337For example, the command 338.Qq Li "chown -R user slink directory" 339will ignore 340.Qq Li slink , 341because the 342.Fl h 343flag must be used to change owners of symbolic links. 344Any symbolic links encountered during the tree traversal will also be 345ignored. 346The command 347.Qq Li "rm -r slink directory" 348will remove 349.Qq Li slink , 350as well as any symbolic links encountered in the tree traversal of 351.Qq Li directory , 352because symbolic links may be removed. 353In no case will either 354.Nm chown 355or 356.Nm rm 357affect the file which 358.Qq Li slink 359references in any way. 360.Pp 361The second rule applies to symbolic links that reference files of type 362directory. 363Symbolic links which reference files of type directory are never 364.Qq followed 365by default. 366This is often referred to as a 367.Qq physical 368walk, as opposed to a 369.Qq logical 370walk (where symbolic links referencing directories are followed). 371.Pp 372As consistently as possible, you can make commands doing a file tree 373walk follow any symbolic links named on the command line, regardless 374of the type of file they reference, by specifying the 375.Fl H 376(for 377.Qq half\-logical ) 378flag. 379This flag is intended to make the command line name space look 380like the logical name space. 381(Note, for commands that do not always do file tree traversals, the 382.Fl H 383flag will be ignored if the 384.Fl R 385flag is not also specified). 386.Pp 387For example, the command 388.Qq Li "chown -HR user slink" 389will traverse the file hierarchy rooted in the file pointed to by 390.Qq Li slink . 391Note, the 392.Fl H 393is not the same as the previously discussed 394.Fl h 395flag. 396The 397.Fl H 398flag causes symbolic links specified on the command line to be 399dereferenced both for the purposes of the action to be performed 400and the tree walk, and it is as if the user had specified the 401name of the file to which the symbolic link pointed. 402.Pp 403As consistently as possible, you can make commands doing a file tree 404walk follow any symbolic links named on the command line, as well as 405any symbolic links encountered during the traversal, regardless of 406the type of file they reference, by specifying the 407.Fl L 408(for 409.Qq logical ) 410flag. 411This flag is intended to make the entire name space look like 412the logical name space. 413(Note, for commands that do not always do file tree traversals, the 414.Fl L 415flag will be ignored if the 416.Fl R 417flag is not also specified). 418.Pp 419For example, the command 420.Qq Li "chown -LR user slink" 421will change the owner of the file referenced by 422.Qq Li slink . 423If 424.Qq Li slink 425references a directory, 426.Nm chown 427will traverse the file hierarchy rooted in the directory that it 428references. 429In addition, if any symbolic links are encountered in any file tree that 430.Nm chown 431traverses, they will be treated in the same fashion as 432.Qq Li slink . 433.Pp 434As consistently as possible, you can specify the default behavior by 435specifying the 436.Fl P 437(for 438.Qq physical ) 439flag. 440This flag is intended to make the entire name space look like the 441physical name space. 442.Pp 443For commands that do not by default do file tree traversals, the 444.Fl H , 445.Fl L , 446and 447.Fl P 448flags are ignored if the 449.Fl R 450flag is not also specified. 451In addition, you may specify the 452.Fl H , 453.Fl L , 454and 455.Fl P 456options more than once; the last one specified determines the 457command's behavior. 458This is intended to permit you to alias commands to behave one way 459or the other, and then override that behavior on the command line. 460.Pp 461The 462.Xr ls 1 463and 464.Xr rm 1 465commands have exceptions to these rules. 466The 467.Nm rm 468command operates on the symbolic link, and not the file it references, 469and therefore never follows a symbolic link. 470The 471.Nm rm 472command does not support the 473.Fl H , 474.Fl L , 475or 476.Fl P 477options. 478.Pp 479To maintain compatibility with historic systems, 480the 481.Nm ls 482command acts a little differently. 483If you do not specify the 484.Fl F , 485.Fl d , 486or 487.Fl l 488options, 489.Nm ls 490will follow symbolic links specified on the command line. 491If the 492.Fl L 493flag is specified. 494If the 495.Fl L 496flag is specified, 497.Nm ls 498follows all symbolic links, 499regardless of their type, 500whether specified on the command line or encountered in the tree walk. 501The 502.Nm ls 503command does not support the 504.Fl H 505or 506.Fl P 507options. 508.Ss Magic symlinks 509So-called 510.Dq magic symlinks 511can be enabled by setting the 512.Dq vfs.generic.magiclinks 513variable with 514.Xr sysctl 8 . 515When magic symlinks are enabled 516.Dq magic 517patterns in symlinks are expanded. 518Those patterns begin with 519.Dq @ 520.Pq an at-sign , 521and end at the end of the pathname component 522.Po 523i.e. at the next 524.Dq / , 525or at the end of the symbolic link if there are no more slashes 526.Pc . 527.Pp 528To illustrate the pattern matching rules, assume that 529.Dq @foo 530is a valid magic string: 531.Pp 532.Bl -tag -width @foo/barxxxxx -offset indent -compact 533.It @foo 534would be matched 535.It @foo/bar 536would be matched 537.It bar@foo 538would be matched 539.It @foobar 540would not be matched 541.El 542.Pp 543Magic strings may also be delimited with 544.Sq { 545and 546.Sq } 547characters, allowing for more complex patterns in symbolic links such as: 548.Bd -literal -offset indent 549@{var1}-@{var2}.@{var3} 550.Ed 551.Pp 552The following patterns are supported: 553.Bl -tag -width @machine_arch -offset indent 554.It @domainname 555Expands to the machine's domain name, as set by 556.Xr setdomainname 3 . 557.It @hostname 558Expands to the machine's host name, as set by 559.Xr sethostname 3 . 560.It @emul 561Expands to the name of the current process's emulation. 562Defaults to 563.Dv netbsd . 564Other valid emulations are: 565.Dv aout , 566.Dv aoutm68k , 567.Dv freebsd , 568.Dv linux , 569.Dv linux32 , 570.Dv m68k4k , 571.Dv netbsd32 , 572.Dv sunos , 573.Dv sunos32 , 574.Dv ultrix , 575.Dv vax1k . 576.It @kernel_ident 577Expands to the name of the 578.Xr config 1 579file used to generate the running kernel. 580For example 581.Dv GENERIC . 582.It @machine 583Expands to the value of 584.Li MACHINE 585for the system. 586For native binaries, this is 587equivalent to the output of 588.Dq uname -m 589or 590.Xr sysctl 3 591.Dq hw.machine . 592.Po 593For non-native binaries, the values returned by uname and sysctl 594typically vary to match the emulation environment. 595.Pc 596.It @machine_arch 597Expands to the value of 598.Li MACHINE_ARCH 599for the system. 600For native binaries, this is 601equivalent to the output of 602.Dq uname -p 603or 604.Xr sysctl 3 605.Dq hw.machine_arch . 606.Po 607For non-native binaries, the values returned by uname and sysctl 608typically vary to match the emulation environment. 609.Pc 610.It @osrelease 611Expands to the operating system release of the running kernel 612.Po 613equivalent to the output of 614.Dq uname -r 615or 616.Xr sysctl 3 617.Dq kern.osrelease 618.Pc . 619.It @ostype 620Expands to the operating system type of the running kernel 621.Po 622equivalent to the output of 623.Dq uname -s 624or 625.Xr sysctl 3 626.Dq kern.ostype 627.Pc . 628This will always be 629.Dq NetBSD 630on 631.Nx 632systems. 633.It @ruid 634Expands to the real user-id of the process. 635.It @uid 636Expands to the effective user-id of the process. 637.It @rgid 638Expands to the real group-id of the process. 639.It @gid 640Expands to the effective group-id of the process. 641.El 642.Sh SEE ALSO 643.Xr chflags 1 , 644.Xr chgrp 1 , 645.Xr chmod 1 , 646.Xr cp 1 , 647.Xr du 1 , 648.Xr find 1 , 649.Xr ln 1 , 650.Xr ls 1 , 651.Xr mv 1 , 652.Xr pax 1 , 653.Xr rm 1 , 654.Xr tar 1 , 655.Xr uname 1 , 656.Xr chown 2 , 657.Xr execve 2 , 658.Xr lchflags 2 , 659.Xr lchmod 2 , 660.Xr lchown 2 , 661.Xr lstat 2 , 662.Xr lutimes 2 , 663.Xr mount 2 , 664.Xr readlink 2 , 665.Xr rename 2 , 666.Xr symlink 2 , 667.Xr unlink 2 , 668.Xr fts 3 , 669.Xr remove 3 , 670.Xr chown 8 , 671.Xr mount 8 672.Sh HISTORY 673Magic symlinks appeared in 674.Nx 4.0 . 675