LS(1)                      POSIX Programmer's Manual                     LS(1)



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

NNAAMMEE
       ls -- list directory contents

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

DDEESSCCRRIIPPTTIIOONN
       For each operand that names a file of a type other than directory or
       symbolic link to a directory, _l_s shall write the name of the file as
       well as any requested, associated information. For each operand that
       names a file of type directory, _l_s 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 --AA or --aa option is supplied, or an implementation-
       defined condition causes them to be written. If one or more of the --dd,
       --FF, or --ll options are specified, and neither the --HH nor the --LL option
       is specified, for each operand that names a file of type symbolic link
       to a directory, _l_s shall write the name of the file as well as any
       requested, associated information. If none of the --dd, --FF, or --ll options
       are specified, or the --HH or --LL options are specified, for each operand
       that names a file of type symbolic link to a directory, _l_s 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 _l_s shall evaluate the file information
       and file type to be those of the symbolic link itself, unless the --LL
       option is specified.

       If no operands are specified, _l_s shall behave as if a single operand of
       dot (''..'')  had been specified. If more than one operand is specified,
       _l_s 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 _l_s 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, _S_e_c_t_i_o_n _7_._3_._2, _L_C___C_O_L_L_A_T_E), then any filenames
       or pathnames that collate equally should be further compared byte-by-
       byte using the collating sequence for the POSIX locale.

       The _l_s 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, _l_s shall write a
       diagnostic message to standard error and shall either recover its
       position in the hierarchy or terminate.

OOPPTTIIOONNSS
       The _l_s utility shall conform to the Base Definitions volume of
       POSIX.1-2017, _S_e_c_t_i_o_n _1_2_._2, _U_t_i_l_i_t_y _S_y_n_t_a_x _G_u_i_d_e_l_i_n_e_s.

       The following options shall be supported:

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

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

       --FF        Do not follow symbolic links named as operands unless the --HH
                 or --LL 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.

       --HH        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, _l_s
                 shall write the name of the link itself and not the file
                 referenced by the link.

       --LL        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, _l_s shall write the
                 name of the link itself and not the file referenced by the
                 link. When --LL is used with --ll, write the contents of symbolic
                 links in the long format (see the STDOUT section).

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

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

       --aa        Write out all directory entries, including those whose names
                 begin with a <period> (''..'').

       --cc        Use time of last modification of the file status information
                 (see the Base Definitions volume of POSIX.1-2017,
                 <<ssyyss__ssttaatt..hh>>) instead of last modification of the file itself
                 for sorting (--tt) or writing (--ll).

       --dd        Do not follow symbolic links named as operands unless the --HH
                 or --LL options are specified. Do not treat directories
                 differently than other types of files. The use of --dd with --RR
                 or --ff produces unspecified results.

       --ff        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 --aa.  When
                 --ff is specified, any occurrences of the --rr, --SS, and --tt
                 options shall be ignored and any occurrences of the --AA, --gg,
                 --ll, --nn, --oo, and --ss options may be ignored. The use of --ff with
                 --RR or --dd produces unspecified results.

       --gg        Turn on the --ll (ell) option, but disable writing the file's
                 owner name or number.  Disable the --CC, --mm, and --xx options.

       --ii        For each file, write the file's file serial number (see
                 _s_t_a_t() in the System Interfaces volume of POSIX.1-2017).

       --kk        Set the block size for the --ss option and the per-directory
                 block count written for the --ll, --nn, --ss, --gg, and --oo options
                 (see the STDOUT section) to 1024 bytes.

       --ll        (The letter ell.) Do not follow symbolic links named as
                 operands unless the --HH or --LL options are specified. Write out
                 in long format (see the STDOUT section). Disable the --CC, --mm,
                 and --xx options.

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

       --nn        Turn on the --ll (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 --CC,
                 --mm, and --xx options.

       --oo        Turn on the --ll (ell) option, but disable writing the file's
                 group name or number.  Disable the --CC, --mm, and --xx options.

       --pp        Write a <slash> (''//'') after each filename if that file is a
                 directory.

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

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

       --ss        Indicate the total number of file system blocks consumed by
                 each file displayed. If the --kk option is also specified, the
                 block size shall be 1024 bytes; otherwise, the block size is
                 implementation-defined.

       --tt        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 _l_s
                 is evaluating its file information to be that of the file
                 referenced by the link (see the --HH and --LL options).

       --uu        Use time of last access (see the Base Definitions volume of
                 POSIX.1-2017, <<ssyyss__ssttaatt..hh>>) instead of last modification of
                 the file for sorting (--tt) or writing (--ll).

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

       --11        (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 --gg, --ll (ell), --nn, and --oo; and
                 disabled by --CC, --mm, and --xx.)

       If an option that enables long format output (--gg, --ll (ell), --nn, and --oo
       is given with an option that disables long format output (--CC, --mm, and
       --xx), this shall not be considered an error. The last of these options
       specified shall determine whether long format output is written.

       If --RR, --dd, or --ff 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 --tt is specified, --cc and --uu are not only mutually-exclusive
       with each other, they are also mutually-exclusive with --SS when
       determining sort order. But even if --SS is specified after all
       occurrences of --cc, --tt, and --uu, the last use of --cc or --uu determines the
       timestamp printed when producing long format output.

OOPPEERRAANNDDSS
       The following operand shall be supported:

       _f_i_l_e      A pathname of a file to be written. If the file specified is
                 not found, a diagnostic message shall be output on standard
                 error.

SSTTDDIINN
       Not used.

IINNPPUUTT FFIILLEESS
       None.

EENNVVIIRROONNMMEENNTT VVAARRIIAABBLLEESS
       The following environment variables shall affect the execution of _l_s:

       _C_O_L_U_M_N_S   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 _l_s
                 utility shall calculate how many pathname text columns to
                 write (see --CC) based on the width provided. If _C_O_L_U_M_N_S 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.

       _L_A_N_G      Provide a default value for the internationalization
                 variables that are unset or null. (See the Base Definitions
                 volume of POSIX.1-2017, _S_e_c_t_i_o_n _8_._2, _I_n_t_e_r_n_a_t_i_o_n_a_l_i_z_a_t_i_o_n
                 _V_a_r_i_a_b_l_e_s for the precedence of internationalization
                 variables used to determine the values of locale categories.)

       _L_C___A_L_L    If set to a non-empty string value, override the values of
                 all the other internationalization variables.

       _L_C___C_O_L_L_A_T_E
                 Determine the locale for character collation information in
                 determining the pathname collation sequence.

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

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

       _L_C___T_I_M_E   Determine the format and contents for date and time strings
                 written by _l_s.

       _N_L_S_P_A_T_H   Determine the location of message catalogs for the processing
                 of _L_C___M_E_S_S_A_G_E_S.

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

AASSYYNNCCHHRROONNOOUUSS EEVVEENNTTSS
       Default.

SSTTDDOOUUTT
       The default format shall be to list one entry per line to standard
       output; the exceptions are to terminals or when one of the --CC, --mm, or
       --xx options is specified. If the output is to a terminal, the format is
       implementation-defined.

       When --mm is specified, the format used for the last element of the list
       shall be:


           "%s\n", <_f_i_l_e_n_a_m_e>

       The format used for each other element of the list shall be:


           "%s,%s", <_f_i_l_e_n_a_m_e>, <_s_e_p_a_r_a_t_o_r>

       where, if there is not room for the next element of the list to fit
       within the current line length, <_s_e_p_a_r_a_t_o_r> is a string containing an
       optional <space> character and a mandatory <newline> character;
       otherwise it is a single <space> character.

       If the --ii option is specified, the file's file serial number (see the
       Base Definitions volume of POSIX.1-2017, <<ssyyss__ssttaatt..hh>>) shall be written
       in the following format before any other output for the corresponding
       entry:


           %u ", <_f_i_l_e _s_e_r_i_a_l _n_u_m_b_e_r>

       If the --ll 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", <_f_i_l_e _m_o_d_e>, <_n_u_m_b_e_r _o_f _l_i_n_k_s>,
               <_o_w_n_e_r _n_a_m_e>, <_g_r_o_u_p _n_a_m_e>, <_s_i_z_e>, <_d_a_t_e _a_n_d _t_i_m_e>,
               <_p_a_t_h_n_a_m_e>

       If the --ll option is specified, the following information shall be
       written for character special and block special files:


           "%s %u %s %s %s %s %s\n", <_f_i_l_e _m_o_d_e>, <_n_u_m_b_e_r _o_f _l_i_n_k_s>,
               <_o_w_n_e_r _n_a_m_e>, <_g_r_o_u_p _n_a_m_e>, <_d_e_v_i_c_e _i_n_f_o>, <_d_a_t_e _a_n_d _t_i_m_e>,
               <_p_a_t_h_n_a_m_e>

       In both cases if the file is a symbolic link and the --LL option is also
       specified, this information shall be for the file resolved from the
       symbolic link, except that the <_p_a_t_h_n_a_m_e> field shall contain the
       pathname of the symbolic link itself. If the file is a symbolic link
       and the --LL option is not specified, this information shall be about the
       link itself and the <_p_a_t_h_n_a_m_e> field shall be of the form:


           "%s -> %s", <_p_a_t_h_n_a_m_e _o_f _l_i_n_k>, <_c_o_n_t_e_n_t_s _o_f _l_i_n_k>

       The --nn, --gg, and --oo options use the same format as --ll, but with omitted
       items and their associated <blank> characters. See the OPTIONS section.

       In both the preceding --ll forms, if <_o_w_n_e_r _n_a_m_e> or <_g_r_o_u_p _n_a_m_e> cannot
       be determined, or if --nn is given, they shall be replaced with their
       associated numeric values using the format %%uu.

       The <_s_i_z_e> field shall contain the value that would be returned for the
       file in the _s_t___s_i_z_e field of ssttrruucctt ssttaatt (see the Base Definitions
       volume of POSIX.1-2017, <<ssyyss__ssttaatt..hh>>).  Note that for some file types
       this value is unspecified.

       The <_d_e_v_i_c_e _i_n_f_o> field shall contain implementation-defined
       information associated with the device in question.

       The <_d_a_t_e _a_n_d _t_i_m_e> 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 _d_a_t_e
       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 %%ee and %%YY) 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 _d_a_t_e shall not be included and the output shall be as if
       the _d_a_t_e command were executed at the time of the last modification
       date of the file rather than the current time. When the _L_C___T_I_M_E 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 _f_i_l_e operand, it shall be written as
       specified.

       The file mode written under the --ll, --nn, --gg, and --oo options shall
       consist of the following format:


           "%c%s%s%s%s", <_e_n_t_r_y _t_y_p_e>, <_o_w_n_e_r _p_e_r_m_i_s_s_i_o_n_s>,
               <_g_r_o_u_p _p_e_r_m_i_s_s_i_o_n_s>, <_o_t_h_e_r _p_e_r_m_i_s_s_i_o_n_s>,
               <_o_p_t_i_o_n_a_l _a_l_t_e_r_n_a_t_e _a_c_c_e_s_s _m_e_t_h_o_d _f_l_a_g>

       The <_o_p_t_i_o_n_a_l _a_l_t_e_r_n_a_t_e _a_c_c_e_s_s _m_e_t_h_o_d _f_l_a_g> 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 <_e_n_t_r_y _t_y_p_e> 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:

       <_o_w_n_e_r _p_e_r_m_i_s_s_i_o_n_s>
             Permissions for the file owner class (see the Base Definitions
             volume of POSIX.1-2017, _S_e_c_t_i_o_n _4_._5, _F_i_l_e _A_c_c_e_s_s _P_e_r_m_i_s_s_i_o_n_s).

       <_g_r_o_u_p _p_e_r_m_i_s_s_i_o_n_s>
             Permissions for the file group class.

       <_o_t_h_e_r _p_e_r_m_i_s_s_i_o_n_s>
             Permissions for the file other class.

       Each field shall have three character positions:

        1. If ''rr'', the file is readable; if ''--'', the file is not readable.

        2. If ''ww'', the file is writable; if ''--'', the file is not writable.

        3. The first of the following that applies:

           S     If in <_o_w_n_e_r _p_e_r_m_i_s_s_i_o_n_s>, the file is not executable and
                 set-user-ID mode is set. If in <_g_r_o_u_p _p_e_r_m_i_s_s_i_o_n_s>, the file
                 is not executable and set-group-ID mode is set.

           s     If in <_o_w_n_e_r _p_e_r_m_i_s_s_i_o_n_s>, the file is executable and set-
                 user-ID mode is set. If in <_g_r_o_u_p _p_e_r_m_i_s_s_i_o_n_s>, the file is
                 executable and set-group-ID mode is set.

           T     If in <_o_t_h_e_r _p_e_r_m_i_s_s_i_o_n_s> and the file is a directory, search
                 permission is not granted to others, and the restricted
                 deletion flag is set.

           t     If in <_o_t_h_e_r _p_e_r_m_i_s_s_i_o_n_s> 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 ''SS'', ''ss'', ''TT'', ''tt'', or ''xx'' 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 --ll, --nn, --ss, --gg, or --oo 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 --kk option is not specified, or
       1024-byte units if the --kk 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", <_n_u_m_b_e_r _o_f _u_n_i_t_s _i_n _t_h_e _d_i_r_e_c_t_o_r_y>

       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 --RR option, each list of files within a directory shall
       be preceded by:


           "\n%s:\n", <_d_i_r_e_c_t_o_r_y _n_a_m_e>

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

SSTTDDEERRRR
       The standard error shall be used only for diagnostic messages.

OOUUTTPPUUTT FFIILLEESS
       None.

EEXXTTEENNDDEEDD DDEESSCCRRIIPPTTIIOONN
       None.

EEXXIITT SSTTAATTUUSS
       The following exit values shall be returned:

        0    Successful completion.

       >0    An error occurred.

CCOONNSSEEQQUUEENNCCEESS OOFF EERRRROORRSS
       Default.

       _T_h_e _f_o_l_l_o_w_i_n_g _s_e_c_t_i_o_n_s _a_r_e _i_n_f_o_r_m_a_t_i_v_e_.

AAPPPPLLIICCAATTIIOONN UUSSAAGGEE
       Many implementations use the <equals-sign> (''=='') to denote sockets
       bound to the file system for the --FF option. Similarly, many historical
       implementations use the ''ss'' character to denote sockets as the entry
       type characters for the --ll option.

       It is difficult for an application to use every part of the file modes
       field of _l_s --ll 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 _t_e_s_t utility.

       The output of _l_s (with the --ll and related options) contains information
       that logically could be used by utilities such as _c_h_m_o_d and _t_o_u_c_h 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
       _l_s 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).

EEXXAAMMPPLLEESS
       An example of a small directory tree being fully listed with _l_s --llaaRRFF aa
       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

RRAATTIIOONNAALLEE
       Some historical implementations of the _l_s utility show all entries in a
       directory except dot and dot-dot when a superuser invokes _l_s without
       specifying the --aa option. When ``normal'' users invoke _l_s without
       specifying --aa, they should not see information about any files with
       names beginning with a <period> unless they were named as _f_i_l_e
       operands.

       Implementations are expected to traverse arbitrary depths when
       processing the --RR option. The only limitation on depth should be based
       on running out of physical storage for keeping track of untraversed
       directories.

       The --11 (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 --SS 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:

       --SS        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-2017 is frequently silent about what happens
       when mutually-exclusive options are specified. Except for --RR, --dd, and
       --ff, the _l_s 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 _l_s 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 _l_s --11 (one), single-text-column output should
       result, not an error.

       The --gg, --ll (ell), --nn, and --oo 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 --gg is present),
       file's group is written (no if --oo 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 --nn is present). The
       --CC, --mm, --xx, and --11 (one) are mutually-exclusive options and the first
       three of these disable long format output. The --11 (one) option does not
       directly change whether or not long format output is enabled, but by
       overriding --CC, --mm, and --xx, 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 --AA option
       (like --aa, but dot and dot-dot are not written out). It has been added
       due to widespread implementation.

       Implementations may make --qq 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 ""\\000011"" or ""^^AA"".

        *  Special behavior for terminals is not relevant to applications
           portability.

       An early proposal specified that the
       <_o_p_t_i_o_n_a_l _a_l_t_e_r_n_a_t_e _a_c_c_e_s_s _m_e_t_h_o_d _f_l_a_g> 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 ''++''.

       Earlier versions of this standard did not have the --kk option, which
       meant that the --ss 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 _l_s --ll listing were fixed
       as 512-byte units. The --kk option has been added to provide a way for
       the --ss option to be used portably, and for consistency it also changes
       the aforementioned units from 512-byte to 1024-byte.

       The <_d_a_t_e _a_n_d _t_i_m_e> field in the --ll 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''.

FFUUTTUURREE DDIIRREECCTTIIOONNSS
       Allowing --ff to ignore the --AA, --gg, --ll, --nn, --oo, and --ss options may be
       removed in a future version.

       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.

SSEEEE AALLSSOO
       _c_h_m_o_d, _f_i_n_d

       The Base Definitions volume of POSIX.1-2017, _S_e_c_t_i_o_n _7_._3_._2, _L_C___C_O_L_L_A_T_E,
       _S_e_c_t_i_o_n _4_._5, _F_i_l_e _A_c_c_e_s_s _P_e_r_m_i_s_s_i_o_n_s, _C_h_a_p_t_e_r _8, _E_n_v_i_r_o_n_m_e_n_t _V_a_r_i_a_b_l_e_s,
       _S_e_c_t_i_o_n _1_2_._2, _U_t_i_l_i_t_y _S_y_n_t_a_x _G_u_i_d_e_l_i_n_e_s, <<ssyyss__ssttaatt..hh>>

       The System Interfaces volume of POSIX.1-2017, _f_s_t_a_t_a_t()

CCOOPPYYRRIIGGHHTT
       Portions of this text are reprinted and reproduced in electronic form
       from IEEE Std 1003.1-2017, Standard for Information Technology --
       Portable Operating System Interface (POSIX), The Open Group Base
       Specifications Issue 7, 2018 Edition, Copyright (C) 2018 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 .

       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 .



IEEE/The Open Group                  2017                                LS(1)
