Merging upstream version 6.8.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 564 insertions, 0 deletions

diff --git a/man/man7/symlink.7 b/man/man7/symlink.7
new file mode 100644
index 0000000..e8d0650
--- /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 2024-05-02 "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)