path: root/coreutils-5.3.0-bin/man/cat1p/ls.1p.txt

ls(P)                                                     ls(P)





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 contained within the  directory  as  well  as  any
       requested, associated information. 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 spec-
       ified, for each operand that names a file of  type  sym-
       bolic  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 con-
       tents of the current directory. If more than one operand
       is  specified,  ls  shall  write  non-directory operands
       first; it shall sort directory and  non-directory  oper-
       ands  separately  according to the collating sequence in
       the current locale.

       The ls utility shall detect  infinite  loops;  that  is,
       entering  a  previously  visited  directory  that  is an
       ancestor of the last file encountered. When  it  detects
       an infinite loop, ls shall write a diagnostic message to
       standard error and shall either recover its position  in
       the hierarchy or terminate.

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 columns, according to the collat-
              ing  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  symbolic  link.  For  other
              file types, other symbols may be written.

       -H     If  a  symbolic  link  referencing a file of type
              directory is specified on the  command  line,  ls
              shall evaluate the file information 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 ref-
              erenced 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 con-
              tents 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 direc-
              tory  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 num-
              ber (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 STD-
              OUT 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 ques-
              tion-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 col-
              lating sequence or oldest first.

       -s     Indicate  the  total number of file system blocks
              consumed by each file displayed. The  block  size
              is          implementation-defined.          <img
              src="../images/opt-end.gif"  alt="[Option   End]"
              border="0">

       -t     Sort  with  the  primary  key being time modified
              (most recently modified first) and the  secondary
              key being filename in the collating sequence.

       -u     Use   time  of  last  access  (see  <sys/stat.h>)
              instead of last  modification  of  the  file  for
              sorting ( -t) or writing ( -l).

       -x     The same as -C, except that the multi-text-column
              output is produced 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
       format.

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 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 internationaliza-
              tion  variables  that are unset or null. (See the
              Base Definitions volume of  IEEE Std 1003.1-2001,
              Section  8.2,  Internationalization Variables for
              the precedence of internationalization  variables
              used  to  determine  the  values  of locale cate-
              gories.)

       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 mes-
              sages 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 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  implemen-
       tation-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 exceeding 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 fol-
       lowing format before any other  output  for  the  corre-
       sponding 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  informa-
       tion 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 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>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
       command were executed at the time of the last  modifica-
       tion 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 file is a  character  special  or  block  special
       file,  the  size of the file may be replaced with imple-
       mentation-defined information associated 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; other-
       wise, 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 Permissions).

       <group permissions>

              Permissions for the file group class.

       <other permissions>

              Permissions for the file other class.


       Each field shall have three character positions:

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

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

       The first of the following that applies:

       S      If in <owner permissions>, the file is  not  exe-
              cutable  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 permis-
              sions>,  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  oth-
              ers, 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 exe-
       cutable or searchable, and in uppercase if it is not.

       If any of the -l,   -g, -n, -o, or -s options is  speci-
       fied,  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, 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  pre-
       cede  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 guaran-
       teed to be exactly as shown, as implementations may have
       extensions.   Applications  can  use  this field to pass
       directly to a user printout or prompt, but actions based
       on  its  contents should generally be deferred, instead,
       to the test utility.

       The output of ls (with the -l and related options)  con-
       tains information that logically could be used by utili-
       ties such as chmod and touch to restore files to a known
       state.  However, this information is presented in a for-
       mat 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  under-
       stand  instead  of  assuming that they can translate the
       permissions 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. Sys-
       tems 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 specifying -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  processing the -R option. The only limita-
       tion on depth should be based on running out of physical
       storage for keeping track of untraversed directories.

       The  -1  (one)  option was historically found in BSD and
       BSD-derived implementations only. It is required in this
       volume of IEEE Std 1003.1-2001 so that conforming appli-
       cations 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  exam-
       ple, 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 example, 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  alter-
       nate  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:

       There are historical  implementations  using  characters
       other than '+' .

       There  are implementations that vary this character used
       in that position to distinguish between  various  alter-
       nate access methods in use.

       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 alter-
       nate access method are encouraged to use '+' .

       In an early proposal, the units used to specify the num-
       ber  of blocks occupied by files in a directory in an ls
       -l listing were implementation-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 appropri-
       ate.

       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  vol-
       ume 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 Operat-
       ing System Interface (POSIX), The Open Group Base Speci-
       fications Issue 6, Copyright (C) 2001-2003 by the Insti-
       tute 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.open-
       group.org/unix/online.html .



POSIX                         2003                        ls(P)