mirror of https://github.com/mkerrisk/man-pages
583 lines
17 KiB
Groff
583 lines
17 KiB
Groff
.\" 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>
|
|
.\"
|
|
.\" %%%LICENSE_START(BSD_3_CLAUSE_UCB)
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\" 4. Neither the name of the University nor the names of its contributors
|
|
.\" may be used to endorse or promote products derived from this software
|
|
.\" without specific prior written permission.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\" %%%LICENSE_END
|
|
.\"
|
|
.\" @(#)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 2021-03-22 "Linux" "Linux Programmer's Manual"
|
|
.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.
|
|
.PP
|
|
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).
|
|
.PP
|
|
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.
|
|
.PP
|
|
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" .
|
|
.PP
|
|
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 " /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 ).
|
|
.PP
|
|
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 only time that the ownership of a symbolic link matters is
|
|
when the link is being removed or renamed in a directory that
|
|
has the sticky bit set (see
|
|
.BR stat (2)).
|
|
.PP
|
|
The last access and last modification timestamps
|
|
of a symbolic link can be changed using
|
|
.BR utimensat (2)
|
|
or
|
|
.BR lutimes (3).
|
|
.PP
|
|
.\" 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.
|
|
.PP
|
|
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.
|
|
.\" .PP
|
|
.\" 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
|
|
.BR O_NOFOLLOW
|
|
flags to
|
|
.BR open (2)
|
|
yields a file descriptor that can be passed as the
|
|
.IR 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).
|
|
.PP
|
|
By default
|
|
(i.e., if the
|
|
.BR 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.)
|
|
.PP
|
|
There are three separate areas that need to be discussed.
|
|
They are as follows:
|
|
.IP 1. 3
|
|
Symbolic links used as filename arguments for system calls.
|
|
.IP 2.
|
|
Symbolic links specified as command-line arguments to utilities that
|
|
are not traversing a file tree.
|
|
.IP 3.
|
|
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).
|
|
.PP
|
|
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
|
|
.IR basename
|
|
component.
|
|
.\"
|
|
.SS Treatment of symbolic links in system calls
|
|
The first area is symbolic links used as filename arguments for
|
|
system calls.
|
|
.PP
|
|
The treatment of symbolic links within a pathname passed to
|
|
a system call is as follows:
|
|
.IP 1. 3
|
|
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 .
|
|
.PP
|
|
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).
|
|
.PP
|
|
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 .
|
|
.PP
|
|
.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.
|
|
.PP
|
|
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 .
|
|
.PP
|
|
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.)
|
|
.PP
|
|
If it is explicitly intended that the command operate on the symbolic
|
|
link instead of following the symbolic link\(emfor 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\(emthen 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.
|
|
.PP
|
|
There are some exceptions to this rule:
|
|
.IP * 2
|
|
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 *
|
|
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\(emthat 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 *
|
|
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).
|
|
.PP
|
|
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.
|
|
.PP
|
|
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.
|
|
.PP
|
|
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 .
|
|
.PP
|
|
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).
|
|
.PP
|
|
Certain conventions are (should be) followed as consistently as
|
|
possible by commands that perform file tree walks:
|
|
.IP * 2
|
|
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 *
|
|
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 *
|
|
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.
|
|
.PP
|
|
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.
|
|
.PP
|
|
The
|
|
.BR ls (1)
|
|
and
|
|
.BR rm (1)
|
|
commands have exceptions to these rules:
|
|
.IP * 2
|
|
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 *
|
|
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)
|