ls(1p) - phpMan

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

PROLOG
       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.
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 con-
       tained within the directory as well as any requested, associated infor-
       mation.  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  cur-
       rent  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  previ-
       ously  visited  directory  that is an ancestor of the last file encoun-
       tered. 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 col-
              umns, 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 sym-
              bolic link. For other file types, other symbols may be written.
       -H     If a symbolic link referencing a file of type directory is spec-
              ified on the command line, ls shall evaluate the  file  informa-
              tion  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 col-
              lating sequence.
       -u     Use time of last access (see <sys/stat.h>) instead of last modi-
              fication of the file for sorting ( -t) or writing ( -l).
       -x     The same as -C, except that the multi-text-column output is pro-
              duced 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 for-
       mat.
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 implementa-
              tion-defined number of column positions shall be assumed,  based
              on the implementation's knowledge of the output device. The col-
              umn width chosen to write the names of files in any given direc-
              tory  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  Vari-
              ables  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 charac-
              ters 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 out-
       put; 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 exceed-
       ing 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 time-
       stamp of when the file was last modified.  In  the  POSIX  locale,  the
       field  shall be the equivalent of the output of the following date com-
       mand:

              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 com-
       mand 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  presenta-
       tion 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  asso-
       ciated 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 Permis-
              sions).
       <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 exe-
              cutable 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 lower-
       case 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  indi-
       cating the number of file system blocks occupied by files in the direc-
       tory 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  op-
       erands,  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  gen-
       erally 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  eas-
       ily  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  permis-
       sions  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 mecha-
       nisms.
       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 speci-
       fying -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 process-
       ing the -R option. The only limitation on depth should be based on run-
       ning  out of physical storage for keeping track of untraversed directo-
       ries.
       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 exam-
          ple, 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  specifica-
           tions  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  implementa-
       tion-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 .

IEEE/The Open Group                  2003                               LS(1P)