xbd_chap03.html

IEEE 1003.1-2003, Single Unix Specification v3

containing the link be used for this purpose. Implementations may choose to use either of these methods; however, this is not
current practice and neither method is specified.</p>

<p>Several reasons were advanced for requiring that when a symbolic link is used as the source argument to the <a href=
"../functions/link.html"><i>link</i>()</a> function, the resulting link will apply to the file named by the contents of the
symbolic link rather than to the symbolic link itself. This is the case in historical implementations. This action was preferred,
as it supported the traditional idea of persistence with respect to the target of a hard link. This decision is appropriate in
light of a previous decision not to require association of attributes with symbolic links, thereby allowing implementations which
do not use inodes. Opposition centered on the lack of symmetry on the part of the <a href=
"../functions/link.html"><i>link</i>()</a> and <a href="../functions/unlink.html"><i>unlink</i>()</a> function pair with respect to
symbolic links.</p>

<p>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, utilities and system calls have adopted their own link following
conventions in a somewhat <i>ad hoc</i> fashion. Rules for a uniform approach are outlined here, although historical practice has
been adhered to as much as was possible. To promote consistent system use, user-written utilities are encouraged to follow these
same rules.</p>

<p>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 &quot;follow&quot; 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, a symbolic link that references a file that
does not exist is found, or a loop is detected. (Current implementations do not detect loops, but have a limit on the number of
symbolic links that they will dereference before declaring it an error.)</p>

<p>There are four domains for which default symbolic link policy is established in a system. In almost all cases, there are utility
options that override this default behavior. The four domains are as follows:</p>

<ol>
<li>
<p>Symbolic links specified to system calls that take filename arguments</p>
</li>

<li>
<p>Symbolic links specified as command line filename arguments to utilities that are not performing a traversal of a file
hierarchy</p>
</li>

<li>
<p>Symbolic links referencing files not of type directory, specified to utilities that are performing a traversal of a file
hierarchy</p>
</li>

<li>
<p>Symbolic links referencing files of type directory, specified to utilities that are performing a traversal of a file
hierarchy</p>
</li>
</ol>

<br>
<p><i>First Domain</i></p>

<p>The first domain is considered in earlier rationale.<br>
</p>

<p><i>Second Domain</i></p>

<p>The reason this category is restricted to utilities that are not traversing the file hierarchy is that some standard utilities
take an option that specifies a hierarchical traversal, but by default operate on the arguments themselves. Generally, users
specifying the option for a file hierarchy traversal wish to operate on a single, physical hierarchy, and therefore symbolic links,
which may reference files outside of the hierarchy, are ignored. For example, <a href="../utilities/chown.html"><i>chown</i></a>
<i>owner file</i> is a different operation from the same command with the <b>-R</b> option specified. In this example, the behavior
of the command <a href="../utilities/chown.html"><i>chown</i></a> <i>owner file</i> is described here, while the behavior of the
command <a href="../utilities/chown.html"><i>chown</i></a> <b>-R</b> <i>owner file</i> is described in the third and fourth
domains.</p>

<p>The general rule is that the utilities in this category follow symbolic links named as arguments.</p>

<p>Exceptions in the second domain are:</p>

<ul>
<li>
<p>The <a href="../utilities/mv.html"><i>mv</i></a> and <a href="../utilities/rm.html"><i>rm</i></a> utilities do not follow
symbolic links named as arguments, but respectively attempt to rename or delete them.</p>
</li>

<li>
<p>The <a href="../utilities/ls.html"><i>ls</i></a> utility is also an exception to this rule. For compatibility with historical
systems, when the <b>-R</b> option is not specified, the <a href="../utilities/ls.html"><i>ls</i></a> utility follows symbolic
links named as arguments if the <b>-L</b> option is specified or if the <b>-F</b>, <b>-d</b>, or <b>-l</b> options are not
specified. (If the <b>-L</b> option is specified, <a href="../utilities/ls.html"><i>ls</i></a> always follows symbolic links; it is
the only utility where the <b>-L</b> option affects its behavior even though a tree walk is not being performed.)</p>
</li>
</ul>

<p>All other standard utilities, when not traversing a file hierarchy, always follow symbolic links named as arguments.</p>

<p>Historical practice is that the <b>-h</b> option is specified if standard utilities are to act upon symbolic links instead of
upon their targets. Examples of commands that have historically had a <b>-h</b> option for this purpose are the <a href=
"../utilities/chgrp.html"><i>chgrp</i></a>, <a href="../utilities/chown.html"><i>chown</i></a>, <a href=
"../utilities/file.html"><i>file</i></a>, and <a href="../utilities/test.html"><i>test</i></a> utilities.<br>
</p>

<p><i>Third Domain</i></p>

<p>The third domain is symbolic links, referencing files not of type directory, specified to utilities that are performing a
traversal of a file hierarchy. (This includes symbolic links specified as command line filename arguments or encountered during the
traversal.)</p>

<p>The intention of the Shell and Utilities volume of IEEE&nbsp;Std&nbsp;1003.1-2001 is that the operation that the utility is
performing is applied to the symbolic link itself, if that operation is applicable to symbolic links. The reason that the operation
is not required is that symbolic links in some implementations do not have such attributes as a file owner, and therefore the <a
href="../utilities/chown.html"><i>chown</i></a> operation would be meaningless. If symbolic links on the system have an owner, it
is the intention that the utility <a href="../utilities/chown.html"><i>chown</i></a> cause the owner of the symbolic link to
change. If symbolic links do not have an owner, the symbolic link should be ignored. Specifically, by default, no change should be
made to the file referenced by the symbolic link.<br>
</p>

<p><i>Fourth Domain</i></p>

<p>The fourth domain is symbolic links referencing files of type directory, specified to utilities that are performing a traversal
of a file hierarchy. (This includes symbolic links specified as command line filename arguments or encountered during the
traversal.)</p>

<p>Most standard utilities do not, by default, indirect into the file hierarchy referenced by the symbolic link. (The Shell and
Utilities volume of IEEE&nbsp;Std&nbsp;1003.1-2001 uses the informal term &quot;physical walk&quot; to describe this case. The case where
the utility does indirect through the symbolic link is termed a &quot;logical walk&quot;.)</p>

<p>There are three reasons for the default to be a physical walk:</p>

<ol>
<li>
<p>With very few exceptions, a physical walk has been the historical default on UNIX systems supporting symbolic links. Because
some utilities (that is, <a href="../utilities/rm.html"><i>rm</i></a>) must default to a physical walk, regardless, changing
historical practice in this regard would be confusing to users and needlessly incompatible.</p>
</li>

<li>
<p>For systems where symbolic links have the historical file attributes (that is, <i>owner</i>, <i>group</i>, <i>mode</i>),
defaulting to a logical traversal would require the addition of a new option to the commands to modify the attributes of the link
itself. This is painful and more complex than the alternatives.</p>
</li>

<li>
<p>There is a security issue with defaulting to a logical walk. Historically, the command <a href=
"../utilities/chown.html"><i>chown</i></a> <b>-R</b> <i>user file</i> has been safe for the superuser because <i>setuid</i> and
<i>setgid</i> bits were lost when the ownership of the file was changed. If the walk were logical, changing ownership would no
longer be safe because a user might have inserted a symbolic link pointing to any file in the tree. Again, this would necessitate
the addition of an option to the commands doing hierarchy traversal to not indirect through the symbolic links, and historical
scripts doing recursive walks would instantly become security problems. While this is mostly an issue for system administrators, it
is preferable to not have different defaults for different classes of users.</p>
</li>
</ol>

<p>However, the standard developers agreed to leave it unspecified to achieve consensus.</p>

<p>As consistently as possible, users may cause standard utilities performing a file hierarchy traversal to follow any symbolic
links named on the command line, regardless of the type of file they reference, by specifying the <b>-H</b> (for half logical)
option. This option is intended to make the command line name space look like the logical name space.</p>

<p>As consistently as possible, users may cause standard utilities performing a file hierarchy traversal to 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 <b>-L</b> (for logical) option. This option is intended to make the entire name space look like the
logical name space.</p>

<p>For consistency, implementors are encouraged to use the <b>-P</b> (for &quot;physical&quot;) flag to specify the physical walk in
utilities that do logical walks by default for whatever reason. The only standard utilities that require the <b>-P</b> option are
<a href="../utilities/cd.html"><i>cd</i></a> and <a href="../utilities/pwd.html"><i>pwd</i></a>; see the note below.</p>

<p>When one or more of the <b>-H</b>, <b>-L</b>, and <b>-P</b> flags can be specified, the last one specified determines the
behavior of the utility. This permits users to alias commands so that the default behavior is a logical walk and then override that
behavior on the command line.</p>

<p><i>Exceptions in the Third and Fourth Domains</i></p>

<p>The <a href="../utilities/ls.html"><i>ls</i></a> and <a href="../utilities/rm.html"><i>rm</i></a> utilities are exceptions to
these rules. The <a href="../utilities/rm.html"><i>rm</i></a> utility never follows symbolic links and does not support the
<b>-H</b>, <b>-L</b>, or <b>-P</b> options. Some historical versions of <a href="../utilities/ls.html"><i>ls</i></a> always
followed symbolic links given on the command line whether the <b>-L</b> option was specified or not. Historical versions of <a
href="../utilities/ls.html"><i>ls</i></a> did not support the <b>-H</b> option. In IEEE&nbsp;Std&nbsp;1003.1-2001, unless one of
the <b>-H</b> or <b>-L</b> options is specified, the <a href="../utilities/ls.html"><i>ls</i></a> utility only follows symbolic
links to directories that are given as operands. The <a href="../utilities/ls.html"><i>ls</i></a> utility does not support the
<b>-P</b> option.</p>

<p>The Shell and Utilities volume of IEEE&nbsp;Std&nbsp;1003.1-2001 requires that the standard utilities <a href=
"../utilities/ls.html"><i>ls</i></a>, <a href="../utilities/find.html"><i>find</i></a>, and <a href=
"../utilities/pax.html"><i>pax</i></a> detect infinite loops when doing logical walks; that is, a directory, or more commonly a
symbolic link, that refers to an ancestor in the current file hierarchy