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

---

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

---

-R

Recursively list all subdirectories encountered.

---

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 /etc/rc.d
total 28
-rwxrwxr-x  1 root      root           1515 Apr 30  2001 rc.devices
-rwxrwxr-x  1 root      root            354 Apr 08 14:37 rc.local
-rwxrwxr-x  1 root      root            321 Dec 23  2004 rc.local~
-rwxrwxr-x  1 root      root           6767 May 31  2001 rc.setup-info
-rwxrwxr-x  1 root      root           2993 May 07  2002 rc.setup-once
-rwxrwxr-x  1 root      root           1271 Apr 21  2002 rc.sysinit

Filetype and permissions

In the long format (-l option), the 10-character field (e.g.“drwxrwxrwx”) describes the filetype and permissions. The first character represents the filetype; the rest of the characters represent the read/write/executable permissions for the owner, group, and other classes.

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

The remaining 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:

For the third position, several characters are possible:

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:

chmod, find, which

Working with Files in the Neutrino User's Guide