ls

List directory contents (POSIX)

Syntax:

ls [-1CFRacdilqrstu] [-DLSbfghnopv] [file...]

Runs on:

QNX Neutrino, Microsoft Windows

Options:

-1

(“One”) Force output to be one entry per line.

-a

List all files, including hidden ones i.e., those that start with a dot (.). By default, these entries aren't listed.

-C

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

-c

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

-d

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

-F

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

Character	Meaning
`/`	Directories
`*`	Executable files
`\|`	FIFOs (named pipes)
`#`	Named special files (QNX Neutrino extension)
`@`	Symbolic links (QNX Neutrino extension)

-i

For each file, print the file's serial number.

-l

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

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

To see a header above the columns, use the -h option.

Note that the initial field (e.g., “drwxrwxrwx”) describes the filetype and permissions (see below).

-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.

Note: QNX Neutrino currently supports only the POSIX (i.e., C) locale.

-R

Recursively list all subdirectories encountered.

Note: If you're using Qnet, doing something like ls -R /net can take a very long time because it recursively lists all the directories on all the machines on your network.

-r

Reverse the order of the sort to get either oldest files first (if files are being sorted by time) or reverse collating sequence.

-s

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

-t

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

-u

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

file

The pathname of a file to be listed. If the file specified isn't found, a diagnostic message is output on standard error. Files are displayed in command-line sequence.

QNX Neutrino extensions:

-b: Use the size of the file for sorting and printing. Sort in descending order.
-D: Display directories only.
-f: Don't sort the output (same as -S).
-g: List in long format, as in ls -l, but don't show owner (group is displayed).
-h: Display a header for the -l (“el”) and -n options.
-L: Resolve symbolic links instead of showing them.
-n: Same as -l (“el”), except display group ID and user ID numbers instead of names.
-o: List in long format, as in ls -l, but don't show group (owner is displayed).
-p: Display a list of relative pathnames for all nondirectory files. The files are listed one to a line. This option allows you to pass full pathnames of files to programs.
-S: Don't sort the output. This option is useful for determining the order in which entries are found in a given directory.
-v: List directories first.

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 nondirectories 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 is “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).

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

When displaying a timestamp for a file, ls displays 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 displays the date and year.

If you use the -l (“el”) or -s option—or the -n, -g, or -o options, which imply them—and you list a directory, the output includes the total number of 512-byte blocks that the directory occupies. This total doesn't include the space occupied by any subdirectories. For example:

$ ls -l some_dir
total 28
-rwxrwxr-x  1 conrad    techies        1515 Jan 09  2014 file1
-rwxrwxr-x  1 conrad    techies         354 Apr 08 14:37 file2.txt
-rwxrwxr-x  1 conrad    techies         321 Dec 23  2012 file3.txt
-rwxrwxr-x  1 conrad    techies        6767 May 31  2013 file4

Filetype and permissions

In the long format (-l option), the initial field (e.g., “drwxrwxrwx”) describes the filetype and permissions. The first character represents the filetype; the next nine represent the read/write/execute permissions for the owner, group, and other classes.

If there's a plus sign (+) after the permissions, the file also has an access control list. For more information, see getfacl and setfacl.

In the first position, the following characters are used to indicate the filetype:

Character	Meaning
`-`	Regular file
`b`	Block special file
`c`	Character special file
`d`	Directory
`l`	Symbolic link
`n`	Named special file
`p`	FIFO (pipe)
`s`	Unix domain socket

The next nine characters represent the owner, group, and other permissions; each class has a three-character field. For each class, the characters and the first two positions are as follows:

Position	Character	Meaning
First	`r` or `-`	The file is readable or not
Second	`w` or `-`	The file is writable or not

For the third position, several characters are possible:

Character	Meaning
`S`	If a file, it isn't executable and is setuid (if in the owner field) or setgid (if in the group field). If a directory, it isn't searchable. All files within that directory inherit the permissions of the directory, not of the creator of the files.
`s`	The file is executable or the directory is searchable. The user/group ID modes are set, and the directory-driven inheritance is as with `S`.
`T`	Sticky bit is set and `x` isn't set.
`t`	Sticky bit is set and `x` is set.
`x`	The file is executable or the directory is searchable.
`-`	None of the attributes (`S`, `s`, `T`, `t`, or `x`) applies.

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.