LS(1)                                                       LS(1)



NAME

       ls, dir, vdir - list directory contents


SYNOPSIS

       ls [options] [file...]
       dir [file...]
       vdir [file...]

       POSIX options: [-CFRacdilqrtu1] [--]

       GNU  options  (shortest  form): [-1abcdfghiklmnopqrstuvwx-
       ABCDFGHLNQRSUX]  [-w  cols]   [-T   cols]   [-I   pattern]
       [--full-time]  [--show-control-chars]  [--block-size=size]
       [--format={long,verbose,commas,across,vertical,single-col-
       umn}]                  [--sort={none,time,size,extension}]
       [--time={atime,access,use,ctime,status}]
       [--color[={none,auto,always}]] [--help] [--version] [--]


DESCRIPTION

       The  program  ls  lists first its non-directory file argu-
       ments, and then for each directory argument  all  listable
       files  contained  within  that directory. If no non-option
       arguments are present, a default argument `.' (the current
       directory)  is  assumed.  The -d option causes directories
       to be treated  as  non-directory  arguments.   A  file  is
       listable  when either its name does not start with `.', or
       the -a option is given.

       Each of the lists of files (that of  non-directory  files,
       and for each directory the list of files inside) is sorted
       separately according to the collating sequence in the cur-
       rent  locale.   When  the -l option is given, each list is
       preceded by a summary line giving the total  size  of  all
       files in the list, measured in semi-kilobytes (512 B).

       The output is to stdout, one entry per line, unless multi-
       column output is requested by the -C option. However,  for
       output  to  a terminal, it is undefined whether the output
       will be single-column or multi-column. The options -1  and
       -C  can  be  used  to force single-column and multi-column
       output, respectively.


POSIX OPTIONS

       -C     List files in columns, sorted vertically.

       -F     Suffix each directory name with `/', each FIFO name
              with  `|', and each name of an executable with `*'.

       -R     Recursively list subdirectories encountered.

       -a     Include files with a name starting with `.' in  the
              listing.

       -c     Use   the   status   change  time  instead  of  the



GNU fileutils 4.0         November 1998                         1





LS(1)                                                       LS(1)


              modification time for sorting (with -t) or  listing
              (with -l).

       -d     List  names of directories like other files, rather
              than listing their contents.

       -i     Precede the output for the file by the file  serial
              number (i-node number).

       -l     Write  (in single-column format) the file mode, the
              number of links to the file, the  owner  name,  the
              group  name,  the  size of the file (in bytes), the
              timestamp, and the filename.

              The file types are as follows: -  for  an  ordinary
              file,  d  for  a  directory,  b for a block special
              device, c for a character special device, l  for  a
              symbolic link, p for a fifo, s for a socket.

              By default, the timestamp shown is that of the last
              modification; the options  -c  and  -u  select  the
              other two timestamps.  For device special files the
              size field is commonly replaced by  the  major  and
              minor device numbers.

       -q     Output  nonprintable  characters  in  a filename as
              question marks.   (This  is  permitted  to  be  the
              default for output to a terminal.)

       -r     Reverse the order of the sort.

       -t     Sort by the timestamp shown.

       -u     Use  the time of last access instead of the modifi-
              cation time for sorting (with -t) or listing  (with
              -l).

       -1     For single-column output.

       --     Terminate option list.


GNU DETAILS

       If standard output is a terminal, the output is in columns
       (sorted vertically).

       dir (also installed as d)  is  equivalent  to  `ls -C -b';
       that  is,  files  are by default listed in columns, sorted
       vertically.  vdir (also installed as v) is  equivalent  to
       `ls -l -b';  that  is, files are by default listed in long
       format.


GNU OPTIONS

       -1, --format=single-column
              List one file per line. This  is  the  default  for



GNU fileutils 4.0         November 1998                         2





LS(1)                                                       LS(1)


              when standard output is not a terminal.

       -a, --all
              List  all files in directories, including all files
              that start with `.'.

       -b, --escape, --quoting-style=escape
              Quote nongraphic characters  in  file  names  using
              alphabetic and octal backslash sequences like those
              used in C. This option is the  same  as  -Q  except
              that filenames are not surrounded by double-quotes.

       -c, --time=ctime, --time=status
              Sort directory contents  according  to  the  files'
              status  change  time (the `ctime' in the inode). If
              the long listing format is being  used  (-l)  print
              the  status change time instead of the modification
              time.

       -d, --directory
              List names of directories like other files,  rather
              than listing their contents.

       -f     Do  not sort directory contents; list them in what-
              ever order they  are  stored  on  the  disk.   Also
              enables -a and -U and disables -l, --color, -s, and
              -t if they were specified before the -f.

       -g     Ignored; for Unix compatibility.

       -h, --human-readable
              Append  a  size  letter,  such  as  M  for   binary
              megabytes  (`mebibytes'),  to  each  size.  (New in
              fileutils-4.0.)

       -i, --inode
              Print the inode number (also called the file serial
              number  and  index number) of each file to the left
              of the file name. (This number uniquely  identifies
              each file within a particular filesystem)

       -k, --kilobytes
              If file sizes are being listed, print them in kilo-
              bytes.

       -l, --format=long, --format=verbose
              In addition to the name of  each  file,  print  the
              file type, permissions, number of hard links, owner
              name, group name, size in bytes, and timestamp (the
              modification time unless other times are selected).
              For files with a time that is more  than  6  months
              old or more than 1 hour into the future, the times-
              tamp contains the year instead of the time of  day.




GNU fileutils 4.0         November 1998                         3





LS(1)                                                       LS(1)


              For  each  directory  that  is  listed, preface the
              files with a line `total blocks', where  blocks  is
              the  total  disk  space  used  by all files in that
              directory.  By default, 1024-byte blocks are  used;
              if the environment variable POSIXLY_CORRECT is set,
              512-byte blocks are used (unless the -k  option  is
              given).  The  blocks computed counts each hard link
              separately; this is arguably a deficiency.

              The permissions listed are similar to symbolic mode
              specifications  but  ls combines multiple bits into
              the third character of each set of permissions

              s      If the setuid or setgid bit and  the  corre-
                     sponding executable bit are both set.

              S      If  the  setuid or setgid bit is set but the
                     corresponding executable bit is not set.

              t      If the sticky bit and  the  other-executable
                     bit are both set.

              T      If  the sticky bit is set but the other-exe-
                     cutable bit is not set.

              x      If the executable bit is set and none of the
                     above apply.

              -      Otherwise.

       -m, --format=commas
              List  files  horizontally, with as many as will fit
              on each line, each  separated  by  a  comma  and  a
              space.

       -n, --numeric-uid-gid
              List  the numeric UID and GID instead of the names.

       -o     Produce long format directory listings,  but  don't
              display  group  information.   It  is equivalent to
              using --format=long  --no-group.   This  option  is
              provided  for  compatibility with other versions of
              ls.

       -p, --file-type, --indicator-style=file-type
              Append a character to each file name indicating the
              file  type. This is like -F except that executables
              aren't marked.  (In fact fileutils-4.0  treats  the
              --file-type option like --classify.)

       -q, --hide-control-chars
              Print  question marks instead of nongraphic charac-
              ters in file names. This is the default.




GNU fileutils 4.0         November 1998                         4





LS(1)                                                       LS(1)


       -r, --reverse
              Sort directory contents in reverse order.

       -s, --size
              Print the size of each file in 1024-byte blocks  to
              the  left  of  the  file  name.  If the environment
              variable POSIXLY_CORRECT is  set,  512-byte  blocks
              are used instead, unless the -k option is given.

       -t, --sort=time
              Sort  by  modification  time  (the  `mtime'  in the
              inode) instead of alphabetically, with  the  newest
              files listed first.

       -u, --time=atime, --time=access, --time=use
              Sort  directory  contents  according  to the files'
              last access time instead of the  modification  time
              (the  `atime'  in  the  inode). If the long listing
              format is being used, print the  last  access  time
              instead of the modification time.

       -v     Sort  directory  contents  according  to the files'
              version.  This takes into  account  the  fact  that
              filenames  frequently  include  indices  or version
              numbers.  Standard sorting functions usually do not
              produce  the  ordering  that  people expect because
              comparisons are made  on  a  character-by-character
              basis.  The version sort adresses this problem, and
              is especially useful when browsing directories that
              contain  many files with indices/version numbers in
              their names.  For example:

                   > ls -1            > ls -1v
                   foo.zml-1.gz       foo.zml-1.gz
                   foo.zml-100.gz     foo.zml-12.gz
                   foo.zml-12.gz      foo.zml-25.gz
                   foo.zml-25.gz      foo.zml-100.gz

              Note also that numeric parts  with  leading  zeroes
              are considered as fractional:

                   > ls -1            > ls -1v
                   abc-1.007.tgz      abc-1.007.tgz
                   abc-1.012b.tgz     abc-1.01a.tgz
                   abc-1.01a.tgz      abc-1.012b.tgz

              (New in fileutils-4.0.)

       -w, --width cols
              Assume  the  screen  is  cols  columns  wide.   The
              default is taken from the terminal driver if possi-
              ble;  otherwise the environment variable COLUMNS is
              used if it is set; otherwise the default is 80.




GNU fileutils 4.0         November 1998                         5





LS(1)                                                       LS(1)


       -x, --format=across, --format=horizontal
              List the files in columns, sorted horizontally.

       -A, --almost-all
              List all files in directories, except for  `.'  and
              `..'.

       -B, --ignore-backups
              Do  not  list  files that end with `~', unless they
              are given on the command line.

       -C, --format=vertical
              List files in columns, sorted vertically.  This  is
              the default if standard output is a terminal. It is
              always the default for dir and d.

       -D, --dired
              With the long listing (-l) format, print  an  addi-
              tional line after the main output:
              //DIRED// BEG1 END1 BEG2 END2 ...

              The  BEGn  and  ENDn  are  unsigned  integers which
              record the byte position of the beginning  and  end
              of each file name in the output. This makes it easy
              for Emacs to find the names, even when they contain
              unusual  characters such as space or newline, with-
              out fancy searching.

              If directories are being listed  recursively  (-R),
              output a similar line after each subdirectory:
              //SUBDIRED// BEG1 END1 ...

       -F, --classify, --indicator-style=classify
              Append a character to each file name indicating the
              file type.  For regular files that are  executable,
              append a `*'.  The file type indicators are `/' for
              directories, `@' for symbolic links, `|' for FIFOs,
              `=' for sockets, and nothing for regular files.

       -G, --no-group
              Inhibit display of group information in a long for-
              mat directory listing.

       -H, --si
              Do the same as for -h,  but  use  the  official  SI
              units (with powers of 1000 instead of 1024, so that
              M stands for 1000000 instead of 1048576).  (New  in
              fileutils-4.0.)

       -I, --ignore=pattern
              Do  not list files whose names match the shell pat-
              tern pattern (not regular expression)  unless  they
              are given on the command line.  As in the shell, an
              initial `.' in a filename does not match a wildcard



GNU fileutils 4.0         November 1998                         6





LS(1)                                                       LS(1)


              at the start of pattern.

       -L, --dereference
              List  the  file  information  corresponding  to the
              referrents of symbolic links rather for  the  links
              themselves.

       -N, --literal
              Do not quote file names.

       -Q, --quote-name, --quoting-style=c
              Enclose  file names in double quotes and quote non-
              graphic characters as in C.

       -R, --recursive
              List the contents of all directories recursively.

       -S, --sort=size
              Sort directory contents by  file  size  instead  of
              alphabetically,   with  the  largest  files  listed
              first.

       -T, --tabsize cols
              Assume that each tabstop is cols columns wide.  The
              default  is 8 and can be overridden by the environ-
              ment variable TABSIZE when POSIXLY_CORRECT  is  not
              set.   ls  uses  tabs where possible in the output,
              for efficiency. If cols is zero, do not use tabs at
              all.

       -U, --sort=none
              Do  not sort directory contents; list them in what-
              ever order they are stored on the disk.  (The  dif-
              ference  between  -U  and  -f  is  that  the former
              doesn't disable or enable options.) This  is  espe-
              cially  useful when listing very large directories,
              since not  doing  any  sorting  can  be  noticeably
              faster.

       -X, --sort=extension
              Sort  directory  contents  alphabetically  by  file
              extension (characters after the  last  `.');  files
              with no extension are sorted first.

       --block-size=size
              Print sizes in blocks of size bytes.  (New in file-
              utils-4.0.)

       --color[=when]
              Specify whether to  use  color  for  distinguishing
              file types.  Colors are specified using the LS_COL-
              ORS environment variable.  For information  on  how
              to  set  this variable, see dircolors(1).  when may
              be omitted, or one of:



GNU fileutils 4.0         November 1998                         7





LS(1)                                                       LS(1)


              none   Do  not  use  color  at  all.  This  is  the
                     default.

              auto   Only  use color if standard output is a ter-
                     minal.

              always Always use color.  Specifying --color and no
                     when is equivalent to --color=always.

       --full-time
              List  times in full, rather than using the standard
              abbreviation heuristics. The format is the same  as
              date(1)'s  default;  it's  not  possible  to change
              this, but you can extract out the date string  with
              cut(1) and then pass the result to `date -d'.

              This   is  most  useful  because  the  time  output
              includes the seconds.  (Unix filesystems store file
              timestamps  only  to  the  nearest  second, so this
              option shows all the information  there  is.)   For
              example,  this  can  help  when you have a Makefile
              that is not regenerating files properly.

       --quoting-style=word
              Use style word to quote  output  names.   The  word
              should be one of the following:

              literal
                     Output  names  as-is.   This  is the default
                     behavior of ls.

              shell  Quote names for the shell  if  they  contain
                     shell  metacharacters or would cause ambigu-
                     ous output.

              shell-always
                     Quote names for  the  shell,  even  if  they
                     would normally not require quoting.

              c      Quote names as for a C language string; this
                     is the same as the -Q option.

              escape Quote as with c except omit the  surrounding
                     double-quote characters; this is the same as
                     the -b option.

              A default value for this option  can  be  specified
              with  the environment variable QUOTING_STYLE.  (See
              ENVIRONMENT below.)

       --show-control-chars
              Print nongraphic characters as-is  in  file  names.
              This is the default unless the output is a terminal
              and the program is ls.



GNU fileutils 4.0         November 1998                         8





LS(1)                                                       LS(1)



GNU STANDARD OPTIONS

       --help Print a usage message on standard output  and  exit
              successfully.

       --version
              Print  version information on standard output, then
              exit successfully.

       --     Terminate option list.


ENVIRONMENT

       The variable  POSIXLY_CORRECT  determines  the  choice  of
       unit.   If it is not set, then the variable TABSIZE deter-
       mines the number of chars  per  tab  stop.   The  variable
       COLUMNS  (when it contains the representation of a decimal
       integer) determines the output column width (for use  with
       the  -C  option).  Filenames must not be truncated to make
       them fit a multi-column output.

       The variables LANG, LC_ALL, LC_COLLATE, LC_CTYPE,  LC_MES-
       SAGES and LC_TIME have the usual meaning.  The variable TZ
       gives the time zone for time strings written by  ls.   The
       variable LS_COLORS is used to specify the colors used.

       The  variable QUOTING_STYLE is used to specify the default
       value  for  the  --quoting-style  option.   It   currently
       defaults  to  literal, though the authors have warned that
       this default may change to shell in some future version of
       ls.


BUGS

       On  BSD systems, the -s option reports sizes that are half
       the correct values for files that are NFS-mounted from HP-
       UX  systems.  On  HP-UX systems, ls reports sizes that are
       twice the correct values for files  that  are  NFS-mounted
       from  BSD systems. This is due to a flaw in HP-UX; it also
       affects the HP-UX ls program.


CONFORMING TO

       POSIX 1003.2


SEE ALSO

       dircolors(1)


NOTES

       This page describes ls as found in the fileutils-4.0 pack-
       age; other versions may differ slightly.  Mail corrections
       and additions to aeb@cwi.nl.  Report bugs in  the  program
       to fileutils-bugs@gnu.ai.mit.edu.








GNU fileutils 4.0         November 1998                         9