BSD 4.4 Lite bin Sources

1 files changed, 432 insertions, 0 deletions

diff --git a/bin/ln/symlink.7 b/bin/ln/symlink.7
new file mode 100644
index 0000000..0f4887d
--- /dev/null
+++ b/bin/ln/symlink.7
@@ -0,0 +1,432 @@
+.\" 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. 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.3 (Berkeley) 3/31/94
+.\"
+.Dd March 31, 1994
+.Dt SYMLINK 7
+.Os BSD 4
+.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 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
+.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, and an error results if this limit is
+exceeded.)
+.Pp
+There are three separate areas that need to be discussed.
+They are as follows:
+.sp
+.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 four system calls that do not follow links, and which operate
+on the symbolic link itself.
+They are:
+.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
+Unlike other filesystem objects, symbolic links do not have an owner,
+group, permissions, access and modification times, etc.
+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).
+The other attributes are filled in from the directory that contains
+the link.
+For portability reasons, you should be aware that other implementations
+(including historic implementations of 4BSD), implement symbolic links
+such that they have the same attributes as any other file.
+.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.
+.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 "file slink"
+display the type of 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 "file slink"
+would report the type of the file referenced by
+.Dq Li slink ,
+while
+.Dq Li "file -h slink"
+would report that
+.Dq 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 4BSD 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
+.Dq Li "chown -R user slink directory"
+will ignore
+.Dq Li slink ,
+because symbolic links in this system do not have owners.
+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
+.Nm chown
+or
+.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 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 lstat 2 ,
+.Xr readlink 2 ,
+.Xr rename 2 ,
+.Xr unlink 2 ,
+.Xr fts 3 ,
+.Xr remove 3 ,
+.Xr chown 8