NAME
ls, dir, vdir - list directory contents
SYNOPSIS
ls [options] [file...]
POSIX options: [-CFRacdilqrtu1]
GNU options (shortest form): [-1abcdfgiklmnopqrstux-
ABCDFGLNQRSUX] [-w cols] [-T cols] [-I pattern]
[--full-time]
[--format={long,verbose,commas,across,vertical,single-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 con-
tained 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
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 mul-
ticolumn 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 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. By default, the timestamp shown is
that of the last modification; the options -c and
8 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 ques-
tion 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.
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'; that is,
files are by default listed in columns, sorted vertically.
vdir (also installed as v) is equivalent to `ls -l'; 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 when
standard output is not a terminal.
-a, --all
List all files in directories, including all files that
start with `.'.
-b, --escape
Quote nongraphic characters in file names using alpha-
betic and octal backslash sequences like those used in
C.
-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 whatever
order they are stored on the disk. Also enables -a and
disables -l, --color, and -s if they were specified
before the -f.
-g Ignored; for Unix compatibility.
-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 modifica-
tion 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 argu-
ably 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 corresponding
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-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 Append a character to each file name indicating the
file type. This is like -F except that executables
aren't marked.
-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.
-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 output. This makes it easy for Emacs to
find the names, even when they contain unusual charac-
ters such as space or newline, without fancy searching.
If directories are being listed recursively (-R), out-
put a similar line after each subdirectory:
//SUBDIRED// BEG1 END1 ...
-F, --classify, --file-type
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.
-I, --ignorepattern
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.
-L, --dereference
List the file information corresponding to the refer-
rents of symbolic links rather for the links them-
selves.
-N, --literal
Do not quote file names.
-Q, --quote-name
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 alpha-
betically, with the largest files listed first.
-T, --tabsize cols
Assume that each tabstop is cols columns wide. The
default is 8. ls uses tabs where possible in the out-
put, 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 -Uand-f is that the later 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 exten-
sion (characters after the last `.'); files with no
extension are sorted first.
--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 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.
GNU STANDARD OPTIONS
--help
Print a usage message on standard output and exit suc-
cessfully.
--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 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.
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-3.16 pack-
age; other versions may differ slightly. Mail corrections
and additions to aeb@cwi.nl and aw@mail1.bet1.puv.fi and
ragnar@lightside.ddns.org . Report bugs in the program to
fileutils-bugs@gnu.ai.mit.edu.