Man Pages

ls(1p) - phpMan ls(1p) - phpMan

Command: man perldoc info search(apropos)  


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 dif-
       fer (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 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 specified, 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 contents 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 operands sep-
       arately 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 ances-
       tor 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 Syn-
       tax Guidelines.

       The following options shall be supported:

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

       -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 exe-
              cutable, 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 eval-
              uate 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 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  sec-
              tion).

       -R     Recursively list subdirectories encountered.

       -a     Write out all directory entries, including those whose names begin with a period ( '.' ). Entries begin-
              ning 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 speci-
              fied. 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 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 path-
              name  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 knowl-
              edge  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 IEEE Std 1003.1-2001, Section 8.2, Internationalization Variables for the prece-
              dence 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  exam-
              ple,  single-byte  as opposed to multi-byte characters in arguments) and which characters 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  writ-
              ten 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 follow-
       ing 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 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 implementa-
       tion-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; 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 Permissions).

       <group permissions>

              Permissions for the file group class.

       <other permissions>

              Permissions for the file other class.


       Each field shall have three character positions:

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


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


        3. The first of the following that applies:

       S
              If in <owner permissions>, the file is not executable and set-user-ID mode is set. If in  <group permis-
              sions>, 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 others, and the
              restricted deletion flag is set.

       x
              The file is executable or the directory is searchable.

       -
              None of the attributes of 'S', 's', 'T', 't', or 'x' applies.


       Implementations may add other characters to this list for the third character position. Such  additions  shall,
       however, be written in lowercase if the file is executable or searchable, and in uppercase if it is not.


       If  any  of  the -l,   -g, -n, -o, or -s 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, 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 pre-
       ceded 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 pre-
       cede 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 generally 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  utili-
       ties  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 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 indica-
       tion 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 issues 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 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 limitation 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 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  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:

        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 '+' .

       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 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 appro-
       priate.

       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, Stan-
       dard  for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifica-
       tions 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 Stan-
       dard, 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)