diff options
Diffstat (limited to 'man7/symlink.7')
| -rw-r--r-- | man7/symlink.7 | 564 |
1 files changed, 0 insertions, 564 deletions
diff --git a/man7/symlink.7 b/man7/symlink.7 deleted file mode 100644 index 737bb1f..0000000 --- a/man7/symlink.7 +++ /dev/null @@ -1,564 +0,0 @@ -.\" 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 2023-10-31 "Linux man-pages 6.7" -.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) |