756 lines
33 KiB
HTML
756 lines
33 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<html>
|
|
<head>
|
|
<meta name="generator" content="HTML Tidy, see www.w3.org">
|
|
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
|
<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group's rhtm tool v1.2.1 -->
|
|
<!-- Copyright (c) 2001 The Open Group, All Rights Reserved -->
|
|
<title>ls</title>
|
|
</head>
|
|
<body bgcolor="white">
|
|
<script type="text/javascript" language="JavaScript" src="../jscript/codes.js">
|
|
</script>
|
|
|
|
<basefont size="3"> <a name="ls"></a> <a name="tag_04_81"></a><!-- ls -->
|
|
<!--header start-->
|
|
<center><font size="2">The Open Group Base Specifications Issue 6<br>
|
|
IEEE Std 1003.1-2001<br>
|
|
Copyright © 2001 The IEEE and The Open Group, All Rights reserved.</font></center>
|
|
|
|
<!--header end-->
|
|
<hr size="2" noshade>
|
|
<h4><a name="tag_04_81_01"></a>NAME</h4>
|
|
|
|
<blockquote>ls - list directory contents</blockquote>
|
|
|
|
<h4><a name="tag_04_81_02"></a>SYNOPSIS</h4>
|
|
|
|
<blockquote class="synopsis">
|
|
<p><code><tt><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> ls</tt> <b>[</b><tt>-CFRacdilqrtu1</tt><b>][</b><tt>-H | -L</tt>
|
|
<b>]<img src="../images/opt-start.gif" border="0">[</b><tt>-fgmnopsx</tt><b>]<img src="../images/opt-end.gif" border=
|
|
"0">[</b><i>file</i><tt>...</tt><b>]</b></code></p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_81_03"></a>DESCRIPTION</h4>
|
|
|
|
<blockquote>
|
|
<p>For each operand that names a file of a type other than directory or symbolic link to a directory, <i>ls</i> shall write the
|
|
name of the file as well as any requested, associated information. For each operand that names a file of type directory, <i>ls</i>
|
|
shall write the names of files contained within the directory as well as any requested, associated information. If one of the
|
|
<b>-d</b>, <b>-F</b>, or <b>-l</b> options are specified, and one of the <b>-H</b> or <b>-L</b> options are not specified, for each
|
|
operand that names a file of type symbolic link to a directory, <i>ls</i> shall write the name of the file as well as any
|
|
requested, associated information. If none of the <b>-d</b>, <b>-F</b>, or <b>-l</b> options are specified, or the <b>-H</b> or
|
|
<b>-L</b> options are specified, for each operand that names a file of type symbolic link to a directory, <i>ls</i> shall write the
|
|
names of files contained within the directory as well as any requested, associated information.</p>
|
|
|
|
<p>If no operands are specified, <i>ls</i> shall write the contents of the current directory. If more than one operand is
|
|
specified, <i>ls</i> shall write non-directory operands first; it shall sort directory and non-directory operands separately
|
|
according to the collating sequence in the current locale.</p>
|
|
|
|
<p>The <i>ls</i> utility shall detect infinite loops; that is, entering a previously visited directory that is an ancestor of the
|
|
last file encountered. When it detects an infinite loop, <i>ls</i> shall write a diagnostic message to standard error and shall
|
|
either recover its position in the hierarchy or terminate.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_81_04"></a>OPTIONS</h4>
|
|
|
|
<blockquote>
|
|
<p>The <i>ls</i> utility shall conform to the Base Definitions volume of IEEE Std 1003.1-2001, <a href=
|
|
"../basedefs/xbd_chap12.html#tag_12_02">Section 12.2, Utility Syntax Guidelines</a>.</p>
|
|
|
|
<p>The following options shall be supported:</p>
|
|
|
|
<dl compact>
|
|
<dt><b>-C</b></dt>
|
|
|
|
<dd>Write multi-text-column output with entries sorted down the columns, according to the collating sequence. The number of text
|
|
columns and the column separator characters are unspecified, but should be adapted to the nature of the output device.</dd>
|
|
|
|
<dt><b>-F</b></dt>
|
|
|
|
<dd>Do not follow symbolic links named as operands unless the <b>-H</b> or <b>-L</b> options are specified. Write a slash (
|
|
<tt>'/'</tt> ) immediately after each pathname that is a directory, an asterisk ( <tt>'*'</tt> ) after each that is executable, a
|
|
vertical bar ( <tt>'|'</tt> ) after each that is a FIFO, and an at sign ( <tt>'@'</tt> ) after each that is a symbolic link. For
|
|
other file types, other symbols may be written.</dd>
|
|
|
|
<dt><b>-H</b></dt>
|
|
|
|
<dd>If a symbolic link referencing a file of type directory is specified on the command line, <i>ls</i> shall evaluate the file
|
|
information and file type to be those of the file referenced by the link, and not the link itself; however, <i>ls</i> shall write
|
|
the name of the link itself and not the file referenced by the link.</dd>
|
|
|
|
<dt><b>-L</b></dt>
|
|
|
|
<dd>Evaluate the file information and file type for all symbolic links (whether named on the command line or encountered in a file
|
|
hierarchy) to be those of the file referenced by the link, and not the link itself; however, <i>ls</i> shall write the name of the
|
|
link itself and not the file referenced by the link. When <b>-L</b> is used with <b>-l</b>, write the contents of symbolic links in
|
|
the long format (see the STDOUT section).</dd>
|
|
|
|
<dt><b>-R</b></dt>
|
|
|
|
<dd>Recursively list subdirectories encountered.</dd>
|
|
|
|
<dt><b>-a</b></dt>
|
|
|
|
<dd>Write out all directory entries, including those whose names begin with a period ( <tt>'.'</tt> ). Entries beginning with a
|
|
period shall not be written out unless explicitly referenced, the <b>-a</b> option is supplied, or an implementation-defined
|
|
condition shall cause them to be written.</dd>
|
|
|
|
<dt><b>-c</b></dt>
|
|
|
|
<dd>Use time of last modification of the file status information (see <a href=
|
|
"../basedefs/sys/stat.h.html"><i><sys/stat.h></i></a> in the System Interfaces volume of IEEE Std 1003.1-2001)
|
|
instead of last modification of the file itself for sorting ( <b>-t</b>) or writing ( <b>-l</b>).</dd>
|
|
|
|
<dt><b>-d</b></dt>
|
|
|
|
<dd>Do not follow symbolic links named as operands unless the <b>-H</b> or <b>-L</b> options are specified. Do not treat
|
|
directories differently than other types of files. The use of <b>-d</b> with <b>-R</b> produces unspecified results.</dd>
|
|
|
|
<dt><b>-f</b></dt>
|
|
|
|
<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
|
|
Force each argument to be interpreted as a directory and list the name found in each slot. This option shall turn off <b>-l</b>,
|
|
<b>-t</b>, <b>-s</b>, and <b>-r</b>, and shall turn on <b>-a</b>; the order is the order in which entries appear in the directory.
|
|
<img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd>
|
|
|
|
<dt><b>-g</b></dt>
|
|
|
|
<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
|
|
The same as <b>-l</b>, except that the owner shall not be written. <img src="../images/opt-end.gif" alt="[Option End]" border=
|
|
"0"></dd>
|
|
|
|
<dt><b>-i</b></dt>
|
|
|
|
<dd>For each file, write the file's file serial number (see <a href="../functions/stat.html"><i>stat</i>()</a> in the System
|
|
Interfaces volume of IEEE Std 1003.1-2001).</dd>
|
|
|
|
<dt><b>-l</b></dt>
|
|
|
|
<dd>(The letter ell.) Do not follow symbolic links named as operands unless the <b>-H</b> or <b>-L</b> options are specified. Write
|
|
out in long format (see the STDOUT section). When <b>-l</b> (ell) is specified, -1 (one) shall be assumed.</dd>
|
|
|
|
<dt><b>-m</b></dt>
|
|
|
|
<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
|
|
Stream output format; list files across the page, separated by commas. <img src="../images/opt-end.gif" alt="[Option End]" border=
|
|
"0"></dd>
|
|
|
|
<dt><b>-n</b></dt>
|
|
|
|
<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
|
|
The same as <b>-l</b>, except that the owner's UID and GID numbers shall be written, rather than the associated character strings.
|
|
<img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd>
|
|
|
|
<dt><b>-o</b></dt>
|
|
|
|
<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
|
|
The same as <b>-l</b>, except that the group shall not be written. <img src="../images/opt-end.gif" alt="[Option End]" border=
|
|
"0"></dd>
|
|
|
|
<dt><b>-p</b></dt>
|
|
|
|
<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
|
|
Write a slash ( <tt>'/'</tt> ) after each filename if that file is a directory. <img src="../images/opt-end.gif" alt="[Option End]"
|
|
border="0"></dd>
|
|
|
|
<dt><b>-q</b></dt>
|
|
|
|
<dd>Force each instance of non-printable filename characters and <tab>s to be written as the question-mark ( <tt>'?'</tt> )
|
|
character. Implementations may provide this option by default if the output is to a terminal device.</dd>
|
|
|
|
<dt><b>-r</b></dt>
|
|
|
|
<dd>Reverse the order of the sort to get reverse collating sequence or oldest first.</dd>
|
|
|
|
<dt><b>-s</b></dt>
|
|
|
|
<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
|
|
Indicate the total number of file system blocks consumed by each file displayed. The block size is implementation-defined. <img
|
|
src="../images/opt-end.gif" alt="[Option End]" border="0"></dd>
|
|
|
|
<dt><b>-t</b></dt>
|
|
|
|
<dd>Sort with the primary key being time modified (most recently modified first) and the secondary key being filename in the
|
|
collating sequence.</dd>
|
|
|
|
<dt><b>-u</b></dt>
|
|
|
|
<dd>Use time of last access (see <a href="../basedefs/sys/stat.h.html"><i><sys/stat.h></i></a>) instead of last modification
|
|
of the file for sorting ( <b>-t</b>) or writing ( <b>-l</b>).</dd>
|
|
|
|
<dt><b>-x</b></dt>
|
|
|
|
<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
|
|
The same as <b>-C</b>, except that the multi-text-column output is produced with entries sorted across, rather than down, the
|
|
columns. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd>
|
|
|
|
<dt><b>-1</b></dt>
|
|
|
|
<dd>(The numeric digit one.) Force output to be one entry per line.</dd>
|
|
</dl>
|
|
|
|
<p>Specifying more than one of the options in the following mutually-exclusive pairs shall not be considered an error: <b>-C</b>
|
|
and <b>-l</b> (ell), <sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt=
|
|
"[Option Start]" border="0"> <b>-m</b> and <b>-l</b> (ell), <b>-x</b> and <b>-l</b> (ell), <img src="../images/opt-end.gif" alt=
|
|
"[Option End]" border="0"> <b>-C</b> and <b>-1</b> (one), <b>-H</b> and <b>-L</b>, <b>-c</b> and <b>-u</b>. The last option
|
|
specified in each pair shall determine the output format.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_81_05"></a>OPERANDS</h4>
|
|
|
|
<blockquote>
|
|
<p>The following operand shall be supported:</p>
|
|
|
|
<dl compact>
|
|
<dt><i>file</i></dt>
|
|
|
|
<dd>A pathname of a file to be written. If the file specified is not found, a diagnostic message shall be output on standard
|
|
error.</dd>
|
|
</dl>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_81_06"></a>STDIN</h4>
|
|
|
|
<blockquote>
|
|
<p>Not used.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_81_07"></a>INPUT FILES</h4>
|
|
|
|
<blockquote>
|
|
<p>None.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_81_08"></a>ENVIRONMENT VARIABLES</h4>
|
|
|
|
<blockquote>
|
|
<p>The following environment variables shall affect the execution of <i>ls</i>:</p>
|
|
|
|
<dl compact>
|
|
<dt><i>COLUMNS</i></dt>
|
|
|
|
<dd>Determine the user's preferred column position width for writing multiple text-column output. If this variable contains a
|
|
string representing a decimal integer, the <i>ls</i> utility shall calculate how many pathname text columns to write (see
|
|
<b>-C</b>) based on the width provided. If <i>COLUMNS</i> is not set or invalid, an implementation-defined number of column
|
|
positions shall be assumed, based on the implementation's knowledge of the output device. The column width chosen to write the
|
|
names of files in any given directory shall be constant. Filenames shall not be truncated to fit into the multiple text-column
|
|
output.</dd>
|
|
|
|
<dt><i>LANG</i></dt>
|
|
|
|
<dd>Provide a default value for the internationalization variables that are unset or null. (See the Base Definitions volume of
|
|
IEEE Std 1003.1-2001, <a href="../basedefs/xbd_chap08.html#tag_08_02">Section 8.2, Internationalization Variables</a> for
|
|
the precedence of internationalization variables used to determine the values of locale categories.)</dd>
|
|
|
|
<dt><i>LC_ALL</i></dt>
|
|
|
|
<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd>
|
|
|
|
<dt><i>LC_COLLATE</i></dt>
|
|
|
|
<dd><br>
|
|
Determine the locale for character collation information in determining the pathname collation sequence.</dd>
|
|
|
|
<dt><i>LC_CTYPE</i></dt>
|
|
|
|
<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as
|
|
opposed to multi-byte characters in arguments) and which characters are defined as printable (character class <b>print</b>).</dd>
|
|
|
|
<dt><i>LC_MESSAGES</i></dt>
|
|
|
|
<dd>Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard
|
|
error.</dd>
|
|
|
|
<dt><i>LC_TIME</i></dt>
|
|
|
|
<dd>Determine the format and contents for date and time strings written by <i>ls</i>.</dd>
|
|
|
|
<dt><i>NLSPATH</i></dt>
|
|
|
|
<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
|
|
Determine the location of message catalogs for the processing of <i>LC_MESSAGES .</i> <img src="../images/opt-end.gif" alt=
|
|
"[Option End]" border="0"></dd>
|
|
|
|
<dt><i>TZ</i></dt>
|
|
|
|
<dd>Determine the timezone for date and time strings written by <i>ls</i>. If <i>TZ</i> is unset or null, an unspecified default
|
|
timezone shall be used.</dd>
|
|
</dl>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_81_09"></a>ASYNCHRONOUS EVENTS</h4>
|
|
|
|
<blockquote>
|
|
<p>Default.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_81_10"></a>STDOUT</h4>
|
|
|
|
<blockquote>
|
|
<p>The default format shall be to list one entry per line to standard output; the exceptions are to terminals or when one of the
|
|
<b>-C</b>, <sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]"
|
|
border="0"> <b>-m</b>, or <b>-x</b> <img src="../images/opt-end.gif" alt="[Option End]" border="0"> options is specified. If the
|
|
output is to a terminal, the format is implementation-defined.</p>
|
|
|
|
<p><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
|
|
When <b>-m</b> is specified, the format used shall be:</p>
|
|
|
|
<pre>
|
|
<tt>"%s, %s, ...\n", <</tt><i>filename1</i><tt>>, <</tt><i>filename2</i><tt>>
|
|
</tt>
|
|
</pre>
|
|
|
|
<p>where the largest number of filenames shall be written without exceeding the length of the line. <img src=
|
|
"../images/opt-end.gif" alt="[Option End]" border="0"></p>
|
|
|
|
<p>If the <b>-i</b> option is specified, the file's file serial number (see <a href=
|
|
"../basedefs/sys/stat.h.html"><i><sys/stat.h></i></a>) shall be written in the following format before any other output for
|
|
the corresponding entry:</p>
|
|
|
|
<pre>
|
|
<tt>%u ", <</tt><i>file serial number</i><tt>>
|
|
</tt>
|
|
</pre>
|
|
|
|
<p>If the <b>-l</b> option is specified without <b>-L</b>, the following information shall be written:</p>
|
|
|
|
<pre>
|
|
<tt>"%s %u %s %s %u %s %s\n", <</tt><i>file mode</i><tt>>, <</tt><i>number of links</i><tt>>,
|
|
<</tt><i>owner name</i><tt>>, <</tt><i>group name</i><tt>>, <</tt><i>number of bytes in the file</i><tt>>,
|
|
<</tt><i>date and time</i><tt>>, <</tt><i>pathname</i><tt>>
|
|
</tt>
|
|
</pre>
|
|
|
|
<p>If the file is a symbolic link, this information shall be about the link itself and the <<i>pathname</i>> field shall be
|
|
of the form:</p>
|
|
|
|
<pre>
|
|
<tt>"%s -> %s", <</tt><i>pathname of link</i><tt>>, <</tt><i>contents of link</i><tt>>
|
|
</tt>
|
|
</pre>
|
|
|
|
<p>If both <b>-l</b> and <b>-L</b> are specified, the following information shall be written:</p>
|
|
|
|
<pre>
|
|
<tt>"%s %u %s %s %u %s %s\n", <</tt><i>file mode</i><tt>>, <</tt><i>number of links</i><tt>>,
|
|
<</tt><i>owner name</i><tt>>, <</tt><i>group name</i><tt>>, <</tt><i>number of bytes in the file</i><tt>>,
|
|
<</tt><i>date and time</i><tt>>, <</tt><i>pathname of link</i><tt>>
|
|
</tt>
|
|
</pre>
|
|
|
|
<p>where all fields except <<i>pathname of link</i>> shall be for the file resolved from the symbolic link.</p>
|
|
|
|
<p><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
|
|
The <b>-g</b>, <b>-n</b>, and <b>-o</b> options use the same format as <b>-l</b>, but with omitted items and their associated
|
|
<blank>s. See the OPTIONS section. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></p>
|
|
|
|
<p>In both the preceding <b>-l</b> forms, if <<i>owner name</i>> or <<i>group name</i>> cannot be determined, <sup>[<a
|
|
href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> or if
|
|
<b>-n</b> is given, <img src="../images/opt-end.gif" alt="[Option End]" border="0"> they shall be replaced with their associated
|
|
numeric values using the format <tt>%u</tt> .</p>
|
|
|
|
<p>The <<i>date and time</i>> field shall contain the appropriate date and timestamp of when the file was last
|
|
modified. In the POSIX locale, the field shall be the equivalent of the output of the following <a href=
|
|
"../utilities/date.html"><i>date</i></a> command:</p>
|
|
|
|
<pre>
|
|
<tt>date "+%b %e %H:%M"
|
|
</tt>
|
|
</pre>
|
|
|
|
<p>if the file has been modified in the last six months, or:</p>
|
|
|
|
<pre>
|
|
<tt>date "+%b %e %Y"
|
|
</tt>
|
|
</pre>
|
|
|
|
<p>(where two <space>s are used between <tt>%e</tt> and <tt>%Y</tt> ) if the file has not been modified in the last six
|
|
months or if the modification date is in the future, except that, in both cases, the final <newline> produced by <a href=
|
|
"../utilities/date.html"><i>date</i></a> shall not be included and the output shall be as if the <a href=
|
|
"../utilities/date.html"><i>date</i></a> command were executed at the time of the last modification date of the file rather than
|
|
the current time. When the <i>LC_TIME</i> locale category is not set to the POSIX locale, a different format and order of
|
|
presentation of this field may be used.</p>
|
|
|
|
<p>If the file is a character special or block special file, the size of the file may be replaced with implementation-defined
|
|
information associated with the device in question.</p>
|
|
|
|
<p>If the pathname was specified as a <i>file</i> operand, it shall be written as specified.</p>
|
|
|
|
<p>The file mode written under the <b>-l</b>, <sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src=
|
|
"../images/opt-start.gif" alt="[Option Start]" border="0"> <b>-g</b>, <b>-n</b>, and <b>-o</b> <img src="../images/opt-end.gif"
|
|
alt="[Option End]" border="0"> options shall consist of the following format:</p>
|
|
|
|
<pre>
|
|
<tt>"%c%s%s%s%c", <</tt><i>entry type</i><tt>>, <</tt><i>owner permissions</i><tt>>,
|
|
<</tt><i>group permissions</i><tt>>, <</tt><i>other permissions</i><tt>>,
|
|
<</tt><i>optional alternate access method flag</i><tt>>
|
|
</tt>
|
|
</pre>
|
|
|
|
<p>The <<i>optional alternate access method flag</i>> shall be a single <space> if there is no
|
|
alternate or additional access control method associated with the file; otherwise, a printable character shall be used.</p>
|
|
|
|
<p>The <<i>entry type</i>> character shall describe the type of file, as follows:</p>
|
|
|
|
<dl compact>
|
|
<dt><tt>d</tt></dt>
|
|
|
|
<dd>Directory.</dd>
|
|
|
|
<dt><tt>b</tt></dt>
|
|
|
|
<dd>Block special file.</dd>
|
|
|
|
<dt><tt>c</tt></dt>
|
|
|
|
<dd>Character special file.</dd>
|
|
|
|
<dt><tt>l</tt> (ell)</dt>
|
|
|
|
<dd>Symbolic link.</dd>
|
|
|
|
<dt><tt>p</tt></dt>
|
|
|
|
<dd>FIFO.</dd>
|
|
|
|
<dt><tt>-</tt></dt>
|
|
|
|
<dd>Regular file.</dd>
|
|
</dl>
|
|
|
|
<p>Implementations may add other characters to this list to represent other implementation-defined file types.</p>
|
|
|
|
<p>The next three fields shall be three characters each:</p>
|
|
|
|
<dl compact>
|
|
<dt><<i>owner permissions</i>></dt>
|
|
|
|
<dd><br>
|
|
Permissions for the file owner class (see the Base Definitions volume of IEEE Std 1003.1-2001, <a href=
|
|
"../basedefs/xbd_chap04.html#tag_04_04">Section 4.4, File Access Permissions</a>).</dd>
|
|
|
|
<dt><<i>group permissions</i>></dt>
|
|
|
|
<dd><br>
|
|
Permissions for the file group class.</dd>
|
|
|
|
<dt><<i>other permissions</i>></dt>
|
|
|
|
<dd><br>
|
|
Permissions for the file other class.</dd>
|
|
</dl>
|
|
|
|
<p>Each field shall have three character positions:</p>
|
|
|
|
<ol>
|
|
<li>
|
|
<p>If <tt>'r'</tt> , the file is readable; if <tt>'-'</tt> , the file is not readable.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>If <tt>'w'</tt> , the file is writable; if <tt>'-'</tt> , the file is not writable.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>The first of the following that applies:</p>
|
|
|
|
<dl compact>
|
|
<dt><tt>S</tt></dt>
|
|
|
|
<dd>If in <<i>owner permissions</i>>, the file is not executable and set-user-ID mode is set. If in
|
|
<<i>group permissions</i>>, the file is not executable and set-group-ID mode is set.</dd>
|
|
|
|
<dt><tt>s</tt></dt>
|
|
|
|
<dd>If in <<i>owner permissions</i>>, the file is executable and set-user-ID mode is set. If in
|
|
<<i>group permissions</i>>, the file is executable and set-group-ID mode is set.</dd>
|
|
|
|
<dt><tt>T</tt></dt>
|
|
|
|
<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
|
|
If in <<i>other permissions</i>> and the file is a directory, search permission is not granted to others, and the
|
|
restricted deletion flag is set. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd>
|
|
|
|
<dt><tt>t</tt></dt>
|
|
|
|
<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
|
|
If in <<i>other permissions</i>> and the file is a directory, search permission is granted to others, and the restricted
|
|
deletion flag is set. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd>
|
|
|
|
<dt><tt>x</tt></dt>
|
|
|
|
<dd>The file is executable or the directory is searchable.</dd>
|
|
|
|
<dt><tt>-</tt></dt>
|
|
|
|
<dd>None of the attributes of <tt>'S'</tt> , <tt>'s'</tt> , <tt>'T'</tt> , <tt>'t'</tt> , or <tt>'x'</tt> applies.</dd>
|
|
</dl>
|
|
|
|
<p>Implementations may add other characters to this list for the third character position. Such additions shall, however, be
|
|
written in lowercase if the file is executable or searchable, and in uppercase if it is not.</p>
|
|
</li>
|
|
</ol>
|
|
|
|
<p>If any of the <b>-l</b>, <sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt=
|
|
"[Option Start]" border="0"> <b>-g</b>, <b>-n</b>, <b>-o</b>, or <b>-s</b> <img src="../images/opt-end.gif" alt="[Option End]"
|
|
border="0"> options is specified, each list of files within the directory shall be preceded by a status line indicating the number
|
|
of file system blocks occupied by files in the directory in 512-byte units, rounded up to the next integral number of units, if
|
|
necessary. In the POSIX locale, the format shall be:</p>
|
|
|
|
<pre>
|
|
<tt>"total %u\n", <</tt><i>number of units in the directory</i><tt>>
|
|
</tt>
|
|
</pre>
|
|
|
|
<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", <</tt><i>directory name</i><tt>>
|
|
</tt>
|
|
</pre>
|
|
|
|
<p>If this string is the first thing to be written, the first <newline> 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 <space> 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> 0</dt>
|
|
|
|
<dd>Successful completion.</dd>
|
|
|
|
<dt>>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 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 "normal" 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 Std 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 Std 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 <space> if there was not. This was changed to be <space> 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 Std 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 <<i>date and time</i>> 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 Std 1003.1-2001, as the appropriate vehicle is a messaging system; that is, the format should be specified as a
|
|
"message".</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 Std 1003.1-2001, <a href="../functions/stat.html"><i>stat</i>()</a>, the Base Definitions volume of
|
|
IEEE Std 1003.1-2001, <a href="../basedefs/sys/stat.h.html"><i><sys/stat.h></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 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 ® is a registered Trademark of The Open Group.<br>
|
|
POSIX ® 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>
|
|
|