ls






This manual page is part of the POSIX Programmer’s Manual.
The Linux implementation of this interface may differ
(consult the corresponding Linux manual page for details of
Linux behavior), or the interface may not be implemented on
Linux.


ls — list directory contents



ls [−ikqrs] [−glno] [−A|−a] [−C|−m|−x|−1] \
    [−F|−p] [−H|−L] [−R|−d] [−S|−f|−t] [−c|−u] [file...]

For each operand that names a file of a type other than
directory or symbolic link to a directory, shall write the
name of the file as well as any requested, associated
information. For each operand that names a file of type
directory, shall write the names of files contained within
the directory as well as any requested, associated
information. Filenames beginning with a <period> (and any
associated information shall not be written out unless
explicitly referenced, the or option is supplied, or an
implementation‐defined condition causes them to be written.
If one or more of the or options are specified, and neither
the nor the option is specified, for each operand that names
a file of type symbolic link to a directory, shall write the
name of the file as well as any requested, associated
information. If none of the or options are specified, or the
or options are specified, for each operand that names a file
of type symbolic link to a directory, shall write the names
of files contained within the directory as well as any
requested, associated information. In each case where the
names of files contained within a directory are written, if
the directory contains any symbolic links then shall
evaluate the file information and file type to be those of
the symbolic link itself, unless the option is specified.
If no operands are specified, shall behave as if a single
operand of dot (had been specified. If more than one operand
is specified, 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 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, shall
write a diagnostic message to standard error and shall
either recover its position in the hierarchy or terminate.

The utility shall conform to the Base Definitions volume of
POSIX.1‐2008, The following options shall be supported:

−A        Write out all directory entries, including those
          whose names begin with a <period> (but excluding
          the entries dot and dot‐dot (if they exist).









                             ‐2‐


−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. This option disables long format output.

−F        Do not follow symbolic links named as operands
          unless the or options are specified. Write a
          <slash> (immediately after each pathname that is a
          directory, an <asterisk> (after each that is
          executable, a <vertical‐line> (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        Evaluate the file information and file type for
          symbolic links specified on the command line to be
          those of the file referenced by the link, and not
          the link itself; however, 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, shall write the name of
          the link itself and not the file referenced by the
          link. When is used with write the contents of
          symbolic links in the long format (see the STDOUT
          section).

−R        Recursively list subdirectories encountered. When
          a symbolic link to a directory is encountered, the
          directory shall not be recursively listed unless
          the option is specified.  The use of with or
          produces unspecified results.

−S        Sort with the primary key being file size (in
          decreasing order) and the secondary key being
          filename in the collating sequence (in increasing
          order).

−a        Write out all directory entries, including those
          whose names begin with a <period> (

−c        Use time of last modification of the file status
          information (see the Base Definitions volume of
          POSIX.1‐2008, instead of last modification of the
          file itself for sorting (or writing (

−d        Do not follow symbolic links named as operands
          unless the or options are specified. Do not treat









                             ‐3‐


          directories differently than other types of files.
          The use of with or produces unspecified results.

−f        List the entries in directory operands in the
          order they appear in the directory. The behavior
          for non‐directory operands is unspecified. This
          option shall turn on When is specified, any
          occurrences of the and options shall be ignored
          and any occurrences of the and options may be
          ignored. The use of with or produces unspecified
          results.

−g        Turn on the (ell) option, but disable writing the
          file’s owner name or number.  Disable the and
          options.

−i        For each file, write the file’s file serial number
          (see stat() in the System Interfaces volume of
          POSIX.1‐2008).

−k        Set the block size for the option and the per‐
          directory block count written for the and options
          (see the STDOUT section) to 1024 bytes.

−l        (The letter ell.) Do not follow symbolic links
          named as operands unless the or options are
          specified. Write out in long format (see the
          STDOUT section). Disable the and options.

−m        Stream output format; list pathnames across the
          page, separated by a <comma> character followed by
          a <space> character. Use a <newline> character as
          the list terminator and after the separator
          sequence when there is not room on a line for the
          next list entry. This option disables long format
          output.

−n        Turn on the (ell) option, but when writing the
          file’s owner or group, write the file’s numeric
          UID or GID rather than the user or group name,
          respectively. Disable the and options.

−o        Turn on the (ell) option, but disable writing the
          file’s group name or number.  Disable the and
          options.

−p        Write a <slash> (after each filename if that file
          is a directory.

−q        Force each instance of non‐printable filename
          characters and <tab> characters to be written as
          the <question‐mark> (character. Implementations
          may provide this option by default if the output
          is to a terminal device.









                             ‐4‐


−r        Reverse the order of the sort to get reverse
          collating sequence oldest first, or smallest file
          size first depending on the other options given.

−s        Indicate the total number of file system blocks
          consumed by each file displayed. If the option is
          also specified, the block size shall be 1024
          bytes; otherwise, 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.  For
          a symbolic link, the time used as the sort key is
          that of the symbolic link itself, unless is
          evaluating its file information to be that of the
          file referenced by the link (see the and options).

−u        Use time of last access (see the Base Definitions
          volume of POSIX.1‐2008, instead of last
          modification of the file for sorting (or writing (

−x        The same as except that the multi‐text‐column
          output is produced with entries sorted across,
          rather than down, the columns. This option
          disables long format output.

−1        (The numeric digit one.) Force output to be one
          entry per line.  This option does not disable long
          format output. (Long format output is enabled by
          (ell), and and disabled by and If an option that
          enables long format output ((ell), and is given
          with an option that disables long format output
          (and this shall not be considered an error. The
          last of these options specified shall determine
          whether long format output is written.  If or 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 is specified, and are
          not only mutually‐exclusive with each other, they
          are also mutually‐exclusive with when determining
          sort order. But even if is specified after all
          occurrences of and the last use of or determines
          the timestamp printed when producing long format
          output.













                             ‐5‐


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.

Not used.

None.

The following environment variables shall affect the
execution of

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 utility shall calculate how
          many pathname text columns to write (see based on
          the width provided. If 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
          POSIX.1‐2008, 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

LC_MESSAGES
          Determine the locale that should be used to affect
          the format and contents of diagnostic messages
          written to standard error.










                             ‐6‐


LC_TIME   Determine the format and contents for date and
          time strings written by

NLSPATH   Determine the location of message catalogs for the
          processing of

TZ        Determine the timezone for date and time strings
          written by If is unset or null, an unspecified
          default timezone shall be used.

Default.

The default format shall be to list one entry per line to
standard output; the exceptions are to terminals or when one
of the or options is specified. If the output is to a
terminal, the format is implementation‐defined.  When 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 option is specified, the file’s
file serial number (see the Base Definitions volume of
POSIX.1‐2008, shall be written in the following format
before any other output for the corresponding entry:

          %u ", <file serial number>
If the 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 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 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 option is not
specified, this information shall be about the link itself
and the <pathname> field shall be of the form:










                             ‐7‐


          "%s −> %s", <pathname of link>, <contents of link>
The and options use the same format as but with omitted
items and their associated <blank> characters. See the
OPTIONS section.  In both the preceding forms, if <owner
name> or <group name> cannot be determined, or if is given,
they shall be replaced with their associated numeric values
using the format The <size> field shall contain the value
that would be returned for the file in the field of (see the
Base Definitions volume of POSIX.1‐2008, 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
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 and 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 shall not be included
and the output shall be as if the command were executed at
the time of the last modification date of the file rather
than the current time. When the 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 operand, it shall be written as specified.
The file mode written under the and 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.










                             ‐8‐


−       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‐2008,

<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 the file is readable; if the file is not readable.

 2. If 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 or 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 or 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 option is not specified, or 1024‐byte units if the









                             ‐9‐


    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 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
    option is given, each file shall be written with the
    number of blocks used by the file. Along with or the
    number and a <space> shall precede the filename; with or
    they shall precede each line describing a file.

The standard error shall be used only for diagnostic
messages.

None.

None.

The following exit values shall be returned:

 0    Successful completion.

>0    An error occurred.

Default.


Many implementations use the <equals‐sign> (to denote
sockets bound to the file system for the option. Similarly,
many historical implementations use the character to denote
sockets as the entry type characters for the option.  It is
difficult for an application to use every part of the file
modes field of 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 utility.  The output of (with the
and related options) contains information that logically
could be used by utilities such as and 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









                            ‐10‐


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 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).

An example of a small directory tree being fully listed with
in the POSIX locale:

     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

Some historical implementations of the utility show all
entries in a directory except dot and dot‐dot when a
superuser invokes without specifying the option. When
‘‘normal’’ users invoke without specifying they should not
see information about any files with names beginning with a
<period> unless they were named as operands.
Implementations are expected to traverse arbitrary depths
when processing the option. The only limitation on depth
should be based on running out of physical storage for
keeping track of untraversed directories.  The (one) option
was historically found in BSD and BSD‐derived
implementations only. It is required in this volume of
POSIX.1‐2008 so that conforming applications might ensure
that output is one entry per line, even if the output is to
a terminal.  The 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









                            ‐11‐


described it as something like:

−S        Sort by size (largest size first) instead of by
          name. Special character devices (listed last) are
          sorted by name.  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‐2008 is frequently silent about what
          happens when mutually‐exclusive options are
          specified. Except for and the 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 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 (one), single‐text‐column
          output should result, not an error.  The (ell),
          and 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 is present), file’s group is
          written (no if 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 is present). The and
          (one) are mutually‐exclusive options and the first
          three of these disable long format output. The
          (one) option does not directly change whether or
          not long format output is enabled, but by
          overriding and 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 option (like but dot and dot‐dot are not
          written out). It has been added due to widespread
          implementation.  Implementations may make 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 or

 *  Special behavior for terminals is not relevant to
    applications portability.  An early proposal specified
    that the <optional alternate access method flag> had to









                            ‐12‐


    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 Earlier versions of this
    standard did not have the option, which meant that the
    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 listing were fixed as 512‐byte units. The option has
    been added to provide a way for the 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 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‐2008, as the
    appropriate vehicle is a messaging system; that is, the
    format should be specified as a ‘‘message’’.

Allowing to ignore the and options may be removed in a
future version.

The Base Definitions volume of POSIX.1‐2008, The System
Interfaces volume of POSIX.1‐2008,

Portions of this text are reprinted and reproduced in
electronic form from IEEE Std 1003.1, 2013 Edition, Standard
for Information Technology ‐‐ Portable Operating System
Interface (POSIX), The Open Group Base Specifications Issue
7, Copyright (C) 2013 by the Institute of Electrical and
Electronics Engineers, Inc and The Open Group.  (This is
POSIX.1‐2008 with the 2013 Technical Corrigendum 1 applied.)
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.unix.org/online.html .

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









                            ‐13‐


such errors, see https://www.kernel.org/doc/man‐
pages/reporting_bugs.html .