484 lines
13 KiB
Groff
484 lines
13 KiB
Groff
.\"-
|
|
.\" Copyright (c) 1992, 1993, 1994
|
|
.\" The Regents of the University of California. All rights reserved.
|
|
.\"
|
|
.\" 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.
|
|
.\"
|
|
.\" @(#)symlink.7 8.3 (Berkeley) 3/31/94
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.Dd February 16, 2015
|
|
.Dt SYMLINK 7
|
|
.Os
|
|
.Sh NAME
|
|
.Nm symlink
|
|
.Nd symbolic link handling
|
|
.Sh SYMBOLIC LINK HANDLING
|
|
Symbolic links are files that act as pointers to other files.
|
|
To understand their behavior, you must first understand how hard links
|
|
work.
|
|
A hard link to a file is indistinguishable from the original file because
|
|
it is a reference to the object underlying the original file name.
|
|
Changes to a file are independent of the name used to reference the
|
|
file.
|
|
Hard links may not refer to directories and may not reference files
|
|
on different file systems.
|
|
A symbolic link contains the name of the file to which it is linked,
|
|
i.e., it is a pointer to another name, and not to an underlying object.
|
|
For this reason, symbolic links may reference directories and may span
|
|
file systems.
|
|
.Pp
|
|
Because a symbolic link and its referenced object coexist in the file system
|
|
name space, confusion can arise in distinguishing between the link itself
|
|
and the referenced object.
|
|
Historically, commands and system calls have adopted their own link
|
|
following conventions in a somewhat ad-hoc fashion.
|
|
Rules for more a uniform approach, as they are implemented in this system,
|
|
are outlined here.
|
|
It is important that local applications conform to these rules, too,
|
|
so that the user interface can be as consistent as possible.
|
|
.Pp
|
|
Symbolic links are handled either by operating on the link itself,
|
|
or by operating on the object referenced by the link.
|
|
In the latter case,
|
|
an application or system call is said to
|
|
.Dq follow
|
|
the link.
|
|
Symbolic links may reference other symbolic links,
|
|
in which case the links are dereferenced until an object that is
|
|
not a symbolic link is found,
|
|
a symbolic link which references 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:
|
|
.Pp
|
|
.Bl -enum -compact -offset indent
|
|
.It
|
|
Symbolic links used as file name arguments for system calls.
|
|
.It
|
|
Symbolic links specified as command line arguments to utilities that
|
|
are not traversing a file tree.
|
|
.It
|
|
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).
|
|
.El
|
|
.Ss System calls.
|
|
The first area is symbolic links used as file name arguments for
|
|
system calls.
|
|
.Pp
|
|
Except as noted below, all system calls follow symbolic links.
|
|
For example, if there were a symbolic link
|
|
.Dq Li slink
|
|
which pointed to a file named
|
|
.Dq Li afile ,
|
|
the system call
|
|
.Dq Li open("slink" ...\&)
|
|
would return a file descriptor to the file
|
|
.Dq afile .
|
|
.Pp
|
|
There are thirteen system calls that do not follow links, and which operate
|
|
on the symbolic link itself.
|
|
They are:
|
|
.Xr lchflags 2 ,
|
|
.Xr lchmod 2 ,
|
|
.Xr lchown 2 ,
|
|
.Xr lpathconf 2 ,
|
|
.Xr lstat 2 ,
|
|
.Xr lutimes 2 ,
|
|
.Xr readlink 2 ,
|
|
.Xr readlinkat 2 ,
|
|
.Xr rename 2 ,
|
|
.Xr renameat 2 ,
|
|
.Xr rmdir 2 ,
|
|
.Xr unlink 2 ,
|
|
and
|
|
.Xr unlinkat 2 .
|
|
Because
|
|
.Xr remove 3
|
|
is an alias for
|
|
.Xr unlink 2 ,
|
|
it also does not follow symbolic links.
|
|
When
|
|
.Xr rmdir 2
|
|
or
|
|
.Xr unlinkat 2
|
|
with the
|
|
.Dv AT_REMOVEDIR
|
|
flag
|
|
is applied to a symbolic link, it fails with the error
|
|
.Er ENOTDIR .
|
|
.Pp
|
|
The
|
|
.Xr linkat 2
|
|
system call does not follow symbolic links
|
|
unless given the
|
|
.Dv AT_SYMLINK_FOLLOW
|
|
flag.
|
|
.Pp
|
|
The following system calls follow symbolic links
|
|
unless given the
|
|
.Dv AT_SYMLINK_NOFOLLOW
|
|
flag:
|
|
.Xr chflagsat 2 ,
|
|
.Xr fchmodat 2 ,
|
|
.Xr fchownat 2 ,
|
|
.Xr fstatat 2
|
|
and
|
|
.Xr utimensat 2 .
|
|
.Pp
|
|
The owner and group of an existing symbolic link can be changed by
|
|
means of the
|
|
.Xr lchown 2
|
|
system call.
|
|
The flags, access permissions, owner/group and modification time of
|
|
an existing symbolic link can be changed by means of the
|
|
.Xr lchflags 2 ,
|
|
.Xr lchmod 2 ,
|
|
.Xr lchown 2 ,
|
|
and
|
|
.Xr lutimes 2
|
|
system calls, respectively.
|
|
Of these, only the flags and ownership are used by the system;
|
|
the access permissions are ignored.
|
|
.Pp
|
|
The
|
|
.Bx 4.4
|
|
system differs from historical
|
|
.Bx 4
|
|
systems in that the system call
|
|
.Xr chown 2
|
|
has been changed to follow symbolic links.
|
|
The
|
|
.Xr lchown 2
|
|
system call was added later when the limitations of the new
|
|
.Xr chown 2
|
|
became apparent.
|
|
.Ss Commands not traversing a file tree.
|
|
The second area is symbolic links, specified as command line file
|
|
name 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
|
|
.Dq Li slink
|
|
which pointed to a file named
|
|
.Dq Li afile ,
|
|
the command
|
|
.Dq Li cat slink
|
|
would display the contents of the file
|
|
.Dq Li afile .
|
|
.Pp
|
|
It is important to realize that this rule includes commands which may
|
|
optionally traverse file trees, e.g.\& the command
|
|
.Dq Li "chown file"
|
|
is included in this rule, while the command
|
|
.Dq Li "chown -R file"
|
|
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, e.g., it is desired that
|
|
.Dq Li "chown slink"
|
|
change the ownership of the file that
|
|
.Dq Li slink
|
|
is, whether it is a symbolic link or not, the
|
|
.Fl h
|
|
option should be used.
|
|
In the above example,
|
|
.Dq Li "chown root slink"
|
|
would change the ownership of the file referenced by
|
|
.Dq Li slink ,
|
|
while
|
|
.Dq Li "chown -h root slink"
|
|
would change the ownership of
|
|
.Dq Li slink
|
|
itself.
|
|
.Pp
|
|
There are five exceptions to this rule.
|
|
The
|
|
.Xr mv 1
|
|
and
|
|
.Xr 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.)
|
|
.Pp
|
|
The
|
|
.Xr ls 1
|
|
command is also an exception to this rule.
|
|
For compatibility with historic systems (when
|
|
.Nm ls
|
|
is not doing a tree walk, i.e., the
|
|
.Fl R
|
|
option is not specified),
|
|
the
|
|
.Nm ls
|
|
command follows symbolic links named as arguments if the
|
|
.Fl H
|
|
or
|
|
.Fl L
|
|
option is specified,
|
|
or if the
|
|
.Fl F ,
|
|
.Fl d
|
|
or
|
|
.Fl l
|
|
options are not specified.
|
|
(The
|
|
.Nm ls
|
|
command is the only command where the
|
|
.Fl H
|
|
and
|
|
.Fl L
|
|
options affect its behavior even though it is not doing a walk of
|
|
a file tree.)
|
|
.Pp
|
|
The
|
|
.Xr file 1
|
|
and
|
|
.Xr stat 1
|
|
commands are also exceptions to this rule.
|
|
These
|
|
commands do not follow symbolic links named as argument by default,
|
|
but do follow symbolic links named as argument if the
|
|
.Fl L
|
|
option is specified.
|
|
.Pp
|
|
The
|
|
.Bx 4.4
|
|
system differs from historical
|
|
.Bx 4
|
|
systems in that the
|
|
.Nm chown
|
|
and
|
|
.Nm chgrp
|
|
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:
|
|
.Xr chflags 1 ,
|
|
.Xr chgrp 1 ,
|
|
.Xr chmod 1 ,
|
|
.Xr cp 1 ,
|
|
.Xr du 1 ,
|
|
.Xr find 1 ,
|
|
.Xr ls 1 ,
|
|
.Xr pax 1 ,
|
|
.Xr rm 1 ,
|
|
.Xr tar 1
|
|
and
|
|
.Xr chown 8 .
|
|
.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 first rule applies to symbolic links that reference files that are
|
|
not of type directory.
|
|
Operations that apply to symbolic links are performed on the links
|
|
themselves, but otherwise the links are ignored.
|
|
.Pp
|
|
The command
|
|
.Dq Li "rm -r slink directory"
|
|
will remove
|
|
.Dq Li slink ,
|
|
as well as any symbolic links encountered in the tree traversal of
|
|
.Dq Li directory ,
|
|
because symbolic links may be removed.
|
|
In no case will
|
|
.Nm rm
|
|
affect the file which
|
|
.Dq Li slink
|
|
references in any way.
|
|
.Pp
|
|
The second rule applies to symbolic links that reference files of type
|
|
directory.
|
|
Symbolic links which reference files of type directory are never
|
|
.Dq followed
|
|
by default.
|
|
This is often referred to as a
|
|
.Dq physical
|
|
walk, as opposed to a
|
|
.Dq logical
|
|
walk (where symbolic links referencing directories are followed).
|
|
.Pp
|
|
As consistently as possible, you can make commands doing a file tree
|
|
walk follow any symbolic links named on the command line, regardless
|
|
of the type of file they reference, by specifying the
|
|
.Fl H
|
|
(for
|
|
.Dq 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
|
|
.Fl H
|
|
flag will be ignored if the
|
|
.Fl R
|
|
flag is not also specified.)
|
|
.Pp
|
|
For example, the command
|
|
.Dq Li "chown -HR user slink"
|
|
will traverse the file hierarchy rooted in the file pointed to by
|
|
.Dq Li slink .
|
|
Note, the
|
|
.Fl H
|
|
is not the same as the previously discussed
|
|
.Fl h
|
|
flag.
|
|
The
|
|
.Fl H
|
|
flag causes symbolic links specified on the command line to be
|
|
dereferenced both for the purposes of 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.
|
|
.Pp
|
|
As consistently as possible, you can make commands doing a file tree
|
|
walk 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
|
|
.Fl L
|
|
(for
|
|
.Dq 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
|
|
.Fl L
|
|
flag will be ignored if the
|
|
.Fl R
|
|
flag is not also specified.)
|
|
.Pp
|
|
For example, the command
|
|
.Dq Li "chown -LR user slink"
|
|
will change the owner of the file referenced by
|
|
.Dq Li slink .
|
|
If
|
|
.Dq Li slink
|
|
references a directory,
|
|
.Nm 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
|
|
.Nm chown
|
|
traverses, they will be treated in the same fashion as
|
|
.Dq Li slink .
|
|
.Pp
|
|
As consistently as possible, you can specify the default behavior by
|
|
specifying the
|
|
.Fl P
|
|
(for
|
|
.Dq 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
|
|
.Fl H ,
|
|
.Fl L
|
|
and
|
|
.Fl P
|
|
flags are ignored if the
|
|
.Fl R
|
|
flag is not also specified.
|
|
In addition, you may specify the
|
|
.Fl H ,
|
|
.Fl L
|
|
and
|
|
.Fl 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
|
|
.Xr ls 1
|
|
and
|
|
.Xr rm 1
|
|
commands have exceptions to these rules.
|
|
The
|
|
.Nm rm
|
|
command operates on the symbolic link, and not the file it references,
|
|
and therefore never follows a symbolic link.
|
|
The
|
|
.Nm rm
|
|
command does not support the
|
|
.Fl H ,
|
|
.Fl L
|
|
or
|
|
.Fl P
|
|
options.
|
|
.Pp
|
|
To maintain compatibility with historic systems,
|
|
the
|
|
.Nm ls
|
|
command acts a little differently.
|
|
If you do not specify the
|
|
.Fl F ,
|
|
.Fl d
|
|
or
|
|
.Fl l
|
|
options,
|
|
.Nm ls
|
|
will follow symbolic links specified on the command line.
|
|
If the
|
|
.Fl L
|
|
flag is specified,
|
|
.Nm ls
|
|
follows all symbolic links,
|
|
regardless of their type,
|
|
whether specified on the command line or encountered in the tree walk.
|
|
.Sh SEE ALSO
|
|
.Xr chflags 1 ,
|
|
.Xr chgrp 1 ,
|
|
.Xr chmod 1 ,
|
|
.Xr cp 1 ,
|
|
.Xr du 1 ,
|
|
.Xr find 1 ,
|
|
.Xr ln 1 ,
|
|
.Xr ls 1 ,
|
|
.Xr mv 1 ,
|
|
.Xr pax 1 ,
|
|
.Xr rm 1 ,
|
|
.Xr tar 1 ,
|
|
.Xr lchflags 2 ,
|
|
.Xr lchmod 2 ,
|
|
.Xr lchown 2 ,
|
|
.Xr lstat 2 ,
|
|
.Xr lutimes 2 ,
|
|
.Xr readlink 2 ,
|
|
.Xr rename 2 ,
|
|
.Xr symlink 2 ,
|
|
.Xr unlink 2 ,
|
|
.Xr fts 3 ,
|
|
.Xr remove 3 ,
|
|
.Xr chown 8
|