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 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(0p))
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(0p)). 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:
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 POSIX.1‐2017, Section 4.5, 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, -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.
