4.4BSD/usr/src/bin/ln/symlink.7

Compare this file to the similar file:
Show the results in this format:
.\" Copyright (c) 1992, 1993
.\"	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. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed by the University of
.\"	California, Berkeley and its contributors.
.\" 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.1 (Berkeley) 5/31/93
.\"
.Dd May 31, 1993
.Dt SYMLINK 7
.Os BSD 4
.Sh NAME
.Nm symlink
.Nd symbolic link handling
.Sh SYMBOLIC LINK HANDLING
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.
Traditionally, utilities and system calls
have adopted their own link following conventions in an ad-hoc fashion.
Rules for more a uniform approach are outlined here.
.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 ``follow'' the link.
Symbolic links may reference other symbolic links, in which case links are
dereferenced until an object that is not a symbolic link is found.
Cycles are avoided by
placing an upper limit on the number of links that may be followed.
An error results if this limit is exceeded.
.Pp
There are three domains for which symbolic link policy is established:
system calls that take file name arguments,
utilities that take file name arguments, and
utilities that traverse file hierarchies.
.Pp
The system calls that do not follow symbolic links are
.Xr lstat 2 ,
.Xr readlink 2 ,
.Xr rename 2 ,
and
.Xr unlink 2 .
All other system calls follow the symbolic link.
Unlike other filesystem objects,
symbolic links do not have an owner, group, access mode, times, etc.
Instead, these attributes are taken from the directory that
contains the link.
The only attributes returned from an
.Xr lstat 2
that refer to the symbolic link itself are the file type (S_IFLNK),
size, blocks, and link count (always 1).
.Pp
The utilities that do not follow symbolic links named as arguments
are
.Xr mv 1
and
.Xr rm 1 .
For compatibility with historic systems, the 
.Xr ls 1
utility follows symbolic links listed on the command line, unless the
.Fl F ,
.Fl d
or
.Fl l 
options are specified.
However, if the
.Fl L
option is specified,
.Xr ls 1
always follows symbolic links.
All other utilities follow symbolic links listed on the command line.
.Pp
The third issue in symbolic link handling is traversal of a file
hierarchy.
File hierarchies can be traversed either ``logically'', by following
symbolic links that point to directories, or ``physically'', by not
following such links.
.Pp
The following utilities can do traversals:
.Xr chflags 1 ,
.Xr chgrp 1 ,
.Xr chmod 1 ,
.Xr chown 8 ,
.Xr cp 1 ,
.Xr du 1 ,
.Xr find 1 ,
.Xr ls 1 ,
.Xr rm 1
and
.Xr tar 1 .
All these utilities, except for
.Xr cp ,
.Xr ls
and
.Xr rm ,
operate according to the following rules.
.Pp
By default, these utilities do a physical traversal, never following any
symbolic links.
If the
.Fl H 
option is specified, the utility will follow symbolic links specified
on the command line.
If the
.Fl h
option is specified, the utilities do a logical traversal, following all
symbolic links whether specified on the command line or encountered while
descending the file hierarchy.
The
.Fl H
flag is intended to make the command line name space look like the logical
name space and the
.Fl h
flag is intended to make the entire hierarchy look like the logical name
space.
.Pp
The utilities
.Xr cp , 
.Xr ls
and
.Xr rm
are exceptions to these rules.
.Pp
To maintain compatibility with historic systems,
.Xr cp
always follows symbolic links on the command line.
The 
.Fl H
and 
.Fl h
options have the effects described above only when the
.Fl R 
flag is specified.
.Pp
.Xr Rm
operates on the name, not the object it points to, and therefore never
follows a symbolic link.
The
.Xr rm
utility does not support the
.Fl H
or
.Fl h
options.
.Pp
To maintain compatibility with historic systems, the
.Xr ls
utility follows all symbolic links in the file hierarchy, including ones
listed on the command line, only when the 
.Fl L 
option is specified.
The
.Xr ls
utility does not support the
.Fl H
or
.Fl h
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 rm 1 ,
.Xr tar 1 ,
.Xr lstat 2 ,
.Xr readlink 2 ,
.Xr rename 2 ,
.Xr unlink 2 ,
.Xr chown 8