man7/symlink.7

   1 .\" Copyright (c) 1992, 1993, 1994
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\" and Copyright (C) 2008, 2014 Michael Kerrisk <mtk.manpages@gmail.com>
   4 .\"
   5 .\" %%%LICENSE_START(BSD_3_CLAUSE_UCB)
   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 .\" 4. 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 .\" %%%LICENSE_END
  30 .\"
  31 .\"     @(#)symlink.7   8.3 (Berkeley) 3/31/94
  32 .\" $FreeBSD: src/bin/ln/symlink.7,v 1.30 2005/02/13 22:25:09 ru Exp $
  33 .\"
  34 .\" 2008-06-11, mtk, Taken from FreeBSD 6.2 and heavily edited for
  35 .\"     specific Linux details, improved readability, and man-pages style.
  36 .\"
  37 .TH SYMLINK 7 2016-10-08 "Linux" "Linux Programmer's Manual"
  38 .SH NAME
  39 symlink \- symbolic link handling
  40 .SH DESCRIPTION
  41 Symbolic links are files that act as pointers to other files.
  42 To understand their behavior, you must first understand how hard links
  43 work.
  44 .PP
  45 A hard link to a file is indistinguishable from the original file because
  46 it is a reference to the object underlying the original filename.
  47 (To be precise: each of the hard links to a file is a reference to
  48 the same
  49 .IR "inode number" ,
  50 where an inode number is an index into the inode table,
  51 which contains metadata about all files on a filesystem.
  52 See
  53 .BR stat (2).)
  54 Changes to a file are independent of the name used to reference the file.
  55 Hard links may not refer to directories
  56 (to prevent the possibility of loops within the filesystem tree,
  57 which would confuse many programs)
  58 and may not refer to files on different filesystems
  59 (because inode numbers are not unique across filesystems).
  60 .PP
  61 A symbolic link is a special type of file whose contents are a string
  62 that is the pathname of another file, the file to which the link refers.
  63 (The contents of a symbolic link can be read using
  64 .BR readlink (2).)
  65 In other words, a symbolic link is a pointer to another name,
  66 and not to an underlying object.
  67 For this reason, symbolic links may refer to directories and may cross
  68 filesystem boundaries.
  69 .PP
  70 There is no requirement that the pathname referred to by a symbolic link
  71 should exist.
  72 A symbolic link that refers to a pathname that does not exist is said
  73 to be a
  74 .IR "dangling link" .
  75 .PP
  76 Because a symbolic link and its referenced object coexist in the filesystem
  77 name space, confusion can arise in distinguishing between the link itself
  78 and the referenced object.
  79 On historical systems,
  80 commands and system calls adopted their own link-following
  81 conventions in a somewhat ad-hoc fashion.
  82 Rules for a more uniform approach,
  83 as they are implemented on Linux and other systems,
  84 are outlined here.
  85 It is important that site-local applications also conform to these rules,
  86 so that the user interface can be as consistent as possible.
  87 .SS Symbolic link ownership, permissions, and timestamps
  88 The owner and group of an existing symbolic link can be changed
  89 using
  90 .BR lchown (2).
  91 The only time that the ownership of a symbolic link matters is
  92 when the link is being removed or renamed in a directory that
  93 has the sticky bit set (see
  94 .BR stat (2)).
  95 .PP
  96 The last access and last modification timestamps
  97 of a symbolic link can be changed using
  98 .BR utimensat (2)
  99 or
 100 .BR lutimes (3).
 101 .PP
 102 On Linux, the permissions of a symbolic link are not used
 103 in any operations; the permissions are always
 104 0777 (read, write, and execute for all user categories),
 105 .\" Linux does not currently implement an lchmod(2).
 106 and can't be changed.
 107 (Note that there are some "magic" symbolic links in the
 108 .I /proc
 109 directory tree\(emfor example, the
 110 .IR /proc/[pid]/fd/*
 111 files\(emthat have different permissions.)
 112 .\"
 113 .\" The
 114 .\" 4.4BSD
 115 .\" system differs from historical
 116 .\" 4BSD
 117 .\" systems in that the system call
 118 .\" .BR chown (2)
 119 .\" has been changed to follow symbolic links.
 120 .\" The
 121 .\" .BR lchown (2)
 122 .\" system call was added later when the limitations of the new
 123 .\" .BR chown (2)
 124 .\" became apparent.
 125 .SS Obtaining a file descriptor that refers to a symbolic link
 126 Using the combination of the
 127 .B O_PATH
 128 and
 129 .BR O_NOFOLLOW
 130 flags to
 131 .BR open (2)
 132 yields a file descriptor that can be passed as the
 133 .IR dirfd
 134 argument in system calls such as
 135 .BR fstatat (2),
 136 .BR fchownat (2),
 137 .BR fchmodat (2),
 138 .BR linkat (2),
 139 and
 140 .BR readlinkat (2),
 141 in order to operate on the symbolic link itself
 142 (rather than the file to which it refers).
 143 .PP
 144 By default
 145 (i.e., if the
 146 .BR AT_SYMLINK_FOLLOW
 147 flag is not specified), if
 148 .BR name_to_handle_at (2)
 149 is applied to a symbolic link, it yields a handle for the symbolic link
 150 (rather than the file to which it refers).
 151 One can then obtain a file descriptor for the symbolic link
 152 (rather than the file to which it refers)
 153 by specifying the
 154 .B O_PATH
 155 flag in a subsequent call to
 156 .BR open_by_handle_at (2).
 157 Again, that file descriptor can be used in the
 158 aforementioned system calls to operate on the symbolic link itself.
 159 .SS Handling of symbolic links by system calls and commands
 160 Symbolic links are handled either by operating on the link itself,
 161 or by operating on the object referred to by the link.
 162 In the latter case,
 163 an application or system call is said to
 164 .I follow
 165 the link.
 166 Symbolic links may refer to other symbolic links,
 167 in which case the links are dereferenced until an object that is
 168 not a symbolic link is found,
 169 a symbolic link that refers to a file which does not exist is found,
 170 or a loop is detected.
 171 (Loop detection is done by placing an upper limit on the number of
 172 links that may be followed, and an error results if this limit is
 173 exceeded.)
 174 .PP
 175 There are three separate areas that need to be discussed.
 176 They are as follows:
 177 .IP 1. 3
 178 Symbolic links used as filename arguments for system calls.
 179 .IP 2.
 180 Symbolic links specified as command-line arguments to utilities that
 181 are not traversing a file tree.
 182 .IP 3.
 183 Symbolic links encountered by utilities that are traversing a file tree
 184 (either specified on the command line or encountered as part of the
 185 file hierarchy walk).
 186 .SS System calls
 187 The first area is symbolic links used as filename arguments for
 188 system calls.
 189 .PP
 190 Except as noted below, all system calls follow symbolic links.
 191 For example, if there were a symbolic link
 192 .I slink
 193 which pointed to a file named
 194 .IR afile ,
 195 the system call
 196 .I "open(""slink"" ...\&)"
 197 would return a file descriptor referring to the file
 198 .IR afile .
 199 .PP
 200 Various system calls do not follow links, and operate
 201 on the symbolic link itself.
 202 They are:
 203 .BR lchown (2),
 204 .BR lgetxattr (2),
 205 .BR llistxattr (2),
 206 .BR lremovexattr (2),
 207 .BR lsetxattr (2),
 208 .BR lstat (2),
 209 .BR readlink (2),
 210 .BR rename (2),
 211 .BR rmdir (2),
 212 and
 213 .BR unlink (2).
 214 .PP
 215 Certain other system calls optionally follow symbolic links.
 216 They are:
 217 .BR faccessat (2),
 218 .\" Maybe one day: .BR fchownat (2)
 219 .BR fchownat (2),
 220 .BR fstatat (2),
 221 .BR linkat (2),
 222 .BR name_to_handle_at (2),
 223 .BR open (2),
 224 .BR openat (2),
 225 .BR open_by_handle_at (2),
 226 and
 227 .BR utimensat (2);
 228 see their manual pages for details.
 229 Because
 230 .BR remove (3)
 231 is an alias for
 232 .BR unlink (2),
 233 that library function also does not follow symbolic links.
 234 When
 235 .BR rmdir (2)
 236 is applied to a symbolic link, it fails with the error
 237 .BR ENOTDIR .
 238 .PP
 239 .BR link (2)
 240 warrants special discussion.
 241 POSIX.1-2001 specifies that
 242 .BR link (2)
 243 should dereference
 244 .I oldpath
 245 if it is a symbolic link.
 246 However, Linux does not do this.
 247 (By default, Solaris is the same,
 248 but the POSIX.1-2001 specified behavior can be obtained with
 249 suitable compiler options.)
 250 POSIX.1-2008 changed the specification to allow
 251 either behavior in an implementation.
 252 .SS Commands not traversing a file tree
 253 The second area is symbolic links, specified as command-line
 254 filename arguments, to commands which are not traversing a file tree.
 255 .PP
 256 Except as noted below, commands follow symbolic links named as
 257 command-line arguments.
 258 For example, if there were a symbolic link
 259 .I slink
 260 which pointed to a file named
 261 .IR afile ,
 262 the command
 263 .I "cat slink"
 264 would display the contents of the file
 265 .IR afile .
 266 .PP
 267 It is important to realize that this rule includes commands which may
 268 optionally traverse file trees; for example, the command
 269 .I "chown file"
 270 is included in this rule, while the command
 271 .IR "chown\ \-R file" ,
 272 which performs a tree traversal, is not.
 273 (The latter is described in the third area, below.)
 274 .PP
 275 If it is explicitly intended that the command operate on the symbolic
 276 link instead of following the symbolic link\(emfor example, it is desired that
 277 .I "chown slink"
 278 change the ownership of the file that
 279 .I slink
 280 is, whether it is a symbolic link or not\(emthe
 281 .I \-h
 282 option should be used.
 283 In the above example,
 284 .I "chown root slink"
 285 would change the ownership of the file referred to by
 286 .IR slink ,
 287 while
 288 .I "chown\ \-h root slink"
 289 would change the ownership of
 290 .I slink
 291 itself.
 292 .PP
 293 There are some exceptions to this rule:
 294 .IP * 2
 295 The
 296 .BR mv (1)
 297 and
 298 .BR rm (1)
 299 commands do not follow symbolic links named as arguments,
 300 but respectively attempt to rename and delete them.
 301 (Note, if the symbolic link references a file via a relative path,
 302 moving it to another directory may very well cause it to stop working,
 303 since the path may no longer be correct.)
 304 .IP *
 305 The
 306 .BR ls (1)
 307 command is also an exception to this rule.
 308 For compatibility with historic systems (when
 309 .BR ls (1)
 310 is not doing a tree walk\(emthat is,
 311 .I \-R
 312 option is not specified),
 313 the
 314 .BR ls (1)
 315 command follows symbolic links named as arguments if the
 316 .I \-H
 317 or
 318 .I \-L
 319 option is specified,
 320 or if the
 321 .IR \-F ,
 322 .IR \-d ,
 323 or
 324 .I \-l
 325 options are not specified.
 326 (The
 327 .BR ls (1)
 328 command is the only command where the
 329 .I \-H
 330 and
 331 .I \-L
 332 options affect its behavior even though it is not doing a walk of
 333 a file tree.)
 334 .IP *
 335 The
 336 .BR file (1)
 337 command is also an exception to this rule.
 338 The
 339 .BR file (1)
 340 command does not follow symbolic links named as argument by default.
 341 The
 342 .BR file (1)
 343 command does follow symbolic links named as argument if the
 344 .I \-L
 345 option is specified.
 346 .\"
 347 .\"The 4.4BSD system differs from historical 4BSD systems in that the
 348 .\".BR chown (1)
 349 .\"and
 350 .\".BR chgrp (1)
 351 .\"commands follow symbolic links specified on the command line.
 352 .SS Commands traversing a file tree
 353 The following commands either optionally or always traverse file trees:
 354 .BR chgrp (1),
 355 .BR chmod (1),
 356 .BR chown (1),
 357 .BR cp (1),
 358 .BR du (1),
 359 .BR find (1),
 360 .BR ls (1),
 361 .BR pax (1),
 362 .BR rm (1),
 363 and
 364 .BR tar (1).
 365 .PP
 366 It is important to realize that the following rules apply equally to
 367 symbolic links encountered during the file tree traversal and symbolic
 368 links listed as command-line arguments.
 369 .PP
 370 The \fIfirst rule\fP applies to symbolic links that reference files other
 371 than directories.
 372 Operations that apply to symbolic links are performed on the links
 373 themselves, but otherwise the links are ignored.
 374 .PP
 375 The command
 376 .I "rm\ \-r slink directory"
 377 will remove
 378 .IR slink ,
 379 as well as any symbolic links encountered in the tree traversal of
 380 .IR directory ,
 381 because symbolic links may be removed.
 382 In no case will
 383 .BR rm (1)
 384 affect the file referred to by
 385 .IR slink .
 386 .PP
 387 The \fIsecond rule\fP applies to symbolic links that refer to directories.
 388 Symbolic links that refer to directories are never followed by default.
 389 This is often referred to as a "physical" walk, as opposed to a "logical"
 390 walk (where symbolic links that refer to directories are followed).
 391 .PP
 392 Certain conventions are (should be) followed as consistently as
 393 possible by commands that perform file tree walks:
 394 .IP * 2
 395 A command can be made to follow
 396 any symbolic links named on the command line,
 397 regardless of the type of file they reference, by specifying the
 398 .I \-H
 399 (for "half-logical") flag.
 400 This flag is intended to make the command-line name space look
 401 like the logical name space.
 402 (Note, for commands that do not always do file tree traversals, the
 403 .I \-H
 404 flag will be ignored if the
 405 .I \-R
 406 flag is not also specified.)
 407 .IP
 408 For example, the command
 409 .I "chown\ \-HR user slink"
 410 will traverse the file hierarchy rooted in the file pointed to by
 411 .IR slink .
 412 Note, the
 413 .I \-H
 414 is not the same as the previously discussed
 415 .I \-h
 416 flag.
 417 The
 418 .I \-H
 419 flag causes symbolic links specified on the command line to be
 420 dereferenced for the purposes of both the action to be performed
 421 and the tree walk, and it is as if the user had specified the
 422 name of the file to which the symbolic link pointed.
 423 .IP *
 424 A command can be made to
 425 follow any symbolic links named on the command line,
 426 as well as any symbolic links encountered during the traversal,
 427 regardless of the type of file they reference, by specifying the
 428 .I \-L
 429 (for "logical") flag.
 430 This flag is intended to make the entire name space look like
 431 the logical name space.
 432 (Note, for commands that do not always do file tree traversals, the
 433 .I \-L
 434 flag will be ignored if the
 435 .I \-R
 436 flag is not also specified.)
 437 .IP
 438 For example, the command
 439 .I "chown\ \-LR user slink"
 440 will change the owner of the file referred to by
 441 .IR slink .
 442 If
 443 .I slink
 444 refers to a directory,
 445 .B chown
 446 will traverse the file hierarchy rooted in the directory that it
 447 references.
 448 In addition, if any symbolic links are encountered in any file tree that
 449 .B chown
 450 traverses, they will be treated in the same fashion as
 451 .IR slink .
 452 .IP *
 453 A command can be made to
 454 provide the default behavior by specifying the
 455 .I \-P
 456 (for "physical") flag.
 457 This flag is intended to make the entire name space look like the
 458 physical name space.
 459 .PP
 460 For commands that do not by default do file tree traversals, the
 461 .IR \-H ,
 462 .IR \-L ,
 463 and
 464 .I \-P
 465 flags are ignored if the
 466 .I \-R
 467 flag is not also specified.
 468 In addition, you may specify the
 469 .IR \-H ,
 470 .IR \-L ,
 471 and
 472 .I \-P
 473 options more than once;
 474 the last one specified determines the command's behavior.
 475 This is intended to permit you to alias commands to behave one way
 476 or the other, and then override that behavior on the command line.
 477 .PP
 478 The
 479 .BR ls (1)
 480 and
 481 .BR rm (1)
 482 commands have exceptions to these rules:
 483 .IP * 2
 484 The
 485 .BR rm (1)
 486 command operates on the symbolic link, and not the file it references,
 487 and therefore never follows a symbolic link.
 488 The
 489 .BR rm (1)
 490 command does not support the
 491 .IR \-H ,
 492 .IR \-L ,
 493 or
 494 .I \-P
 495 options.
 496 .IP *
 497 To maintain compatibility with historic systems,
 498 the
 499 .BR ls (1)
 500 command acts a little differently.
 501 If you do not specify the
 502 .IR \-F ,
 503 .IR \-d
 504 or
 505 .I \-l
 506 options,
 507 .BR ls (1)
 508 will follow symbolic links specified on the command line.
 509 If the
 510 .I \-L
 511 flag is specified,
 512 .BR ls (1)
 513 follows all symbolic links,
 514 regardless of their type,
 515 whether specified on the command line or encountered in the tree walk.
 516 .SH SEE ALSO
 517 .BR chgrp (1),
 518 .BR chmod (1),
 519 .BR find (1),
 520 .BR ln (1),
 521 .BR ls (1),
 522 .BR mv (1),
 523 .BR namei (1),
 524 .BR rm (1),
 525 .BR lchown (2),
 526 .BR link (2),
 527 .BR lstat (2),
 528 .BR readlink (2),
 529 .BR rename (2),
 530 .BR symlink (2),
 531 .BR unlink (2),
 532 .BR utimensat (2),
 533 .BR lutimes (3),
 534 .BR path_resolution (7)