From a4a7cf28d924998f49ce73eb266b208deda92454 Mon Sep 17 00:00:00 2001 From: Keith Bostic Date: Thu, 31 Mar 1994 19:54:46 -0800 Subject: [PATCH] rework to reflect POSIX 1003.2 symlinks SCCS-vsn: bin/ln/symlink.7 8.2 --- usr/src/bin/ln/symlink.7 | 430 ++++++++++++++++++++++++++++++--------- 1 file changed, 330 insertions(+), 100 deletions(-) diff --git a/usr/src/bin/ln/symlink.7 b/usr/src/bin/ln/symlink.7 index 493048db82..9aa68c30c3 100644 --- a/usr/src/bin/ln/symlink.7 +++ b/usr/src/bin/ln/symlink.7 @@ -1,9 +1,9 @@ -.\" Copyright (c) 1992, 1993 +.\" Copyright (c) 1992, 1993, 1994 .\" The Regents of the University of California. All rights reserved. .\" .\" %sccs.include.redist.roff% .\" -.\" @(#)symlink.7 8.1 (Berkeley) %G% +.\" @(#)symlink.7 8.2 (Berkeley) %G% .\" .Dd .Dt SYMLINK 7 @@ -12,150 +12,377 @@ .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 +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. -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. +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 is 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. +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 +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 . -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. +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 -The utilities that do not follow symbolic links named as arguments -are +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 . -For compatibility with historic systems, the +.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 -utility follows symbolic links listed on the command line, unless the +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 specified. -However, if the +.Fl l +options are not specified. +(If the .Fl L option is specified, -.Xr ls 1 +.Nm ls 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. +.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 following utilities can do traversals: +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 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 +.Xr pax 1 , +.Xr rm 1 , +.Xr tar 1 and -.Xr rm , -operate according to the following rules. +.Xr chown 8 . .Pp -By default, these utilities do a physical traversal, never following any -symbolic links. -If the +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 -option is specified, the utility will follow symbolic links specified -on the command line. -If the +(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 -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. +flag. 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. +flag causes symbolic links specified on the command line to be +dereferenced for the purposes of the tree walk, and it is as if the +user had specified the name of the file to which the symbolic link +pointed. .Pp -The utilities -.Xr cp , -.Xr ls -and -.Xr rm -are exceptions to these rules. +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 -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. +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, the last one +.Fl H , +.Fl L +and +.Fl P +specified determines the command's behavior. +This is intended to permit you to alias commands to behave one way +or the other, and then specify or override that behavior on the +command line. .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 +.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 h +.Fl P 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. +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 -.Xr ls -utility does not support the +.Nm ls +command does not support the .Fl H or -.Fl h +.Fl P options. .Sh SEE ALSO .Xr chflags 1 , @@ -167,10 +394,13 @@ options. .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 -- 2.20.1