606 lines
15 KiB
Groff
606 lines
15 KiB
Groff
.\" $NetBSD: symlink.7,v 1.23 2014/01/10 09:44:30 wiz 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 January 9, 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, 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 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.
|
|
.Pp
|
|
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 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 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
|
|
.Qq follow
|
|
the link.
|
|
.Pp
|
|
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, 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
|
|
.Qq Li slink
|
|
which pointed to a file named
|
|
.Qq Li afile ,
|
|
the system call
|
|
.Qq Li open("slink" ...)
|
|
would return a file descriptor to the file
|
|
.Qq afile .
|
|
.Pp
|
|
There are eight 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 lstat 2 ,
|
|
.Xr lutimes 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
|
|
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.
|
|
.Pp
|
|
If the filesystem is mounted with the
|
|
.Em symperm
|
|
.Xr mount 8
|
|
option, the symbolic link file permission bits have the following effects:
|
|
.Pp
|
|
The
|
|
.Xr readlink 2
|
|
system call requires read permissions on the symbolic link.
|
|
.Pp
|
|
System calls that follow symbolic links will fail without execute/search
|
|
permissions on all the symbolic links followed.
|
|
.Pp
|
|
The write, sticky, set-user-ID-on-execution and set-group-ID-on-execution
|
|
symbolic link mode bits have no effect on any system calls
|
|
.Po
|
|
including
|
|
.Xr execve 2
|
|
.Pc .
|
|
.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
|
|
.Qq Li slink
|
|
which pointed to a file named
|
|
.Qq Li afile ,
|
|
the command
|
|
.Qq Li cat slink
|
|
would display the contents of the file
|
|
.Qq Li afile .
|
|
.Pp
|
|
It is important to realize that this rule includes commands which may
|
|
optionally traverse file trees, e.g.
|
|
the command
|
|
.Qq Li "chown file"
|
|
is included in this rule, while the command
|
|
.Qq 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
|
|
.Qq Li "file slink"
|
|
display the type of file that
|
|
.Qq Li slink
|
|
is, whether it is a symbolic link or not, the
|
|
.Fl h
|
|
option should be used.
|
|
In the above example,
|
|
.Qq Li "file slink"
|
|
would report the type of the file referenced by
|
|
.Qq Li slink ,
|
|
while
|
|
.Qq Li "file -h slink"
|
|
would report that
|
|
.Qq Li slink
|
|
was a symbolic link.
|
|
.Pp
|
|
There are three 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 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.
|
|
.Nm ls
|
|
is the only command where the
|
|
.Fl L
|
|
option affects its behavior even though it is not doing a walk of
|
|
a file tree).
|
|
.Pp
|
|
The
|
|
.Bx 4.4
|
|
system differs from historical
|
|
.Bx 4
|
|
systems in that the
|
|
.Nm chown ,
|
|
.Nm chgrp
|
|
and
|
|
.Nm file
|
|
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
|
|
For example, the command
|
|
.Qq Li "chown -R user slink directory"
|
|
will ignore
|
|
.Qq Li slink ,
|
|
because the
|
|
.Fl h
|
|
flag must be used to change owners of symbolic links.
|
|
Any symbolic links encountered during the tree traversal will also be
|
|
ignored.
|
|
The command
|
|
.Qq Li "rm -r slink directory"
|
|
will remove
|
|
.Qq Li slink ,
|
|
as well as any symbolic links encountered in the tree traversal of
|
|
.Qq Li directory ,
|
|
because symbolic links may be removed.
|
|
In no case will either
|
|
.Nm chown
|
|
or
|
|
.Nm rm
|
|
affect the file which
|
|
.Qq 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
|
|
.Qq followed
|
|
by default.
|
|
This is often referred to as a
|
|
.Qq physical
|
|
walk, as opposed to a
|
|
.Qq 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
|
|
.Qq 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
|
|
.Qq Li "chown -HR user slink"
|
|
will traverse the file hierarchy rooted in the file pointed to by
|
|
.Qq 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
|
|
.Qq 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
|
|
.Qq Li "chown -LR user slink"
|
|
will change the owner of the file referenced by
|
|
.Qq Li slink .
|
|
If
|
|
.Qq 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
|
|
.Qq Li slink .
|
|
.Pp
|
|
As consistently as possible, you can specify the default behavior by
|
|
specifying the
|
|
.Fl P
|
|
(for
|
|
.Qq 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 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.
|
|
.Ss Magic symlinks
|
|
So-called
|
|
.Dq magic symlinks
|
|
can be enabled by setting the
|
|
.Dq vfs.generic.magiclinks
|
|
variable with
|
|
.Xr sysctl 8 .
|
|
When magic symlinks are enabled
|
|
.Dq magic
|
|
patterns in symlinks are expanded.
|
|
Those patterns begin with
|
|
.Dq @
|
|
.Pq an at-sign ,
|
|
and end at the end of the pathname component
|
|
.Po
|
|
i.e. at the next
|
|
.Dq / ,
|
|
or at the end of the symbolic link if there are no more slashes
|
|
.Pc .
|
|
.Pp
|
|
To illustrate the pattern matching rules, assume that
|
|
.Dq @foo
|
|
is a valid magic string:
|
|
.Pp
|
|
.Bl -tag -width @foo/barxxxxx -offset indent -compact
|
|
.It @foo
|
|
would be matched
|
|
.It @foo/bar
|
|
would be matched
|
|
.It bar@foo
|
|
would be matched
|
|
.It @foobar
|
|
would not be matched
|
|
.El
|
|
.Pp
|
|
Magic strings may also be delimited with
|
|
.Sq {
|
|
and
|
|
.Sq }
|
|
characters, allowing for more complex patterns in symbolic links such as:
|
|
.Bd -literal -offset indent
|
|
@{var1}-@{var2}.@{var3}
|
|
.Ed
|
|
.Pp
|
|
The following patterns are supported:
|
|
.Bl -tag -width @machine_arch -offset indent
|
|
.It @domainname
|
|
Expands to the machine's domain name, as set by
|
|
.Xr setdomainname 3 .
|
|
.It @hostname
|
|
Expands to the machine's host name, as set by
|
|
.Xr sethostname 3 .
|
|
.It @emul
|
|
Expands to the name of the current process's emulation.
|
|
Defaults to
|
|
.Dv netbsd .
|
|
Other valid emulations are:
|
|
.Dv aout ,
|
|
.Dv aoutm68k ,
|
|
.Dv darwin ,
|
|
.Dv freebsd ,
|
|
.Dv ibcs2 ,
|
|
.Dv linux ,
|
|
.Dv linux32 ,
|
|
.Dv m68k4k ,
|
|
.Dv netbsd32 ,
|
|
.Dv osf1 ,
|
|
.Dv sunos ,
|
|
.Dv sunos32 ,
|
|
.Dv svr4 ,
|
|
.Dv svr4_32 ,
|
|
.Dv ultrix ,
|
|
.Dv vax1k .
|
|
.It @kernel_ident
|
|
Expands to the name of the
|
|
.Xr config 1
|
|
file used to generate the running kernel.
|
|
For example
|
|
.Dv GENERIC .
|
|
.It @machine
|
|
Expands to the value of
|
|
.Li MACHINE
|
|
for the system.
|
|
For native binaries, this is
|
|
equivalent to the output of
|
|
.Dq uname -m
|
|
or
|
|
.Xr sysctl 3
|
|
.Dq hw.machine .
|
|
.Po
|
|
For non-native binaries, the values returned by uname and sysctl
|
|
typically vary to match the emulation environment.
|
|
.Pc
|
|
.It @machine_arch
|
|
Expands to the value of
|
|
.Li MACHINE_ARCH
|
|
for the system.
|
|
For native binaries, this is
|
|
equivalent to the output of
|
|
.Dq uname -p
|
|
or
|
|
.Xr sysctl 3
|
|
.Dq hw.machine_arch .
|
|
.Po
|
|
For non-native binaries, the values returned by uname and sysctl
|
|
typically vary to match the emulation environment.
|
|
.Pc
|
|
.It @osrelease
|
|
Expands to the operating system release of the running kernel
|
|
.Po
|
|
equivalent to the output of
|
|
.Dq uname -r
|
|
or
|
|
.Xr sysctl 3
|
|
.Dq kern.osrelease
|
|
.Pc .
|
|
.It @ostype
|
|
Expands to the operating system type of the running kernel
|
|
.Po
|
|
equivalent to the output of
|
|
.Dq uname -s
|
|
or
|
|
.Xr sysctl 3
|
|
.Dq kern.ostype
|
|
.Pc .
|
|
This will always be
|
|
.Dq NetBSD
|
|
on
|
|
.Nx
|
|
systems.
|
|
.It @ruid
|
|
Expands to the real user-id of the process.
|
|
.It @uid
|
|
Expands to the effective user-id of the process.
|
|
.It @rgid
|
|
Expands to the real group-id of the process.
|
|
.It @gid
|
|
Expands to the effective group-id of the process.
|
|
.El
|
|
.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 uname 1 ,
|
|
.Xr chown 2 ,
|
|
.Xr execve 2 ,
|
|
.Xr lchflags 2 ,
|
|
.Xr lchmod 2 ,
|
|
.Xr lchown 2 ,
|
|
.Xr lstat 2 ,
|
|
.Xr lutimes 2 ,
|
|
.Xr mount 2 ,
|
|
.Xr readlink 2 ,
|
|
.Xr rename 2 ,
|
|
.Xr symlink 2 ,
|
|
.Xr unlink 2 ,
|
|
.Xr fts 3 ,
|
|
.Xr remove 3 ,
|
|
.Xr chown 8 ,
|
|
.Xr mount 8
|
|
.Sh HISTORY
|
|
Magic symlinks appeared in
|
|
.Nx 4.0 .
|