file_cmds-321.100.10.0.1.tar.gz

[apple/file_cmds.git] / ln / symlink.7

diff --git a/ln/symlink.7 b/ln/symlink.7
index 7e6e68a2a5f06e62be0167124107fa7a2281ad14..7c6c7576eb9b415127a0fa481e0d629283b02819 100644 (file)
--- a/ln/symlink.7
+++ b/ln/symlink.7
@@ -1,5 +1,4 @@
-.\"    $NetBSD: symlink.7,v 1.7 1998/02/06 05:39:47 perry Exp $
-.\"
+.\"-

 .\" Copyright (c) 1992, 1993, 1994
 .\"    The Regents of the University of California.  All rights reserved.
 .\"
 .\" Copyright (c) 1992, 1993, 1994
 .\"    The Regents of the University of California.  All rights reserved.
 .\"


@@ -11,10 +10,6 @@
 .\" 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.
 .\" 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.
 .\" 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.


@@ -32,10 +27,11 @@
 .\" SUCH DAMAGE.
 .\"
 .\"    @(#)symlink.7   8.3 (Berkeley) 3/31/94
 .\" SUCH DAMAGE.
 .\"
 .\"    @(#)symlink.7   8.3 (Berkeley) 3/31/94

+.\" $FreeBSD: src/bin/ln/symlink.7,v 1.30 2005/02/13 22:25:09 ru Exp $

 .\"
 .Dd March 31, 1994
 .Dt SYMLINK 7
 .\"
 .Dd March 31, 1994
 .Dt SYMLINK 7

-.Os BSD 4
+.Os

 .Sh NAME
 .Nm symlink
 .Nd symbolic link handling
 .Sh NAME
 .Nm symlink
 .Nd symbolic link handling


@@ -50,11 +46,11 @@ 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,
 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.
+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
 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
+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
 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


@@ -73,7 +69,7 @@ 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,
 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,
+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
 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


@@ -81,7 +77,7 @@ exceeded.)
 .Pp
 There are three separate areas that need to be discussed.
 They are as follows:
 .Pp
 There are three separate areas that need to be discussed.
 They are as follows:

-.sp
+.Pp

 .Bl -enum -compact -offset indent
 .It
 Symbolic links used as file name arguments for system calls.
 .Bl -enum -compact -offset indent
 .It
 Symbolic links used as file name arguments for system calls.


@@ -103,16 +99,21 @@ For example, if there were a symbolic link
 which pointed to a file named
 .Dq Li afile ,
 the system call
 which pointed to a file named
 .Dq Li afile ,
 the system call

-.Dq Li open("slink" ...)
+.Dq Li open("slink" ...\&)

 would return a file descriptor to the file
 .Dq afile .
 .Pp
 would return a file descriptor to the file
 .Dq afile .
 .Pp

-There are four system calls that do not follow links, and which operate
+There are nine system calls that do not follow links, and which operate

 on the symbolic link itself.
 They are:
 on the symbolic link itself.
 They are:

+.Xr lchflags 2 ,
+.Xr lchmod 2 ,
+.Xr lchown 2 ,

 .Xr lstat 2 ,
 .Xr lstat 2 ,

+.Xr lutimes 3 ,

 .Xr readlink 2 ,
 .Xr rename 2 ,
 .Xr readlink 2 ,
 .Xr rename 2 ,

+.Xr rmdir 2 ,

 and
 .Xr unlink 2 .
 Because
 and
 .Xr unlink 2 .
 Because


@@ -120,21 +121,45 @@ Because
 is an alias for
 .Xr unlink 2 ,
 it also does not follow symbolic links.
 is an alias for
 .Xr unlink 2 ,
 it also does not follow symbolic links.

+When
+.Xr rmdir 2
+is applied to a symbolic link, it fails with the error
+.Er ENOTDIR .
+.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 3
+system calls, respectively.
+Of these, only the flags are used by the system;
+the access permissions and ownership are ignored.

 .Pp
 The
 .Bx 4.4
 .Pp
 The
 .Bx 4.4

-system differs from historical 
+system differs from historical

 .Bx 4
 systems in that the system call
 .Xr chown 2
 has been changed to follow symbolic links.
 .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.
 .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 
+For example, if there were a symbolic link

 .Dq Li slink
 which pointed to a file named
 .Dq Li afile ,
 .Dq Li slink
 which pointed to a file named
 .Dq Li afile ,


@@ -144,7 +169,7 @@ would display the contents of the file
 .Dq Li afile .
 .Pp
 It is important to realize that this rule includes commands which may
 .Dq Li afile .
 .Pp
 It is important to realize that this rule includes commands which may

-optionally traverse file trees, e.g. the command
+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"
 .Dq Li "chown file"
 is included in this rule, while the command
 .Dq Li "chown -R file"


@@ -153,23 +178,23 @@ is not.
 .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
 .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 "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 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 "chown root slink"
+would change the ownership of the file referenced by

 .Dq Li slink ,
 while
 .Dq Li slink ,
 while

-.Dq Li "file -h slink"
-would report that
+.Dq Li "chown -h root slink"
+would change the ownership of

 .Dq Li slink
 .Dq Li slink

-was a symbolic link.
+itself.

 .Pp
 .Pp

-There are three exceptions to this rule.
+There are four exceptions to this rule.

 The
 .Xr mv 1
 and
 The
 .Xr mv 1
 and


@@ -185,12 +210,14 @@ The
 command is also an exception to this rule.
 For compatibility with historic systems (when
 .Nm ls
 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
+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 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 L
 option is specified,
 or if the


@@ -199,26 +226,35 @@ or if the
 or
 .Fl l
 options are not specified.
 or
 .Fl l
 options are not specified.

-(If the
-.Fl L
-option is specified,
-.Nm ls
-always follows symbolic links.
+(The

 .Nm ls
 .Nm ls

-is the only command where the
+command is the only command where the
+.Fl H
+and

 .Fl L
 .Fl L

-option affects its behavior even though it is not doing a walk of
+options affect its behavior even though it is not doing a walk of

 a file tree.)
 .Pp
 The
 a file tree.)
 .Pp
 The

+.Xr file 1
+command is also an exception to this rule.
+The
+.Xr file 1
+command does not follow symbolic links named as argument by default.
+The
+.Xr file 1
+command does follow symbolic links named as argument if
+.Fl L
+option is specified.
+.Pp
+The

 .Bx 4.4
 system differs from historical
 .Bx 4
 systems in that the
 .Bx 4.4
 system differs from historical
 .Bx 4
 systems in that the

-.Nm chown ,
-.Nm chgrp
+.Nm chown

 and
 and

-.Nm file
+.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:
 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:


@@ -244,13 +280,6 @@ not of type directory.
 Operations that apply to symbolic links are performed on the links
 themselves, but otherwise the links are ignored.
 .Pp
 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
 The command
 .Dq Li "rm -r slink directory"
 will remove


@@ -258,9 +287,7 @@ will remove
 as well as any symbolic links encountered in the tree traversal of
 .Dq Li directory ,
 because symbolic links may be removed.
 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
+In no case will

 .Nm rm
 affect the file which
 .Dq Li slink
 .Nm rm
 affect the file which
 .Dq Li slink


@@ -280,7 +307,7 @@ walk (where symbolic links referencing directories are followed).
 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
 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 
+.Fl H

 (for
 .Dq half\-logical )
 flag.
 (for
 .Dq half\-logical )
 flag.


@@ -387,9 +414,15 @@ options.
 To maintain compatibility with historic systems,
 the
 .Nm ls
 To maintain compatibility with historic systems,
 the
 .Nm ls

-command never follows symbolic links unless the
-.Fl L
-flag is specified.
+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,
 If the
 .Fl L
 flag is specified,


@@ -397,13 +430,6 @@ flag is specified,
 follows all symbolic links,
 regardless of their type,
 whether specified on the command line or encountered in the tree walk.
 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 ,
 .Sh SEE ALSO
 .Xr chflags 1 ,
 .Xr chgrp 1 ,


@@ -417,7 +443,11 @@ options.
 .Xr pax 1 ,
 .Xr rm 1 ,
 .Xr tar 1 ,
 .Xr pax 1 ,
 .Xr rm 1 ,
 .Xr tar 1 ,

+.Xr lchflags 2 ,
+.Xr lchmod 2 ,
+.Xr lchown 2 ,

 .Xr lstat 2 ,
 .Xr lstat 2 ,

+.Xr lutimes 3 ,

 .Xr readlink 2 ,
 .Xr rename 2 ,
 .Xr symlink 2 ,
 .Xr readlink 2 ,
 .Xr rename 2 ,
 .Xr symlink 2 ,