ls

List directory contents (POSIX)

Syntax:

ls [-acCdFilqrRstu1] [-bDfghnopSvx] [file...]

Options:

-1

("one") Force output to be one entry per line.

-a

List all files, including those which start with a dot (.). By default, these entries aren't listed.

-b

(QNX extension) Use the size of the file for sorting and printing. Sort in descending order.

-c

For sorting (-t) or printing (-l ("el")), use time of last change to the file's status information instead of time of last modification of the file itself.

-C

Display multiple-column output, with entries sorted down the columns according to the collating sequence.

-d

Treat directories like files -- give information on the directory itself, not on the files or subdirectories it contains.

-D

(QNX extension) Display directories only.

-f

(QNX extension) Don't sort the output (same as -S).

-F

Indicate the filetype by adding an extra character after some pathnames, as follows:

Character	Meaning
/	for directories
*	for executable files
|	for FIFOs (named pipes)
@	for named special files (QNX extension)

-g

(QNX extension) List in long format, as in ls -l ("el"), but don't show owner (group is displayed).

-h

(QNX extension) Display a header for the -l ("el") -x and -n options.

-i

For each file, print the file's serial number (inode).

-l

("el") List in long format. This option provides most of the relevant file information such as permissions, link count, owner/group of the file, as well as the size, date, and name of the file, as follows:

drwxrwxrwx  7 root     techies   22528 Jan 17 15:38 Csrc
-rw-rw-rw-  1 barney   rubble       22 Feb 14 13:41 rock
-rwxrwxrwx  1 root     techies      22 Feb 14 13:41 exec
-rw-rw-rw-  1 fred     fstone       22 Feb 14 13:41 fred
drwxrwxrwx  2 root     techies   23040 Feb 12 10:56 libt
drwxrwxrwx  2 root     root       2048 Sep 28 06:39 util

Note that the first character preceding the permissions denotes the file type, as follows:

Character	File type
-	Regular
b	Block special
c	Character special
d	Directory
p	FIFO
l	Symbolic link
n	Named special
s	Socket special

-n

(QNX extension) Same as -l ("el"), except display group ID and user ID numbers instead of names.

-o

(QNX extension) List in long format, as in ls -l ("el"), but don't show group (owner is displayed).

-p

(QNX extension) Display non-directory files only, as a list of pathnames relative to the original file specified on the command line, or the current directory (.) if no file parameters were supplied. This option allows you to pass full pathnames of files to programs (i.e. the portion of the path supplied on the command line will not be stripped off from the filenames in ls's output).

-q

Force filename characters that aren't included in the character set classification in the current locale to be displayed as a question mark (?). This is the default if output is to a terminal.

-r

Reverse the order of the sort. When sorting alphabetically (default), this will result in reverse alphabetical order. When sorting by time (-t), files will be listed oldest to newest. When sorting by size (-b), files will be listed smallest to largest.

-R

Recursively list all subdirectories encountered.

-s

Display the size of the file in 512-byte blocks.

-S

(QNX extension) Don't sort the output. This option is useful for determining the order in which entries are found in a given directory.

-t

Sort by time modified (most recently modified first) before sorting the files by the collating sequence.

-u

For sorting (-t) or printing (-l ("el")), use time of last access (i.e. last use), instead of time of last modification of the file.

-v

(QNX extension) List directories first.

-x

(QNX extension) Display extent information for a file or directory. Extent information describes how a file is segmented on disk. This option displays information similar to the following example:

     Size xtnts xblk_1  xsize   xblk status Filename
    22528     8 000686  4     000C1A  ----  Csrc 
       22     1 00adc3  1     000000  --I-  rock  
       22     1 00ACD8  1     000000  ----  exec
       22     1 00ADC2  1     000000  -B--  results
    23040    10 004A55  4     005A91  ----  libtests
     2048     1 0013EB  8     000000  ---G  logfile

Note that the text descriptions of the columns are displayed only if the -h option is used. The meaning of the fields is as follows:

Size

File size, in bytes.

xtnts

Number of extents in the file.

xblk_1

The block address (hex) of the first extent in the file.

xsize

The number of blocks in the first extent of the file.

xblk

The block address (hex) of the first extent block for the file. If there are no extent blocks (i.e. the file only has zero or one extent), this will be zero.

status

A subset of the status bits related to the file. If a bit is set, the corresponding letter will appear. If not set, a dash (-) will appear instead. The bits shown are:

Bit:	Represents:	Meaning:
B	_FILE_BUSY	Indicates that the file has been grown or truncated but the inode has not been updated on disk.
I	_FILE_INODE	The directory entry does not contain an embedded inode. Inode information for this file is stored in the .inodes file.
C	_FSYS_CLEAN	Valid for the filesystem root only; indicates that there are no busy files.
G	_FILE_GROWN	Pregrown file. Indicates that file space has been preallocated in excess of the space currently used by the file in anticipation of future growth.

Filename

The name of the file. If -F is supplied, and the filename will have the file type character appended (e.g. / for directories, * for executables etc.).

file

The pathname of a file to be listed. If the file specified isn't found, a diagnostic message is output on standard error.

Description:

For each file you name that isn't a directory, ls displays the file's name as well as any information requested on the file.

For each directory you name, ls displays the names of files contained within that directory, as well as any information requested on the files. The -d option overrides this behavior and makes ls display information on the directory itself, rather than on its contents.

If you specify more than one file, ls displays files that aren't directories first. Directories and non-directories are sorted separately.

If you don't specify a file, ls displays the contents of the current directory.

Specifying more than one of the -C, -l ("el"), and -1 ("one") options isn't considered an error. The last option specified determines the output format.

In many environments, the ls command will be "aliased" to either ls -C or ls -CF, the two most common ls display formats. Unless the POSIX_STRICT environment variable is set, ls defaults to the multi-column output (-C option) when its standard output is a tty. When the standard output is not a tty, it defaults to single-column output.

The -p option is useful for passing a list of all non-directory filenames, one filename per line, to other programs. The filenames include the full pathnames.

When displaying a timestamp for a file, ls will display the date and time, unless the file is older or newer than the current date by six months (a "month" is defined as 30 days). Otherwise, ls will display the date and year.

Environment variables:

COLUMNS

If this variable contains a string representing a decimal integer, it indicates the user's preferred column position width for displaying multiple-column output. The ls utility calculates how many pathname text columns to display (see -C) based on the width provided. If COLUMNS isn't set or is invalid, the number of columns displayed is determined by the type of output device.

POSIX_STRICT

Interpret options according to POSIX specifications.

TZ

Determines the time zone for date and time displays.

Exit status:

0

All files were listed successfully.

>0

An error occurred.

See also:

find