mirror of https://github.com/mkerrisk/man-pages
738 lines
24 KiB
Groff
738 lines
24 KiB
Groff
|
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
|
||
|
.TH "LS" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
||
|
.\" ls
|
||
|
.SH NAME
|
||
|
ls \- list directory contents
|
||
|
.SH SYNOPSIS
|
||
|
.LP
|
||
|
\fBls\fP \fB[\fP\fB-CFRacdilqrtu1\fP\fB][\fP\fB-H | -L\fP
|
||
|
\fB][\fP\fB-fgmnopsx\fP\fB][\fP\fIfile\fP\fB...\fP\fB]\fP
|
||
|
.SH DESCRIPTION
|
||
|
.LP
|
||
|
For each operand that names a file of a type other than directory
|
||
|
or symbolic link to a directory, \fIls\fP shall write the
|
||
|
name of the file as well as any requested, associated information.
|
||
|
For each operand that names a file of type directory, \fIls\fP
|
||
|
shall write the names of files contained within the directory as well
|
||
|
as any requested, associated information. If one of the
|
||
|
\fB-d\fP, \fB-F\fP, or \fB-l\fP options are specified, and one of
|
||
|
the \fB-H\fP or \fB-L\fP options are not specified, for each
|
||
|
operand that names a file of type symbolic link to a directory, \fIls\fP
|
||
|
shall write the name of the file as well as any
|
||
|
requested, associated information. If none of the \fB-d\fP, \fB-F\fP,
|
||
|
or \fB-l\fP options are specified, or the \fB-H\fP or
|
||
|
\fB-L\fP options are specified, for each operand that names a file
|
||
|
of type symbolic link to a directory, \fIls\fP shall write the
|
||
|
names of files contained within the directory as well as any requested,
|
||
|
associated information.
|
||
|
.LP
|
||
|
If no operands are specified, \fIls\fP shall write the contents of
|
||
|
the current directory. If more than one operand is
|
||
|
specified, \fIls\fP shall write non-directory operands first; it shall
|
||
|
sort directory and non-directory operands separately
|
||
|
according to the collating sequence in the current locale.
|
||
|
.LP
|
||
|
The \fIls\fP 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, \fIls\fP
|
||
|
shall write a diagnostic message to standard error and shall
|
||
|
either recover its position in the hierarchy or terminate.
|
||
|
.SH OPTIONS
|
||
|
.LP
|
||
|
The \fIls\fP utility shall conform to the Base Definitions volume
|
||
|
of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines.
|
||
|
.LP
|
||
|
The following options shall be supported:
|
||
|
.TP 7
|
||
|
\fB-C\fP
|
||
|
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.
|
||
|
.TP 7
|
||
|
\fB-F\fP
|
||
|
Do not follow symbolic links named as operands unless the \fB-H\fP
|
||
|
or \fB-L\fP options are specified. Write a slash (
|
||
|
\fB'/'\fP ) immediately after each pathname that is a directory, an
|
||
|
asterisk ( \fB'*'\fP ) after each that is executable, a
|
||
|
vertical bar ( \fB'|'\fP ) after each that is a FIFO, and an at sign
|
||
|
( \fB'@'\fP ) after each that is a symbolic link. For
|
||
|
other file types, other symbols may be written.
|
||
|
.TP 7
|
||
|
\fB-H\fP
|
||
|
If a symbolic link referencing a file of type directory is specified
|
||
|
on the command line, \fIls\fP shall evaluate the file
|
||
|
information and file type to be those of the file referenced by the
|
||
|
link, and not the link itself; however, \fIls\fP shall write
|
||
|
the name of the link itself and not the file referenced by the link.
|
||
|
.TP 7
|
||
|
\fB-L\fP
|
||
|
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, \fIls\fP shall write the name of the
|
||
|
link itself and not the file referenced by the link. When \fB-L\fP
|
||
|
is used with \fB-l\fP, write the contents of symbolic links in
|
||
|
the long format (see the STDOUT section).
|
||
|
.TP 7
|
||
|
\fB-R\fP
|
||
|
Recursively list subdirectories encountered.
|
||
|
.TP 7
|
||
|
\fB-a\fP
|
||
|
Write out all directory entries, including those whose names begin
|
||
|
with a period ( \fB'.'\fP ). Entries beginning with a
|
||
|
period shall not be written out unless explicitly referenced, the
|
||
|
\fB-a\fP option is supplied, or an implementation-defined
|
||
|
condition shall cause them to be written.
|
||
|
.TP 7
|
||
|
\fB-c\fP
|
||
|
Use time of last modification of the file status information (see
|
||
|
\fI<sys/stat.h>\fP in the System Interfaces volume of IEEE\ Std\ 1003.1-2001)
|
||
|
instead of last modification of the file itself for sorting ( \fB-t\fP)
|
||
|
or writing ( \fB-l\fP).
|
||
|
.TP 7
|
||
|
\fB-d\fP
|
||
|
Do not follow symbolic links named as operands unless the \fB-H\fP
|
||
|
or \fB-L\fP options are specified. Do not treat
|
||
|
directories differently than other types of files. The use of \fB-d\fP
|
||
|
with \fB-R\fP produces unspecified results.
|
||
|
.TP 7
|
||
|
\fB-f\fP
|
||
|
Force each argument to be interpreted as a directory and list the
|
||
|
name found in each slot. This option shall turn off \fB-l\fP,
|
||
|
\fB-t\fP, \fB-s\fP, and \fB-r\fP, and shall turn on \fB-a\fP; the
|
||
|
order is the order in which entries appear in the directory.
|
||
|
.TP 7
|
||
|
\fB-g\fP
|
||
|
The same as \fB-l\fP, except that the owner shall not be written.
|
||
|
.TP 7
|
||
|
\fB-i\fP
|
||
|
For each file, write the file's file serial number (see \fIstat\fP()
|
||
|
in the System
|
||
|
Interfaces volume of IEEE\ Std\ 1003.1-2001).
|
||
|
.TP 7
|
||
|
\fB-l\fP
|
||
|
(The letter ell.) Do not follow symbolic links named as operands unless
|
||
|
the \fB-H\fP or \fB-L\fP options are specified. Write
|
||
|
out in long format (see the STDOUT section). When \fB-l\fP (ell) is
|
||
|
specified, -1 (one) shall be assumed.
|
||
|
.TP 7
|
||
|
\fB-m\fP
|
||
|
Stream output format; list files across the page, separated by commas.
|
||
|
.TP 7
|
||
|
\fB-n\fP
|
||
|
The same as \fB-l\fP, except that the owner's UID and GID numbers
|
||
|
shall be written, rather than the associated character strings.
|
||
|
.TP 7
|
||
|
\fB-o\fP
|
||
|
The same as \fB-l\fP, except that the group shall not be written.
|
||
|
.TP 7
|
||
|
\fB-p\fP
|
||
|
Write a slash ( \fB'/'\fP ) after each filename if that file is a
|
||
|
directory.
|
||
|
.TP 7
|
||
|
\fB-q\fP
|
||
|
Force each instance of non-printable filename characters and <tab>s
|
||
|
to be written as the question-mark ( \fB'?'\fP )
|
||
|
character. Implementations may provide this option by default if the
|
||
|
output is to a terminal device.
|
||
|
.TP 7
|
||
|
\fB-r\fP
|
||
|
Reverse the order of the sort to get reverse collating sequence or
|
||
|
oldest first.
|
||
|
.TP 7
|
||
|
\fB-s\fP
|
||
|
Indicate the total number of file system blocks consumed by each file
|
||
|
displayed. The block size is implementation-defined.
|
||
|
.TP 7
|
||
|
\fB-t\fP
|
||
|
Sort with the primary key being time modified (most recently modified
|
||
|
first) and the secondary key being filename in the
|
||
|
collating sequence.
|
||
|
.TP 7
|
||
|
\fB-u\fP
|
||
|
Use time of last access (see \fI<sys/stat.h>\fP) instead of last modification
|
||
|
of the file for sorting ( \fB-t\fP) or writing ( \fB-l\fP).
|
||
|
.TP 7
|
||
|
\fB-x\fP
|
||
|
The same as \fB-C\fP, except that the multi-text-column output is
|
||
|
produced with entries sorted across, rather than down, the
|
||
|
columns.
|
||
|
.TP 7
|
||
|
\fB-1\fP
|
||
|
(The numeric digit one.) Force output to be one entry per line.
|
||
|
.sp
|
||
|
.LP
|
||
|
Specifying more than one of the options in the following mutually-exclusive
|
||
|
pairs shall not be considered an error: \fB-C\fP
|
||
|
and \fB-l\fP (ell), \fB-m\fP and \fB-l\fP (ell), \fB-x\fP and \fB-l\fP
|
||
|
(ell), \fB-C\fP and \fB-1\fP (one), \fB-H\fP and \fB-L\fP, \fB-c\fP
|
||
|
and \fB-u\fP. The last option
|
||
|
specified in each pair shall determine the output format.
|
||
|
.SH OPERANDS
|
||
|
.LP
|
||
|
The following operand shall be supported:
|
||
|
.TP 7
|
||
|
\fIfile\fP
|
||
|
A pathname of a file to be written. If the file specified is not found,
|
||
|
a diagnostic message shall be output on standard
|
||
|
error.
|
||
|
.sp
|
||
|
.SH STDIN
|
||
|
.LP
|
||
|
Not used.
|
||
|
.SH INPUT FILES
|
||
|
.LP
|
||
|
None.
|
||
|
.SH ENVIRONMENT VARIABLES
|
||
|
.LP
|
||
|
The following environment variables shall affect the execution of
|
||
|
\fIls\fP:
|
||
|
.TP 7
|
||
|
\fICOLUMNS\fP
|
||
|
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 \fIls\fP utility shall
|
||
|
calculate how many pathname text columns to write (see
|
||
|
\fB-C\fP) based on the width provided. If \fICOLUMNS\fP 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.
|
||
|
.TP 7
|
||
|
\fILANG\fP
|
||
|
Provide a default value for the internationalization variables that
|
||
|
are unset or null. (See the Base Definitions volume of
|
||
|
IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables
|
||
|
for
|
||
|
the precedence of internationalization variables used to determine
|
||
|
the values of locale categories.)
|
||
|
.TP 7
|
||
|
\fILC_ALL\fP
|
||
|
If set to a non-empty string value, override the values of all the
|
||
|
other internationalization variables.
|
||
|
.TP 7
|
||
|
\fILC_COLLATE\fP
|
||
|
.sp
|
||
|
Determine the locale for character collation information in determining
|
||
|
the pathname collation sequence.
|
||
|
.TP 7
|
||
|
\fILC_CTYPE\fP
|
||
|
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 \fBprint\fP).
|
||
|
.TP 7
|
||
|
\fILC_MESSAGES\fP
|
||
|
Determine the locale that should be used to affect the format and
|
||
|
contents of diagnostic messages written to standard
|
||
|
error.
|
||
|
.TP 7
|
||
|
\fILC_TIME\fP
|
||
|
Determine the format and contents for date and time strings written
|
||
|
by \fIls\fP.
|
||
|
.TP 7
|
||
|
\fINLSPATH\fP
|
||
|
Determine the location of message catalogs for the processing of \fILC_MESSAGES
|
||
|
\&.\fP
|
||
|
.TP 7
|
||
|
\fITZ\fP
|
||
|
Determine the timezone for date and time strings written by \fIls\fP.
|
||
|
If \fITZ\fP is unset or null, an unspecified default
|
||
|
timezone shall be used.
|
||
|
.sp
|
||
|
.SH ASYNCHRONOUS EVENTS
|
||
|
.LP
|
||
|
Default.
|
||
|
.SH STDOUT
|
||
|
.LP
|
||
|
The default format shall be to list one entry per line to standard
|
||
|
output; the exceptions are to terminals or when one of the
|
||
|
\fB-C\fP, \fB-m\fP, or \fB-x\fP options is specified. If the
|
||
|
output is to a terminal, the format is implementation-defined.
|
||
|
.LP
|
||
|
When \fB-m\fP is specified, the format used shall be:
|
||
|
.sp
|
||
|
.RS
|
||
|
.nf
|
||
|
|
||
|
\fB"%s, %s, ...\\n", <\fP\fIfilename1\fP\fB>, <\fP\fIfilename2\fP\fB>
|
||
|
\fP
|
||
|
.fi
|
||
|
.RE
|
||
|
.LP
|
||
|
where the largest number of filenames shall be written without exceeding
|
||
|
the length of the line.
|
||
|
.LP
|
||
|
If the \fB-i\fP option is specified, the file's file serial number
|
||
|
(see \fI<sys/stat.h>\fP) shall be written in the following format
|
||
|
before any other output for
|
||
|
the corresponding entry:
|
||
|
.sp
|
||
|
.RS
|
||
|
.nf
|
||
|
|
||
|
\fB%u ", <\fP\fIfile serial number\fP\fB>
|
||
|
\fP
|
||
|
.fi
|
||
|
.RE
|
||
|
.LP
|
||
|
If the \fB-l\fP option is specified without \fB-L\fP, the following
|
||
|
information shall be written:
|
||
|
.sp
|
||
|
.RS
|
||
|
.nf
|
||
|
|
||
|
\fB"%s %u %s %s %u %s %s\\n", <\fP\fIfile mode\fP\fB>, <\fP\fInumber of links\fP\fB>,
|
||
|
<\fP\fIowner name\fP\fB>, <\fP\fIgroup name\fP\fB>, <\fP\fInumber of bytes in the file\fP\fB>,
|
||
|
<\fP\fIdate and time\fP\fB>, <\fP\fIpathname\fP\fB>
|
||
|
\fP
|
||
|
.fi
|
||
|
.RE
|
||
|
.LP
|
||
|
If the file is a symbolic link, this information shall be about the
|
||
|
link itself and the <\fIpathname\fP> field shall be
|
||
|
of the form:
|
||
|
.sp
|
||
|
.RS
|
||
|
.nf
|
||
|
|
||
|
\fB"%s -> %s", <\fP\fIpathname of link\fP\fB>, <\fP\fIcontents of link\fP\fB>
|
||
|
\fP
|
||
|
.fi
|
||
|
.RE
|
||
|
.LP
|
||
|
If both \fB-l\fP and \fB-L\fP are specified, the following information
|
||
|
shall be written:
|
||
|
.sp
|
||
|
.RS
|
||
|
.nf
|
||
|
|
||
|
\fB"%s %u %s %s %u %s %s\\n", <\fP\fIfile mode\fP\fB>, <\fP\fInumber of links\fP\fB>,
|
||
|
<\fP\fIowner name\fP\fB>, <\fP\fIgroup name\fP\fB>, <\fP\fInumber of bytes in the file\fP\fB>,
|
||
|
<\fP\fIdate and time\fP\fB>, <\fP\fIpathname of link\fP\fB>
|
||
|
\fP
|
||
|
.fi
|
||
|
.RE
|
||
|
.LP
|
||
|
where all fields except <\fIpathname of link\fP> shall be for the
|
||
|
file resolved from the symbolic link.
|
||
|
.LP
|
||
|
The \fB-g\fP, \fB-n\fP, and \fB-o\fP options use the same format as
|
||
|
\fB-l\fP, but with omitted items and their associated
|
||
|
<blank>s. See the OPTIONS section.
|
||
|
.LP
|
||
|
In both the preceding \fB-l\fP forms, if <\fIowner name\fP> or <\fIgroup
|
||
|
name\fP> cannot be determined, \ or if
|
||
|
\fB-n\fP is given, they shall be replaced with their associated
|
||
|
numeric values using the format \fB%u\fP .
|
||
|
.LP
|
||
|
The <\fIdate\ and\ time\fP> 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 \fIdate\fP command:
|
||
|
.sp
|
||
|
.RS
|
||
|
.nf
|
||
|
|
||
|
\fBdate "+%b %e %H:%M"
|
||
|
\fP
|
||
|
.fi
|
||
|
.RE
|
||
|
.LP
|
||
|
if the file has been modified in the last six months, or:
|
||
|
.sp
|
||
|
.RS
|
||
|
.nf
|
||
|
|
||
|
\fBdate "+%b %e %Y"
|
||
|
\fP
|
||
|
.fi
|
||
|
.RE
|
||
|
.LP
|
||
|
(where two <space>s are used between \fB%e\fP and \fB%Y\fP ) 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 \fIdate\fP shall not
|
||
|
be included and the output shall be as if the \fIdate\fP command were
|
||
|
executed at the time of the last modification date of the file rather
|
||
|
than
|
||
|
the current time. When the \fILC_TIME\fP locale category is not set
|
||
|
to the POSIX locale, a different format and order of
|
||
|
presentation of this field may be used.
|
||
|
.LP
|
||
|
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.
|
||
|
.LP
|
||
|
If the pathname was specified as a \fIfile\fP operand, it shall be
|
||
|
written as specified.
|
||
|
.LP
|
||
|
The file mode written under the \fB-l\fP, \fB-g\fP, \fB-n\fP, and
|
||
|
\fB-o\fP options shall consist of the following format:
|
||
|
.sp
|
||
|
.RS
|
||
|
.nf
|
||
|
|
||
|
\fB"%c%s%s%s%c", <\fP\fIentry type\fP\fB>, <\fP\fIowner permissions\fP\fB>,
|
||
|
<\fP\fIgroup permissions\fP\fB>, <\fP\fIother permissions\fP\fB>,
|
||
|
<\fP\fIoptional alternate access method flag\fP\fB>
|
||
|
\fP
|
||
|
.fi
|
||
|
.RE
|
||
|
.LP
|
||
|
The <\fIoptional\ alternate\ access\ method\ flag\fP> 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.
|
||
|
.LP
|
||
|
The <\fIentry\ type\fP> character shall describe the type of file,
|
||
|
as follows:
|
||
|
.TP 7
|
||
|
\fBd\fP
|
||
|
Directory.
|
||
|
.TP 7
|
||
|
\fBb\fP
|
||
|
Block special file.
|
||
|
.TP 7
|
||
|
\fBc\fP
|
||
|
Character special file.
|
||
|
.TP 7
|
||
|
\fBl\fP\ (ell)
|
||
|
Symbolic link.
|
||
|
.TP 7
|
||
|
\fBp\fP
|
||
|
FIFO.
|
||
|
.TP 7
|
||
|
\fB-\fP
|
||
|
Regular file.
|
||
|
.sp
|
||
|
.LP
|
||
|
Implementations may add other characters to this list to represent
|
||
|
other implementation-defined file types.
|
||
|
.LP
|
||
|
The next three fields shall be three characters each:
|
||
|
.TP 7
|
||
|
<\fIowner permissions\fP>
|
||
|
.sp
|
||
|
Permissions for the file owner class (see the Base Definitions volume
|
||
|
of IEEE\ Std\ 1003.1-2001, Section 4.4, File Access Permissions).
|
||
|
.TP 7
|
||
|
<\fIgroup permissions\fP>
|
||
|
.sp
|
||
|
Permissions for the file group class.
|
||
|
.TP 7
|
||
|
<\fIother permissions\fP>
|
||
|
.sp
|
||
|
Permissions for the file other class.
|
||
|
.sp
|
||
|
.LP
|
||
|
Each field shall have three character positions:
|
||
|
.IP " 1." 4
|
||
|
If \fB'r'\fP , the file is readable; if \fB'-'\fP , the file is not
|
||
|
readable.
|
||
|
.LP
|
||
|
.IP " 2." 4
|
||
|
If \fB'w'\fP , the file is writable; if \fB'-'\fP , the file is not
|
||
|
writable.
|
||
|
.LP
|
||
|
.IP " 3." 4
|
||
|
The first of the following that applies:
|
||
|
.TP 7
|
||
|
\fBS\fP
|
||
|
.RS
|
||
|
If in <\fIowner\ permissions\fP>, the file is not executable and set-user-ID
|
||
|
mode is set. If in
|
||
|
<\fIgroup\ permissions\fP>, the file is not executable and set-group-ID
|
||
|
mode is set.
|
||
|
.RE
|
||
|
.TP 7
|
||
|
\fBs\fP
|
||
|
.RS
|
||
|
If in <\fIowner\ permissions\fP>, the file is executable and set-user-ID
|
||
|
mode is set. If in
|
||
|
<\fIgroup\ permissions\fP>, the file is executable and set-group-ID
|
||
|
mode is set.
|
||
|
.RE
|
||
|
.TP 7
|
||
|
\fBT\fP
|
||
|
.RS
|
||
|
If in <\fIother\ permissions\fP> and the file is a directory, search
|
||
|
permission is not granted to others, and the
|
||
|
restricted deletion flag is set.
|
||
|
.RE
|
||
|
.TP 7
|
||
|
\fBt\fP
|
||
|
.RS
|
||
|
If in <\fIother\ permissions\fP> and the file is a directory, search
|
||
|
permission is granted to others, and the restricted
|
||
|
deletion flag is set.
|
||
|
.RE
|
||
|
.TP 7
|
||
|
\fBx\fP
|
||
|
.RS
|
||
|
The file is executable or the directory is searchable.
|
||
|
.RE
|
||
|
.TP 7
|
||
|
\fB-\fP
|
||
|
.RS
|
||
|
None of the attributes of \fB'S'\fP , \fB's'\fP , \fB'T'\fP , \fB't'\fP
|
||
|
, or \fB'x'\fP applies.
|
||
|
.RE
|
||
|
.sp
|
||
|
.LP
|
||
|
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.
|
||
|
.LP
|
||
|
.LP
|
||
|
If any of the \fB-l\fP, \fB-g\fP, \fB-n\fP, \fB-o\fP, or \fB-s\fP
|
||
|
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:
|
||
|
.sp
|
||
|
.RS
|
||
|
.nf
|
||
|
|
||
|
\fB"total %u\\n", <\fP\fInumber of units in the directory\fP\fB>
|
||
|
\fP
|
||
|
.fi
|
||
|
.RE
|
||
|
.LP
|
||
|
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 \fB-R\fP option, each list of
|
||
|
files within a directory shall be preceded by:
|
||
|
.sp
|
||
|
.RS
|
||
|
.nf
|
||
|
|
||
|
\fB"\\n%s:\\n", <\fP\fIdirectory name\fP\fB>
|
||
|
\fP
|
||
|
.fi
|
||
|
.RE
|
||
|
.LP
|
||
|
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.
|
||
|
.LP
|
||
|
If the \fB-s\fP option is given, each file shall be written with the
|
||
|
number of blocks used by the file. Along with \fB-C\fP,
|
||
|
\fB-1\fP, \fB-m\fP, or \fB-x\fP, the number and a <space> shall precede
|
||
|
the filename; with \fB-g\fP, \fB-l\fP,
|
||
|
\fB-n\fP, or \fB-o\fP, they shall precede each line describing a file.
|
||
|
.SH STDERR
|
||
|
.LP
|
||
|
The standard error shall be used only for diagnostic messages.
|
||
|
.SH OUTPUT FILES
|
||
|
.LP
|
||
|
None.
|
||
|
.SH EXTENDED DESCRIPTION
|
||
|
.LP
|
||
|
None.
|
||
|
.SH EXIT STATUS
|
||
|
.LP
|
||
|
The following exit values shall be returned:
|
||
|
.TP 7
|
||
|
\ 0
|
||
|
Successful completion.
|
||
|
.TP 7
|
||
|
>0
|
||
|
An error occurred.
|
||
|
.sp
|
||
|
.SH CONSEQUENCES OF ERRORS
|
||
|
.LP
|
||
|
Default.
|
||
|
.LP
|
||
|
\fIThe following sections are informative.\fP
|
||
|
.SH APPLICATION USAGE
|
||
|
.LP
|
||
|
Many implementations use the equal sign ( \fB'='\fP ) to denote sockets
|
||
|
bound to the file system for the \fB-F\fP option.
|
||
|
Similarly, many historical implementations use the \fB's'\fP character
|
||
|
to denote sockets as the entry type characters for the
|
||
|
\fB-l\fP option.
|
||
|
.LP
|
||
|
It is difficult for an application to use every part of the file modes
|
||
|
field of \fIls\fP \fB-l\fP 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 \fItest\fP utility.
|
||
|
.LP
|
||
|
The output of \fIls\fP (with the \fB-l\fP and related options) contains
|
||
|
information that logically could be used by utilities
|
||
|
such as \fIchmod\fP and \fItouch\fP 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.
|
||
|
.LP
|
||
|
As with many of the utilities that deal with filenames, the output
|
||
|
of \fIls\fP 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.
|
||
|
.LP
|
||
|
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).
|
||
|
.SH EXAMPLES
|
||
|
.LP
|
||
|
An example of a small directory tree being fully listed with \fIls\fP
|
||
|
\fB-laRF\ a\fP in the POSIX locale:
|
||
|
.sp
|
||
|
.RS
|
||
|
.nf
|
||
|
|
||
|
\fBtotal 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*
|
||
|
.sp
|
||
|
|
||
|
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
|
||
|
\fP
|
||
|
.fi
|
||
|
.RE
|
||
|
.SH RATIONALE
|
||
|
.LP
|
||
|
Some historical implementations of the \fIls\fP utility show all entries
|
||
|
in a directory except dot and dot-dot when a superuser
|
||
|
invokes \fIls\fP without specifying the \fB-a\fP option. When "normal"
|
||
|
users invoke \fIls\fP without specifying \fB-a\fP,
|
||
|
they should not see information about any files with names beginning
|
||
|
with a period unless they were named as \fIfile\fP
|
||
|
operands.
|
||
|
.LP
|
||
|
Implementations are expected to traverse arbitrary depths when processing
|
||
|
the \fB-R\fP option. The only limitation on depth
|
||
|
should be based on running out of physical storage for keeping track
|
||
|
of untraversed directories.
|
||
|
.LP
|
||
|
The \fB-1\fP (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.
|
||
|
.LP
|
||
|
Generally, this volume of IEEE\ Std\ 1003.1-2001 is silent about what
|
||
|
happens when options are given multiple times. In
|
||
|
the cases of \fB-C\fP, \fB-l\fP, and \fB-1\fP, however, it does specify
|
||
|
the results of these overlapping options. Since
|
||
|
\fIls\fP is one of the most aliased commands, it is important that
|
||
|
the implementation perform intuitively. For example, if the
|
||
|
alias were:
|
||
|
.sp
|
||
|
.RS
|
||
|
.nf
|
||
|
|
||
|
\fBalias ls="ls -C"
|
||
|
\fP
|
||
|
.fi
|
||
|
.RE
|
||
|
.LP
|
||
|
and the user typed \fIls\fP \fB-1\fP, single-text-column output should
|
||
|
result, not an error.
|
||
|
.LP
|
||
|
The BSD \fIls\fP provides a \fB-A\fP option (like \fB-a\fP, but dot
|
||
|
and dot-dot are not written out). The small difference
|
||
|
from \fB-a\fP did not seem important enough to require both.
|
||
|
.LP
|
||
|
Implementations may make \fB-q\fP the default for terminals to prevent
|
||
|
trojan horse attacks on terminals with special escape
|
||
|
sequences. This is not required because:
|
||
|
.IP " *" 3
|
||
|
Some control characters may be useful on some terminals; for example,
|
||
|
a system might write them as \fB"\\001"\fP or
|
||
|
\fB"^A"\fP .
|
||
|
.LP
|
||
|
.IP " *" 3
|
||
|
Special behavior for terminals is not relevant to applications portability.
|
||
|
.LP
|
||
|
.LP
|
||
|
An early proposal specified that the optional alternate access method
|
||
|
flag had to be \fB'+'\fP 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:
|
||
|
.IP " 1." 4
|
||
|
There are historical implementations using characters other than \fB'+'\fP
|
||
|
\&.
|
||
|
.LP
|
||
|
.IP " 2." 4
|
||
|
There are implementations that vary this character used in that position
|
||
|
to distinguish between various alternate access methods
|
||
|
in use.
|
||
|
.LP
|
||
|
.IP " 3." 4
|
||
|
The standard developers did not want to preclude future specifications
|
||
|
that might need a way to specify more than one alternate
|
||
|
access method.
|
||
|
.LP
|
||
|
.LP
|
||
|
Nonetheless, implementations providing a single alternate access method
|
||
|
are encouraged to use \fB'+'\fP .
|
||
|
.LP
|
||
|
In an early proposal, the units used to specify the number of blocks
|
||
|
occupied by files in a directory in an \fIls\fP \fB-l\fP
|
||
|
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.
|
||
|
.LP
|
||
|
The <\fIdate\ and\ time\fP> field in the \fB-l\fP 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".
|
||
|
.SH FUTURE DIRECTIONS
|
||
|
.LP
|
||
|
The \fB-s\fP uses implementation-defined units and cannot be used
|
||
|
portably; it may be withdrawn in a future version.
|
||
|
.SH SEE ALSO
|
||
|
.LP
|
||
|
\fIchmod\fP() , \fIfind\fP , the System Interfaces volume of
|
||
|
IEEE\ Std\ 1003.1-2001, \fIstat\fP(), the Base Definitions volume
|
||
|
of
|
||
|
IEEE\ Std\ 1003.1-2001, \fI<sys/stat.h>\fP
|
||
|
.SH COPYRIGHT
|
||
|
Portions of this text are reprinted and reproduced in electronic form
|
||
|
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
|
||
|
-- Portable Operating System Interface (POSIX), The Open Group Base
|
||
|
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
|
||
|
Electrical and Electronics Engineers, Inc and The Open Group. In the
|
||
|
event of any discrepancy between this version and the original IEEE and
|
||
|
The Open Group Standard, the original IEEE and The Open Group Standard
|
||
|
is the referee document. The original Standard can be obtained online at
|
||
|
http://www.opengroup.org/unix/online.html .
|