464 lines
12 KiB
Groff
464 lines
12 KiB
Groff
.\" $OpenBSD: symlink.7,v 1.19 2014/12/13 21:00:19 guenther Exp $
|
|
.\" $NetBSD: symlink.7,v 1.4 1996/04/25 15:44:56 mycroft Exp $
|
|
.\"
|
|
.\" 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.
|
|
.\" 3. 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
|
|
.\"
|
|
.Dd $Mdocdate: December 13 2014 $
|
|
.Dt SYMLINK 7
|
|
.Os
|
|
.Sh NAME
|
|
.Nm symlink
|
|
.Nd symbolic link handling
|
|
.Sh DESCRIPTION
|
|
Symbolic links are files that act as pointers to other files.
|
|
To understand their behavior, it is necessary to 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 a 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 filesystem
|
|
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 a more 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 doesn't 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, with an error resulting 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 at least five system calls that do not follow links, and which
|
|
operate on the symbolic link itself.
|
|
They are:
|
|
.Xr lchown 2 ,
|
|
.Xr lstat 2 ,
|
|
.Xr readlink 2 ,
|
|
.Xr rename 2 ,
|
|
and
|
|
.Xr unlink 2 .
|
|
Because
|
|
.Xr remove 3
|
|
is an alias for
|
|
.Xr unlink 2 ,
|
|
it also does not follow symbolic links.
|
|
.Pp
|
|
Additionally, the following system calls accept a
|
|
.Fa flag
|
|
argument to control whether or not to follow symbolic links:
|
|
.Xr chflagsat 2 ,
|
|
.Xr fchmodat 2 ,
|
|
.Xr fchownat 2 ,
|
|
.Xr fstatat 2 ,
|
|
.Xr linkat 2 ,
|
|
and
|
|
.Xr utimensat 2 .
|
|
.Pp
|
|
The
|
|
.Bx 4.4
|
|
system differs from historical 4BSD 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 owner file"
|
|
is included in this rule, while the command
|
|
.Dq Li "chown -R owner 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 owner slink"
|
|
change the ownership of
|
|
.Dq Li slink ,
|
|
not of what it points to -- the
|
|
.Fl h
|
|
option should be used.
|
|
In the above example,
|
|
.Dq Li "chown owner slink"
|
|
would change the owner of
|
|
.Dq Li afile
|
|
to
|
|
.Dq Li owner ,
|
|
while
|
|
.Dq Li "chown -h owner slink"
|
|
would change the ownership of
|
|
.Dq Li slink .
|
|
.Pp
|
|
There are several 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 that 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 L
|
|
option is specified,
|
|
or if the
|
|
.Fl F ,
|
|
.Fl d ,
|
|
or
|
|
.Fl l
|
|
options are not specified.
|
|
(If the
|
|
.Fl L
|
|
option is specified,
|
|
.Nm ls
|
|
always follows symbolic links.
|
|
The
|
|
.Fl L
|
|
option affects its behavior even though it is not doing a walk of
|
|
a file tree.)
|
|
.Pp
|
|
The
|
|
.Xr file 1
|
|
command behaves as
|
|
.Xr ls 1
|
|
in that the
|
|
.Fl L
|
|
option makes it follow a symbolic link.
|
|
By default,
|
|
.Dq Li "file slink"
|
|
will report that
|
|
.Dq Li slink
|
|
is a symbolic link.
|
|
This behavior is different from
|
|
.Xr file 1
|
|
on some other systems, where the
|
|
.Fl h
|
|
convention is followed.
|
|
.Pp
|
|
The
|
|
.Bx 4.4
|
|
system differs from historical 4BSD systems in that the
|
|
.Xr chown 8 ,
|
|
.Xr chgrp 1 ,
|
|
and
|
|
.Xr file 1
|
|
commands follow symbolic links specified on the command line
|
|
(unless the
|
|
.Fl h
|
|
option is used).
|
|
.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
|
|
For example, the command
|
|
.Dq Li "chown -R user slink directory"
|
|
will ignore
|
|
.Dq Li slink ,
|
|
because the
|
|
.Fl h
|
|
option was not given.
|
|
Any symbolic links encountered during the tree traversal will also be
|
|
ignored.
|
|
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 either
|
|
.Xr chown 8
|
|
or
|
|
.Xr rm 1
|
|
follow the symlink to affect the file which
|
|
.Dq Li slink
|
|
references.
|
|
.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, it is possible to 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 .
|
|
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, it is possible to 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, it is possible to 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, the
|
|
.Fl H ,
|
|
.Fl L ,
|
|
and
|
|
.Fl P
|
|
options may be specified more than once;
|
|
the last one specified determines the command's behavior.
|
|
This is intended to permit aliasing 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 never follows symbolic links unless the
|
|
.Fl L
|
|
flag is specified.
|
|
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.
|
|
The
|
|
.Nm ls
|
|
command does not support the
|
|
.Fl H
|
|
or
|
|
.Fl P
|
|
options.
|
|
.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 lchown 2 ,
|
|
.Xr lstat 2 ,
|
|
.Xr readlink 2 ,
|
|
.Xr rename 2 ,
|
|
.Xr symlink 2 ,
|
|
.Xr unlink 2 ,
|
|
.Xr fts 3 ,
|
|
.Xr remove 3 ,
|
|
.Xr chown 8
|