diff options
Diffstat (limited to 'man/man7/symlink.7')
| -rw-r--r-- | man/man7/symlink.7 | 564 |
1 files changed, 564 insertions, 0 deletions
diff --git a/man/man7/symlink.7 b/man/man7/symlink.7 new file mode 100644 index 000000000..5aaaee598 --- /dev/null +++ b/man/man7/symlink.7 @@ -0,0 +1,564 @@ +.\" Copyright (c) 1992, 1993, 1994 +.\" The Regents of the University of California. All rights reserved. +.\" and Copyright (C) 2008, 2014 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: BSD-3-Clause +.\" +.\" @(#)symlink.7 8.3 (Berkeley) 3/31/94 +.\" $FreeBSD: src/bin/ln/symlink.7,v 1.30 2005/02/13 22:25:09 ru Exp $ +.\" +.\" 2008-06-11, mtk, Taken from FreeBSD 6.2 and heavily edited for +.\" specific Linux details, improved readability, and man-pages style. +.\" +.TH symlink 7 (date) "Linux man-pages (unreleased)" +.SH NAME +symlink \- symbolic link handling +.SH DESCRIPTION +Symbolic links are files that act as pointers to other files. +To understand their behavior, you must first understand how hard links +work. +.P +A hard link to a file is indistinguishable from the original file because +it is a reference to the object underlying the original filename. +(To be precise: each of the hard links to a file is a reference to +the same +.IR "inode number" , +where an inode number is an index into the inode table, +which contains metadata about all files on a filesystem. +See +.BR stat (2).) +Changes to a file are independent of the name used to reference the file. +Hard links may not refer to directories +(to prevent the possibility of loops within the filesystem tree, +which would confuse many programs) +and may not refer to files on different filesystems +(because inode numbers are not unique across filesystems). +.P +A symbolic link is a special type of file whose contents are a string +that is the pathname of another file, the file to which the link refers. +(The contents of a symbolic link can be read using +.BR readlink (2).) +In other words, a symbolic link is a pointer to another name, +and not to an underlying object. +For this reason, symbolic links may refer to directories and may cross +filesystem boundaries. +.P +There is no requirement that the pathname referred to by a symbolic link +should exist. +A symbolic link that refers to a pathname that does not exist is said +to be a +.IR "dangling link" . +.P +Because a symbolic link and its referenced object coexist in the filesystem +name space, confusion can arise in distinguishing between the link itself +and the referenced object. +On historical systems, +commands and system calls adopted their own link-following +conventions in a somewhat ad-hoc fashion. +Rules for a more uniform approach, +as they are implemented on Linux and other systems, +are outlined here. +It is important that site-local applications also conform to these rules, +so that the user interface can be as consistent as possible. +.\" +.SS Magic links +There is a special class of symbolic-link-like objects +known as "magic links", which +can be found in certain pseudofilesystems such as +.BR proc (5) +(examples include +.IR /proc/ pid /exe +and +.IR /proc/ pid /fd/ *). +Unlike normal symbolic links, magic links are not resolved through +pathname-expansion, but instead act as direct references to the kernel's own +representation of a file handle. +As such, these magic links allow users to +access files which cannot be referenced with normal paths (such as unlinked +files still referenced by a running program ). +.P +Because they can bypass ordinary +.BR mount_namespaces (7)-based +restrictions, +magic links have been used as attack vectors in various exploits. +.\" +.SS Symbolic link ownership, permissions, and timestamps +The owner and group of an existing symbolic link can be changed +using +.BR lchown (2). +The ownership of a symbolic link matters +when the link is being removed or renamed in a directory that +has the sticky bit set (see +.BR inode (7)), +and when the +.I fs.protected_symlinks +sysctl is set (see +.BR proc (5)). +.P +The last access and last modification timestamps +of a symbolic link can be changed using +.BR utimensat (2) +or +.BR lutimes (3). +.P +.\" Linux does not currently implement an lchmod(2). +On Linux, the permissions of an ordinary symbolic link are not used in any +operations; the permissions are always 0777 (read, write, and execute for all +user categories), and can't be changed. +.P +However, magic links do not follow this rule. +They can have a non-0777 mode, +though this mode is not currently used in any permission checks. +.\" .P +.\" The +.\" 4.4BSD +.\" system differs from historical +.\" 4BSD +.\" systems in that the system call +.\" .BR chown (2) +.\" has been changed to follow symbolic links. +.\" The +.\" .BR lchown (2) +.\" system call was added later when the limitations of the new +.\" .BR chown (2) +.\" became apparent. +.SS Obtaining a file descriptor that refers to a symbolic link +Using the combination of the +.B O_PATH +and +.B O_NOFOLLOW +flags to +.BR open (2) +yields a file descriptor that can be passed as the +.I dirfd +argument in system calls such as +.BR fstatat (2), +.BR fchownat (2), +.BR fchmodat (2), +.BR linkat (2), +and +.BR readlinkat (2), +in order to operate on the symbolic link itself +(rather than the file to which it refers). +.P +By default +(i.e., if the +.B AT_SYMLINK_FOLLOW +flag is not specified), if +.BR name_to_handle_at (2) +is applied to a symbolic link, it yields a handle for the symbolic link +(rather than the file to which it refers). +One can then obtain a file descriptor for the symbolic link +(rather than the file to which it refers) +by specifying the +.B O_PATH +flag in a subsequent call to +.BR open_by_handle_at (2). +Again, that file descriptor can be used in the +aforementioned system calls to operate on the symbolic link itself. +.SS Handling of symbolic links by system calls and commands +Symbolic links are handled either by operating on the link itself, +or by operating on the object referred to by the link. +In the latter case, +an application or system call is said to +.I follow +the link. +Symbolic links may refer to other symbolic links, +in which case the links are dereferenced until an object that is +not a symbolic link is found, +a symbolic link that refers to a file which does not exist is found, +or a loop is detected. +(Loop detection is done by placing an upper limit on the number of +links that may be followed, and an error results if this limit is +exceeded.) +.P +There are three separate areas that need to be discussed. +They are as follows: +.IP \[bu] 3 +Symbolic links used as filename arguments for system calls. +.IP \[bu] +Symbolic links specified as command-line arguments to utilities that +are not traversing a file tree. +.IP \[bu] +Symbolic links encountered by utilities that are traversing a file tree +(either specified on the command line or encountered as part of the +file hierarchy walk). +.P +Before describing the treatment of symbolic links by system calls and commands, +we require some terminology. +Given a pathname of the form +.IR a/b/c , +the part preceding the final slash (i.e., +.IR a/b ) +is called the +.I dirname +component, and the part following the final slash (i.e., +.IR c ) +is called the +.I basename +component. +.\" +.SS Treatment of symbolic links in system calls +The first area is symbolic links used as filename arguments for +system calls. +.P +The treatment of symbolic links within a pathname passed to +a system call is as follows: +.IP (1) 5 +Within the dirname component of a pathname, +symbolic links are always followed in nearly every system call. +(This is also true for commands.) +The one exception is +.BR openat2 (2), +which provides flags that can be used to explicitly +prevent following of symbolic links in the dirname component. +.IP (2) +Except as noted below, +all system calls follow symbolic links +in the basename component of a pathname. +For example, if there were a symbolic link +.I slink +which pointed to a file named +.IR afile , +the system call +.I "open(""slink"" ...\&)" +would return a file descriptor referring to the file +.IR afile . +.P +Various system calls do not follow links in +the basename component of a pathname, +and operate on the symbolic link itself. +They are: +.BR lchown (2), +.BR lgetxattr (2), +.BR llistxattr (2), +.BR lremovexattr (2), +.BR lsetxattr (2), +.BR lstat (2), +.BR readlink (2), +.BR rename (2), +.BR rmdir (2), +and +.BR unlink (2). +.P +Certain other system calls optionally follow symbolic links +in the basename component of a pathname. +They are: +.BR faccessat (2), +.\" Maybe one day: .BR fchownat (2) +.BR fchownat (2), +.BR fstatat (2), +.BR linkat (2), +.BR name_to_handle_at (2), +.BR open (2), +.BR openat (2), +.BR open_by_handle_at (2), +and +.BR utimensat (2); +see their manual pages for details. +Because +.BR remove (3) +is an alias for +.BR unlink (2), +that library function also does not follow symbolic links. +When +.BR rmdir (2) +is applied to a symbolic link, it fails with the error +.BR ENOTDIR . +.P +.BR link (2) +warrants special discussion. +POSIX.1-2001 specifies that +.BR link (2) +should dereference +.I oldpath +if it is a symbolic link. +However, Linux does not do this. +(By default, Solaris is the same, +but the POSIX.1-2001 specified behavior can be obtained with +suitable compiler options.) +POSIX.1-2008 changed the specification to allow +either behavior in an implementation. +.SS Commands not traversing a file tree +The second area is symbolic links, specified as command-line +filename arguments, to commands which are not traversing a file tree. +.P +Except as noted below, commands follow symbolic links named as +command-line arguments. +For example, if there were a symbolic link +.I slink +which pointed to a file named +.IR afile , +the command +.I "cat slink" +would display the contents of the file +.IR afile . +.P +It is important to realize that this rule includes commands which may +optionally traverse file trees; for example, the command +.I "chown file" +is included in this rule, while the command +.IR "chown\ \-R file" , +which performs a tree traversal, is not. +(The latter is described in the third area, below.) +.P +If it is explicitly intended that the command operate on the symbolic +link instead of following the symbolic link\[em]for example, it is desired that +.I "chown slink" +change the ownership of the file that +.I slink +is, whether it is a symbolic link or not\[em]then the +.I \-h +option should be used. +In the above example, +.I "chown root slink" +would change the ownership of the file referred to by +.IR slink , +while +.I "chown\ \-h root slink" +would change the ownership of +.I slink +itself. +.P +There are some exceptions to this rule: +.IP \[bu] 3 +The +.BR mv (1) +and +.BR rm (1) +commands do not follow symbolic links named as arguments, +but respectively attempt to rename and delete them. +(Note, if the symbolic link references a file via a relative path, +moving it to another directory may very well cause it to stop working, +since the path may no longer be correct.) +.IP \[bu] +The +.BR ls (1) +command is also an exception to this rule. +For compatibility with historic systems (when +.BR ls (1) +is not doing a tree walk\[em]that is, +.I \-R +option is not specified), +the +.BR ls (1) +command follows symbolic links named as arguments if the +.I \-H +or +.I \-L +option is specified, +or if the +.IR \-F , +.IR \-d , +or +.I \-l +options are not specified. +(The +.BR ls (1) +command is the only command where the +.I \-H +and +.I \-L +options affect its behavior even though it is not doing a walk of +a file tree.) +.IP \[bu] +The +.BR file (1) +command is also an exception to this rule. +The +.BR file (1) +command does not follow symbolic links named as argument by default. +The +.BR file (1) +command does follow symbolic links named as argument if the +.I \-L +option is specified. +.\" +.\"The 4.4BSD system differs from historical 4BSD systems in that the +.\".BR chown (1) +.\"and +.\".BR chgrp (1) +.\"commands follow symbolic links specified on the command line. +.SS Commands traversing a file tree +The following commands either optionally or always traverse file trees: +.BR chgrp (1), +.BR chmod (1), +.BR chown (1), +.BR cp (1), +.BR du (1), +.BR find (1), +.BR ls (1), +.BR pax (1), +.BR rm (1), +and +.BR tar (1). +.P +It is important to realize that the following rules apply equally to +symbolic links encountered during the file tree traversal and symbolic +links listed as command-line arguments. +.P +The \fIfirst rule\fP applies to symbolic links that reference files other +than directories. +Operations that apply to symbolic links are performed on the links +themselves, but otherwise the links are ignored. +.P +The command +.I "rm\ \-r slink directory" +will remove +.IR slink , +as well as any symbolic links encountered in the tree traversal of +.IR directory , +because symbolic links may be removed. +In no case will +.BR rm (1) +affect the file referred to by +.IR slink . +.P +The \fIsecond rule\fP applies to symbolic links that refer to directories. +Symbolic links that refer to directories are never followed by default. +This is often referred to as a "physical" walk, as opposed to a "logical" +walk (where symbolic links that refer to directories are followed). +.P +Certain conventions are (should be) followed as consistently as +possible by commands that perform file tree walks: +.IP \[bu] 3 +A command can be made to follow +any symbolic links named on the command line, +regardless of the type of file they reference, by specifying the +.I \-H +(for "half-logical") flag. +This flag is intended to make the command-line name space look +like the logical name space. +(Note, for commands that do not always do file tree traversals, the +.I \-H +flag will be ignored if the +.I \-R +flag is not also specified.) +.IP +For example, the command +.I "chown\ \-HR user slink" +will traverse the file hierarchy rooted in the file pointed to by +.IR slink . +Note, the +.I \-H +is not the same as the previously discussed +.I \-h +flag. +The +.I \-H +flag causes symbolic links specified on the command line to be +dereferenced for the purposes of both the action to be performed +and the tree walk, and it is as if the user had specified the +name of the file to which the symbolic link pointed. +.IP \[bu] +A command can be made to +follow any symbolic links named on the command line, +as well as any symbolic links encountered during the traversal, +regardless of the type of file they reference, by specifying the +.I \-L +(for "logical") flag. +This flag is intended to make the entire name space look like +the logical name space. +(Note, for commands that do not always do file tree traversals, the +.I \-L +flag will be ignored if the +.I \-R +flag is not also specified.) +.IP +For example, the command +.I "chown\ \-LR user slink" +will change the owner of the file referred to by +.IR slink . +If +.I slink +refers to a directory, +.B chown +will traverse the file hierarchy rooted in the directory that it +references. +In addition, if any symbolic links are encountered in any file tree that +.B chown +traverses, they will be treated in the same fashion as +.IR slink . +.IP \[bu] +A command can be made to +provide the default behavior by specifying the +.I \-P +(for "physical") flag. +This flag is intended to make the entire name space look like the +physical name space. +.P +For commands that do not by default do file tree traversals, the +.IR \-H , +.IR \-L , +and +.I \-P +flags are ignored if the +.I \-R +flag is not also specified. +In addition, you may specify the +.IR \-H , +.IR \-L , +and +.I \-P +options more than once; +the last one specified determines the command's behavior. +This is intended to permit you to alias commands to behave one way +or the other, and then override that behavior on the command line. +.P +The +.BR ls (1) +and +.BR rm (1) +commands have exceptions to these rules: +.IP \[bu] 3 +The +.BR rm (1) +command operates on the symbolic link, and not the file it references, +and therefore never follows a symbolic link. +The +.BR rm (1) +command does not support the +.IR \-H , +.IR \-L , +or +.I \-P +options. +.IP \[bu] +To maintain compatibility with historic systems, +the +.BR ls (1) +command acts a little differently. +If you do not specify the +.IR \-F , +.IR \-d , +or +.I \-l +options, +.BR ls (1) +will follow symbolic links specified on the command line. +If the +.I \-L +flag is specified, +.BR ls (1) +follows all symbolic links, +regardless of their type, +whether specified on the command line or encountered in the tree walk. +.SH SEE ALSO +.BR chgrp (1), +.BR chmod (1), +.BR find (1), +.BR ln (1), +.BR ls (1), +.BR mv (1), +.BR namei (1), +.BR rm (1), +.BR lchown (2), +.BR link (2), +.BR lstat (2), +.BR readlink (2), +.BR rename (2), +.BR symlink (2), +.BR unlink (2), +.BR utimensat (2), +.BR lutimes (3), +.BR path_resolution (7) |