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