ls.html

IEEE 1003.1-2003, Single Unix Specification v3

<p>If more than one directory, or a combination of non-directory files and directories are written, either as a result of
specifying multiple operands, or the <b>-R</b> option, each list of files within a directory shall be preceded by:</p>

<pre>
<tt>"\n%s:\n", &lt;</tt><i>directory name</i><tt>&gt;
</tt>
</pre>

<p>If this string is the first thing to be written, the first &lt;newline&gt; shall not be written. This output shall precede the
number of units in the directory.</p>

<p><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
If the <b>-s</b> option is given, each file shall be written with the number of blocks used by the file. Along with <b>-C</b>,
<b>-1</b>, <b>-m</b>, or <b>-x</b>, the number and a &lt;space&gt; shall precede the filename; with <b>-g</b>, <b>-l</b>,
<b>-n</b>, or <b>-o</b>, they shall precede each line describing a file. <img src="../images/opt-end.gif" alt="[Option End]"
border="0"></p>
</blockquote>

<h4><a name="tag_04_81_11"></a>STDERR</h4>

<blockquote>
<p>The standard error shall be used only for diagnostic messages.</p>
</blockquote>

<h4><a name="tag_04_81_12"></a>OUTPUT FILES</h4>

<blockquote>
<p>None.</p>
</blockquote>

<h4><a name="tag_04_81_13"></a>EXTENDED DESCRIPTION</h4>

<blockquote>
<p>None.</p>
</blockquote>

<h4><a name="tag_04_81_14"></a>EXIT STATUS</h4>

<blockquote>
<p>The following exit values shall be returned:</p>

<dl compact>
<dt>&nbsp;0</dt>

<dd>Successful completion.</dd>

<dt>&gt;0</dt>

<dd>An error occurred.</dd>
</dl>
</blockquote>

<h4><a name="tag_04_81_15"></a>CONSEQUENCES OF ERRORS</h4>

<blockquote>
<p>Default.</p>
</blockquote>

<hr>
<div class="box"><em>The following sections are informative.</em></div>

<h4><a name="tag_04_81_16"></a>APPLICATION USAGE</h4>

<blockquote>
<p>Many implementations use the equal sign ( <tt>'='</tt> ) to denote sockets bound to the file system for the <b>-F</b> option.
Similarly, many historical implementations use the <tt>'s'</tt> character to denote sockets as the entry type characters for the
<b>-l</b> option.</p>

<p>It is difficult for an application to use every part of the file modes field of <i>ls</i> <b>-l</b> in a portable manner.
Certain file types and executable bits are not guaranteed to be exactly as shown, as implementations may have extensions.
Applications can use this field to pass directly to a user printout or prompt, but actions based on its contents should generally
be deferred, instead, to the <a href="../utilities/test.html"><i>test</i></a> utility.</p>

<p>The output of <i>ls</i> (with the <b>-l</b> and related options) contains information that logically could be used by utilities
such as <a href="../utilities/chmod.html"><i>chmod</i></a> and <a href="../utilities/touch.html"><i>touch</i></a> to restore files
to a known state. However, this information is presented in a format that cannot be used directly by those utilities or be easily
translated into a format that can be used. A character has been added to the end of the permissions string so that applications at
least have an indication that they may be working in an area they do not understand instead of assuming that they can translate the
permissions string into something that can be used. Future issues or related documents may define one or more specific characters
to be used based on different standard additional or alternative access control mechanisms.</p>

<p>As with many of the utilities that deal with filenames, the output of <i>ls</i> for multiple files or in one of the long listing
formats must be used carefully on systems where filenames can contain embedded white space. Systems and system administrators
should institute policies and user training to limit the use of such filenames.</p>

<p>The number of disk blocks occupied by the file that it reports varies depending on underlying file system type, block size units
reported, and the method of calculating the number of blocks. On some file system types, the number is the actual number of blocks
occupied by the file (counting indirect blocks and ignoring holes in the file); on others it is calculated based on the file size
(usually making an allowance for indirect blocks, but ignoring holes).</p>
</blockquote>

<h4><a name="tag_04_81_17"></a>EXAMPLES</h4>

<blockquote>
<p>An example of a small directory tree being fully listed with <i>ls</i> <b>-laRF&nbsp;a</b> in the POSIX locale:</p>

<pre>
<tt>total 11
drwxr-xr-x   3 hlj      prog          64 Jul  4 12:07 ./
drwxrwxrwx   4 hlj      prog        3264 Jul  4 12:09 ../
drwxr-xr-x   2 hlj      prog          48 Jul  4 12:07 b/
-rwxr--r--   1 hlj      prog         572 Jul  4 12:07 foo*
<br>
a/b:
total 4
drwxr-xr-x   2 hlj      prog          48 Jul  4 12:07 ./
drwxr-xr-x   3 hlj      prog          64 Jul  4 12:07 ../
-rw-r--r--   1 hlj      prog         700 Jul  4 12:07 bar
</tt>
</pre>
</blockquote>

<h4><a name="tag_04_81_18"></a>RATIONALE</h4>

<blockquote>
<p>Some historical implementations of the <i>ls</i> utility show all entries in a directory except dot and dot-dot when a superuser
invokes <i>ls</i> without specifying the <b>-a</b> option. When &quot;normal&quot; users invoke <i>ls</i> without specifying <b>-a</b>,
they should not see information about any files with names beginning with a period unless they were named as <i>file</i>
operands.</p>

<p>Implementations are expected to traverse arbitrary depths when processing the <b>-R</b> option. The only limitation on depth
should be based on running out of physical storage for keeping track of untraversed directories.</p>

<p>The <b>-1</b> (one) option was historically found in BSD and BSD-derived implementations only. It is required in this volume of
IEEE&nbsp;Std&nbsp;1003.1-2001 so that conforming applications might ensure that output is one entry per line, even if the output
is to a terminal.</p>

<p>Generally, this volume of IEEE&nbsp;Std&nbsp;1003.1-2001 is silent about what happens when options are given multiple times. In
the cases of <b>-C</b>, <b>-l</b>, and <b>-1</b>, however, it does specify the results of these overlapping options. Since
<i>ls</i> is one of the most aliased commands, it is important that the implementation perform intuitively. For example, if the
alias were:</p>

<pre>
<tt>alias ls="ls -C"
</tt>
</pre>

<p>and the user typed <i>ls</i> <b>-1</b>, single-text-column output should result, not an error.</p>

<p>The BSD <i>ls</i> provides a <b>-A</b> option (like <b>-a</b>, but dot and dot-dot are not written out). The small difference
from <b>-a</b> did not seem important enough to require both.</p>

<p>Implementations may make <b>-q</b> the default for terminals to prevent trojan horse attacks on terminals with special escape
sequences. This is not required because:</p>

<ul>
<li>
<p>Some control characters may be useful on some terminals; for example, a system might write them as <tt>"\001"</tt> or
<tt>"^A"</tt> .</p>
</li>

<li>
<p>Special behavior for terminals is not relevant to applications portability.</p>
</li>
</ul>

<p>An early proposal specified that the optional alternate access method flag had to be <tt>'+'</tt> if there was an alternate
access method used on the file or &lt;space&gt; if there was not. This was changed to be &lt;space&gt; if there is not and a single
printable character if there is. This was done for three reasons:</p>

<ol>
<li>
<p>There are historical implementations using characters other than <tt>'+'</tt> .</p>
</li>

<li>
<p>There are implementations that vary this character used in that position to distinguish between various alternate access methods
in use.</p>
</li>

<li>
<p>The standard developers did not want to preclude future specifications that might need a way to specify more than one alternate
access method.</p>
</li>
</ol>

<p>Nonetheless, implementations providing a single alternate access method are encouraged to use <tt>'+'</tt> .</p>

<p>In an early proposal, the units used to specify the number of blocks occupied by files in a directory in an <i>ls</i> <b>-l</b>
listing were implementation-defined. This was because BSD systems have historically used 1024-byte units and System V systems have
historically used 512-byte units. It was pointed out by BSD developers that their system has used 512-byte units in some places and
1024-byte units in other places. (System V has consistently used 512.) Therefore, this volume of IEEE&nbsp;Std&nbsp;1003.1-2001
usually specifies 512. Future releases of BSD are expected to consistently provide 512 bytes as a default with a way of specifying
1024-byte units where appropriate.</p>

<p>The &lt;<i>date&nbsp;and&nbsp;time</i>&gt; field in the <b>-l</b> format is specified only for the POSIX locale. As noted, the
format can be different in other locales. No mechanism for defining this is present in this volume of
IEEE&nbsp;Std&nbsp;1003.1-2001, as the appropriate vehicle is a messaging system; that is, the format should be specified as a
&quot;message&quot;.</p>
</blockquote>

<h4><a name="tag_04_81_19"></a>FUTURE DIRECTIONS</h4>

<blockquote>
<p>The <b>-s</b> uses implementation-defined units and cannot be used portably; it may be withdrawn in a future version.</p>
</blockquote>

<h4><a name="tag_04_81_20"></a>SEE ALSO</h4>

<blockquote>
<p><a href="chmod.html"><i>chmod</i>()</a> , <a href="find.html"><i>find</i></a> , the System Interfaces volume of
IEEE&nbsp;Std&nbsp;1003.1-2001, <a href="../functions/stat.html"><i>stat</i>()</a>, the Base Definitions volume of
IEEE&nbsp;Std&nbsp;1003.1-2001, <a href="../basedefs/sys/stat.h.html"><i>&lt;sys/stat.h&gt;</i></a></p>
</blockquote>

<h4><a name="tag_04_81_21"></a>CHANGE HISTORY</h4>

<blockquote>
<p>First released in Issue 2.</p>
</blockquote>

<h4><a name="tag_04_81_22"></a>Issue 5</h4>

<blockquote>
<p>A second FUTURE DIRECTION is added.</p>
</blockquote>

<h4><a name="tag_04_81_23"></a>Issue 6</h4>

<blockquote>
<p>The following new requirements on POSIX implementations derive from alignment with the Single UNIX Specification:</p>

<ul>
<li>
<p>In the <b>-F</b> option, other symbols are allowed for other file types.</p>
</li>
</ul>

<p>Treatment of symbolic links is added, as defined in the IEEE&nbsp;P1003.2b draft standard.</p>

<p>The Open Group Base Resolution bwg2001-010 is applied, adding the <tt>T</tt> and <tt>t</tt> fields as an XSI extension.</p>
</blockquote>

<div class="box"><em>End of informative text.</em></div>

<hr>
<hr size="2" noshade>
<center><font size="2"><!--footer start-->
UNIX &reg; is a registered Trademark of The Open Group.<br>
POSIX &reg; is a registered Trademark of The IEEE.<br>
[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href=
"../utilities/contents.html">XCU</a> | <a href="../functions/contents.html">XSH</a> | <a href="../xrat/contents.html">XRAT</a>
]</font></center>

<!--footer end-->
<hr size="2" noshade>
</body>
</html>