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): [-1abcdfghiklmnopqrstuvwxABCDFGHLNQRSUX]
[-w cols][-T cols][-I pattern][--full-time][--show-control-chars]
[--block-size=size][--format={long,verbose,commas,across,vertical,sin-
gle-column}][--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 arguments, 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 directo-
ries 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 current 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 multicolumn 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.
POSIXOPTIONS
-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 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 modifica-
tion; 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 modification time for
sorting (with -t) or listing (with -l).
-1 For single-column output.
-- Terminate option list.
GNUDETAILS
If standard output is a terminal, the output is in columns (sorted ver-
tically).
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.
GNUOPTIONS
-1,--format=single-column
List one file per line. This is the default for 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 dou-
ble-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 mod-
ification time.
-d,--directory
List names of directories like other files, rather than listing
their contents.
-f Do not sort directory contents; list them in whatever 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 kilobytes.
-l,--format=long,--format=verbose
In addition to the name of each file, print the file type, per-
missions, 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 timestamp contains
the year instead of the time of day.
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 com-
puted counts each hard link separately; this is arguably a defi-
ciency.
The permissions listed are similar to symbolic mode specifica-
tions but ls combines multiple bits into the third character of
each set of permissions
s If the setuid or setgid bit and the corresponding exe-
cutable 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-executable 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 characters in file
names. This is the default.
-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 compar-
isons are made on a character-by-character basis. The version
sort addresses this problem, and is especially useful when
browsing directories that contain many files with indices/ver-
sion 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 possible; otherwise the environment
variable COLUMNS is used if it is set; otherwise the default is
80.
-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 additional 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 out-
put. 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 simi-
lar 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 format directory
listing.
-H,--si
Do the same as for -h, but use the official SI units (with pow-
ers 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 pattern 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 at the start of pattern. For simple-minded
root-kits: add LS_OPTIONS="$LS_OPTIONS -I mystuff" in /etc/pro-
file or so, to hide your directories.
-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 nongraphic charac-
ters 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 environment 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 whatever order they
are stored on the disk. (The difference between -U and -f is
that the former doesn't disable or enable options.) This is
especially 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 (char-
acters after the last '.'); files with no extension are sorted
first.
--block-size=size
Print sizes in blocks of size bytes. (New in fileutils-4.0.)
--color[=when]
Specify whether to use color for distinguishing file types.
Colors are specified using the LS_COLORS environment variable.
For information on how to set this variable, see dircolors(1).
when may be omitted, or one of:
none Do not use color at all. This is the default.
auto Only use color if standard output is a terminal.
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 sec-
onds. (Unix filesystems store file timestamps only to the near-
est 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 metachar-
acters or would cause ambiguous 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 envi-
ronment 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.
GNUSTANDARDOPTIONS
--help Print a usage message on standard output and exit successfully.
--version
Print version information on standard output, then exit success-
fully.
-- Terminate option list.
ENVIRONMENT
The variable POSIXLY_CORRECT determines the choice of unit. If it is
not set, then the variable TABSIZE determines 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_MESSAGES 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 LS_OPTIONS gives default
options.
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 sys-
tems, 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.
CONFORMINGTO
POSIX 1003.2
SEEALSO
dircolors(1)
NOTES
This page describes ls as found in the fileutils-4.0 package; other
versions may differ slightly. Mail corrections and additions to
aeb
cwi.nl. Report bugs in the program to fileutils-
bugsgnu.edu.
GNU fileutils 4.0 1998-11 LS(1)
Take our 
