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