About Us Documentation

Contact Site Map



Go to the previous, next chapter.

Directory listing

This chapter describes the ls command and its variants dir and vdir, which list information about files.

ls: List directory contents

The ls program lists information about files (of any type, including directories). Options and file arguments can be intermixed arbitrarily, as usual.

For non-option command-line arguments that are directories, by default ls lists the contents of directories, not recursively, and omitting files with names beginning with .. For other non-option arguments, by default ls lists just the filename. If no non-option arguments are specified, ls lists the contents of the current directory.

By default, the output is sorted alphabetically. If standard output is a terminal, the output is in columns (sorted vertically); otherwise, they are listed one per line.

Because ls is such a fundamental program, it has accumulated many options over the years. They are described in the subsections below; within each section, options are listed alphabetically (ignoring case). The division of options into the subsections is not absolute, since some options affect more than one aspect of ls's operation.

-g Also, the -g option is accepted but ignored, for compatibility with Unix. Also see section Common options.

Which files are listed

These options determine which files ls lists information for. By default, any files and the contents of any directories on the command line are shown.

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

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

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

-d --directory -d --directory List just the names of directories, as with other types of files, rather than listing their contents.

-I --ignore -I --ignore=pattern Do not list files whose names match the shell pattern (not regular expression) pattern 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 -L --dereference List the files linked to by symbolic links instead of listing the contents of the links.

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

What information is listed

These options affect the information that ls displays. By default, only filenames are shown.

-D --dired -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 filename 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 ...

-G --no-group -G --no-group Inhibit display of group information in a long format directory listing. (This is the default in some non-GNU versions of ls, so we provide this option for compatibility.)

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

-l --format=long --format=verbose -l --format long ls format verbose ls format 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 (by default, the modification time). For files with a time 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 bug.

This output format is the default for the GNU v and vdir programs.

-s --size -s --size Print the size of each file in 1024-byte blocks to the left of the filename. If the environment variable POSIXLY_CORRECT is set, 512-byte blocks are used instead, unless the -k option is given (see section General output formatting).

For files that are NFS-mounted from an HP-UX system to a BSD system, this option reports sizes that are half the correct values. On HP-UX systems, it 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.

Sorting the output

These options change the order in which ls sorts the information it outputs. By default, sorting is done by character code (e.g., ASCII order).

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

-f -f Primarily, like -U---do not sort; list the files in whatever order they are stored in the directory. But also enable -a (list all files) and disable -l and -s (if they were specified before the -f).

-r --reverse -r --reverse Reverse whatever the sorting method is---e.g., list files in reverse alphabetical order, youngest first, smallest first, or whatever.

-S --sort=size -S --sort size of files, sorting files by Sort by file size, largest first.

-t --sort=time -t --sort modification time, sorting files by Sort by modification time (the mtime in the inode), newest first.

-u --time=atime --time=access --time=use -u --time atime, sorting files by access time, sorting files by use time, sorting files by Sort by access time (the atime in the inode). If the long listing format is being used, print the last access time.

-U --sort=none -U --sort none, sorting option for ls Do not sort; list the files in whatever order they are stored in the directory. (Do not do any of the other unrelated things that -f does.) This is especially useful when listing very large directories, since not doing any sorting can be noticeably faster.

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

General output formatting

These options affect the appearance of the overall output.

-1 --format=single-column -1 --format single-column output of files List one file per line. This is the default for ls when standard output is not a terminal.

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

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

--full-time --full-time List times in full, rather than using the standard abbreviation heuristics. The format is the same as date's default; it's not possible to change this, but you can extract out the date string with cut and then pass the result to date -d. @xref{date invocation} invocation, , sh-utils, Shell utilities}.

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.

-k --kilobytes -k --kilobytes If file sizes are being listed, print them in kilobytes. This overrides the environment variable POSIXLY_CORRECT.

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

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

-p Append a character to each filename indicating the file type. This is like -F, except that executables are not marked.

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

-T --tabsize=cols -T --tabsize Assume that each tabstop is cols columns wide. The default is 8. ls uses tabs where possible in the output, for efficiency.

-w --width=cols -w --width Assume the screen is cols columns wide. The default is taken from the terminal settings if possible; otherwise the environment variable COLUMNS is used if it is set; otherwise the default is 80.

Formatting the filenames

These options change how filenames themselves are printed.

-b --escape -b --escape Quote nongraphic characters in filenames using alphabetic and octal backslash sequences like those used in C.

-N --literal -N --literal Do not quote filenames.

-q --hide-control-chars -q --hide-control-chars Print question marks instead of nongraphic characters in filenames. This is the default.

-Q --quote-name -Q --quote-name Enclose filenames in double quotes and quote nongraphic characters as in C.

dir: Briefly list directory contents

The dir program (also installed as d) is equivalent to ls -C; that is, files are by default always listed in columns, sorted vertically.

vdir: Verbosely list directory contents

The vdir program (also installed v)is equivalent to ls -l; that is, files are by default listed in long format.



Email addresses listed on this site may  NOT be used for unsolicited commercial email.

Ready-to-Run Software, Inc Privacy Statement

Portions (c)Copyright, 1996-2005 by Ready-to-Run Software, Inc
(All rights reserved.)
212 Cedar Cove
Lansing, NY 14882
Phone: 607 533 UNIX (8649)
Fax: 607 533 4002