ls [-ikqrs] [-glno] [-A|-a] [-C|-m|-x|-1] \
[-F|-p] [-H|-L] [-R|-d] [-S|-f|-t] [-c|-u] [file...]
If no operands are specified, ls shall behave as if a single operand of dot ('.') had been specified. 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.
Whenever ls sorts filenames or pathnames according to the collating sequence in the current locale, if this collating sequence does not have a total ordering of all characters (see the Base Definitions volume of POSIX.1-2017, Section 7.3.2, LC_COLLATE), then any filenames or pathnames that collate equally should be further compared byte-by-byte using the collating sequence for the POSIX 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.
The following options shall be supported:
If an option that enables long format output (-g, -l (ell), -n, and \-o is given with an option that disables long format output (-C, -m, and -x), this shall not be considered an error. The last of these options specified shall determine whether long format output is written.
If -R, -d, or -f are specified, the results of specifying these mutually-exclusive options are specified by the descriptions of these options above. If more than one of any of the other options shown in the SYNOPSIS section in mutually-exclusive sets are given, this shall not be considered an error; the last option specified in each set shall determine the output.
Note that if -t is specified, -c and -u are not only mutually-exclusive with each other, they are also mutually-exclusive with -S when determining sort order. But even if -S is specified after all occurrences of -c, -t, and -u, the last use of -c or -u determines the timestamp printed when producing long format output.
When -m is specified, the format used for the last element of the list shall be:
"%s\n", <filename>
The format used for each other element of the list shall be:
"%s,%s", <filename>, <separator>
where, if there is not room for the next element of the list to fit within the current line length, <separator> is a string containing an optional <space> character and a mandatory <newline> character; otherwise it is a single <space> character.
If the -i option is specified, the file's file serial number (see the Base Definitions volume of POSIX.1-2017, <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, the following information shall be written for files other than character special and block special files:
"%s %u %s %s %u %s %s\n", <file mode>, <number of links>,
<owner name>, <group name>, <size>, <date and time>,
<pathname>
If the -l option is specified, the following information shall be written for character special and block special files:
"%s %u %s %s %s %s %s\n", <file mode>, <number of links>,
<owner name>, <group name>, <device info>, <date and time>,
<pathname>
In both cases if the file is a symbolic link and the -L option is also specified, this information shall be for the file resolved from the symbolic link, except that the <pathname> field shall contain the pathname of the symbolic link itself. If the file is a symbolic link and the -L option is not specified, 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>
The -n, -g, and -o options use the same format as -l, but with omitted items and their associated <blank> characters. 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 <size> field shall contain the value that would be returned for the file in the st_size field of struct stat (see the Base Definitions volume of POSIX.1-2017, <sys_stat.h>). Note that for some file types this value is unspecified.
The <device info> field shall contain implementation-defined information associated with the device in question.
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> characters 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 pathname was specified as a file operand, it shall be written as specified.
The file mode written under the -l, -n, -g, and -o options shall consist of the following format:
"%c%s%s%s%s", <entry type>, <owner permissions>,
<group permissions>, <other permissions>,
<optional alternate access method flag>
The <optional alternate access method flag> shall be the empty string if there is no alternate or additional access control method associated with the file; otherwise, it shall be a string containing a single printable character that is not a <blank>.
The <entry type> character shall describe the type of file, as follows:
Implementations may add other characters to this list to represent other implementation-defined file types.
The next three fields shall be three characters each:
Each field shall have three character positions:
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, -n, -s, -g, or -o 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 if the -k option is not specified, or 1024-byte units if the -k option is specified, 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 -l, -n, -g, or -o, they shall precede each line describing a file.
The following sections are informative.
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 versions 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).
total 11 drwxr-xr-x 3 fox prog 64 Jul 4 12:07 ./ drwxrwxrwx 4 fox prog 3264 Jul 4 12:09 ../ drwxr-xr-x 2 fox prog 48 Jul 4 12:07 b/ -rwxr--r-- 1 fox prog 572 Jul 4 12:07 foo* a/b: total 4 drwxr-xr-x 2 fox prog 48 Jul 4 12:07 ./ drwxr-xr-x 3 fox prog 64 Jul 4 12:07 ../ -rw-r--r-- 1 fox prog 700 Jul 4 12:07 bar
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 POSIX.1-2017 so that conforming applications might ensure that output is one entry per line, even if the output is to a terminal.
The -S option was added in Issue 7, but had been provided by several implementations for many years. The description given in the standard documents historic practice, but does not match much of the documentation that described its behavior. Historical documentation typically described it as something like:
even though the file type was never considered when sorting the output. Character special files do typically sort close to the end of the list because their file size on most implementations is zero. But they are sorted alphabetically with any other files that happen to have the same file size (zero), not sorted separately and added to the end.
This volume of POSIX.1-2017 is frequently silent about what happens when mutually-exclusive options are specified. Except for -R, -d, and -f, the ls utility is required to accept multiple options from each mutually-exclusive option set without treating them as errors and to use the behavior specified by the last option given in each mutually-exclusive set. 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 (one), single-text-column output should result, not an error.
The -g, -l (ell), -n, and -o options are not mutually-exclusive options. They all enable long format output. They work together to determine whether the file's owner is written (no if -g is present), file's group is written (no if -o is present), and if the file's group or owner is written whether it is written as the name (default) or a string representation of the UID or GID number (if -n is present). The -C, -m, -x, and -1 (one) are mutually-exclusive options and the first three of these disable long format output. The -1 (one) option does not directly change whether or not long format output is enabled, but by overriding -C, -m, and -x, it can re-enable long format output that had been disabled by one of these options.
Earlier versions of this standard did not describe the BSD -A option (like -a, but dot and dot-dot are not written out). It has been added due to widespread implementation.
Implementations may make -q the default for terminals to prevent trojan horse attacks on terminals with special escape sequences. This is not required because:
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:
Nonetheless, implementations providing a single alternate access method are encouraged to use '+'.
Earlier versions of this standard did not have the -k option, which meant that the -s option could not be used portably as its block size was implementation-defined, and the units used to specify the number of blocks occupied by files in a directory in an ls -l listing were fixed as 512-byte units. The -k option has been added to provide a way for the -s option to be used portably, and for consistency it also changes the aforementioned units from 512-byte to 1024-byte.
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 POSIX.1-2017, as the appropriate vehicle is a messaging system; that is, the format should be specified as a ``message''.
A future version of this standard may require that if the collating sequence for the current locale does not have a total ordering of all characters, any filenames or pathnames that collate equally are further compared byte-by-byte using the collating sequence for the POSIX locale.
The Base Definitions volume of POSIX.1-2017, Section 7.3.2, LC_COLLATE, Section 4.5, File Access Permissions, Chapter 8, Environment Variables, Section 12.2, Utility Syntax Guidelines, <sys_stat.h>
The System Interfaces volume of POSIX.1-2017, fstatat()
Any typographical or formatting errors that appear in this page are most likely to have been introduced during the conversion of the source files to man page format. To report such errors, see https://www.kernel.org/doc/man-pages/reporting_bugs.html .