|
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,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 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 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.
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.
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 modification 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 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 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, 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
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
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 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, --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 comparisons 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/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 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 characters
such as space or newline, without 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 format
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 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/profile 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 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 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
(characters 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 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
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 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 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 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 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 package; 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.
|
|
jamesthornton.com>