ls

list file and directory names and attributes 

Command


SYNOPSIS

ls [-AabCcdFfghikLlmnopqRrstux1] [-timeout seconds] [-X attr] [pathname...]


DESCRIPTION

ls lists files and directories. If the pathname is a file, ls displays information on the file according to the requested options. If the pathname is a directory, ls displays information on the files and subdirectories therein. You may obtain information on a directory itself using the -d option.

If you do not specify any options, ls displays only the file name(s). When ls sends output to a pipe or a file, it writes one name per line; when it sends output to the terminal, it uses the -C (multi-column) format.

Options

-A 

lists all entries including those starting with periods (.), but excluding any . or .. entries.

-a 

lists all entries including those starting with a period (.).

-b 

displays non-printable characters as octal bytes with the form \ooo.

-C 

puts output into columns, sorted vertically; this is the default output format to the terminal.

-c 

uses the creation time of the file for sorting (-t) or displaying (-l).

-d 

does not display the contents of named directories, but show information on the directories themselves.

-F 

puts a / after each directory name, a * after every executable file, a | after every FIFO file, a @ after every symbolic link and a = after every socket.

Note:

Windows systems do not support FIFO files or sockets (as files) and consider all files that are not directories or symbolic links to be executable files. This option of the ls utility labels the files and directories display accordingly.

-f 

enables the -a option and disables the -C, -g, -l, -n, -o, -r, -s, and -t options. For each argument that is a directory, all directory entries are listed in the same order they are retrieved from the system (POSIX-compliant and UNIX systems only).

-g 

displays only the group ID numbers (on XP/2003/Vista/7/2008/8/2012, POSIX-compliant and UNIX systems).

-h 

displays file sizes using more human-friendly units. Units used are:

B       Bytes
KB      Kilobytes
MB      Megabytes
GB      Gigabytes
TB      Terabytes
PB      Petabytes
EB      Exabytes

When this option is specified, each file size is displayed using the most appropriate unit and is rounded to two decimal places.

-i 

displays inode numbers along with file names (only on systems that support inode numbers, such as POSIX-compliant and UNIX systems).

-k 

displays size in kilobytes instead of blocks when specified with the -s option. If the -s option is not specified, this option has no effect.

-L 

follows symbolic links.

Note:

Symbolic links are only available on XP/2003/Vista/7/2008/8/2012 systems with the NTFS file system.

-l 

displays permissions, links, owner, group, size, time, name; see Long Output Format.

-m 

displays names in single line, with commas separating names.

-n 

displays user ID and group IDs as numbers instead of names.

-o 

displays only the user ID of owner (POSIX-compliant and UNIX systems only).

-p 

puts / after directory names.

-q 

displays non-printable characters as ?.

-R 

lists subdirectories recursively.

-r 

sorts in reverse of usual order; you can combine this with other options that sort the list.

-s 

displays size in blocks (after the inode number, but before other information). If the -k option is also specified, the size is displayed in kilobytes instead.

-t 

sorts entries by time. By default, this option sorts the output by the modification times of files. You can change this with the -c and -u options.

-timeout seconds 

specifies the number of seconds that ls has to complete the operation before timing out and issuing an error. seconds is given in seconds.

-u 

uses the last access time for sorting (-t) or displaying (-l).

-X attr 

displays extended security attributes under Windows. This option turns on the -l (long listing) option. The attr argument is a string containing some of these characters:

Character  Meaning 
A file attributes in verbose format
a file attributes in terse format
D verbose file Discretionary Access Control Entries (XP/2003/Vista/7/2008/8/2012 only)
d terse file Discretionary Access Control Entries (XP/2003/Vista/7/2008/8/2012 only)

If both A and a or both D and d are in attr, ls uses the last one given on the command line. See Extended Attribute Descriptions.

-x 

puts output into columns sorted across the rows.

-1 

forces single column output.

Note:

When you specify options that are mutually exclusive (for example, -c and -u), the option that appears last on the command line is used.

Long Output Format

The output from ls -l summarizes all the most important information about the file on one line. If the specified pathname is a directory, ls displays information on every file in that directory (one file per line). It precedes this list with a status line that indicates the total number of file system blocks (512 byte units) occupied by the files in that directory. Here is a sample of the output along with an explanation.

-rw-rw-rw- 1 root   dir 104 Dec 25 19:32 file

The first character identifies the file type:

-    Regular file
b    Block special file
c    Character special file
d    Directory
l    Symbolic link
n    Network file
p    FIFO
s    Socket

The next nine characters are in three groups of three; they describe the permissions on the file. The first group of three describes owner permissions; the second describes group permissions; the third describes other (or world) permissions. Because Windows systems do not support group and other permissions, these are copies of the owner's permissions. Characters that may appear are:

r    Permission to read file
w    Permission to write to file
x    Permission to execute file
a    Archive bit is on (file has not been backed up)
c    Compressed file
s    System file
h    Hidden file
t    Temporary file

On Windows systems, most of the permissions shown are artificial, with no real meaning. The w bit is set according to the ReadOnly attribute, and the rx bits are always set on.

You can change some permissions with the chmod command.

After the permissions comes the number of links to the file.

Next comes the name of the owner of the file or directory. On file systems that don't support XP/2003/Vista/7/2008/8/2012 security, the owner name cannot be determined and the owner ID number is displayed instead. Under XP/2003/Vista/7/2008/8/2012 the name of the owner of a file is displayed if the file's SIDs can be obtained and if these SIDs have an associated name in the SAM database. If the file has a SID associated with it, but the name of the SID cannot be determined, then the value of the SID is displayed. (This can happen when the current user is not in the domain that was used when the file was created.) If the file does not have a SID (for example, if it is on a non-NTFS file system), or if the file security information cannot be accessed because the file is locked by another process, then the user name appears as <unavail>.

Note:

When a listed file is owned by the local computer, the owner is displayed as computer_name\ where computer_name is the name of the local computer.

Then comes the name of the group that owns the file or directory. On Windows systems, the same rules are followed for the group name as for the owner name.

Following this is the size of the file, expressed in bytes.

After this comes a date and time. For a file, this is the time that the file was last changed; for a directory, it is the time that the directory was created. The -c and -u options can change which time value is used. If the date is more than six months old or if the date is in the future, the year is shown instead of the time.

The last item on the line is the name of the file or directory.

Extended Attribute Descriptions

On XP/2003/Vista/7/2008/8/2012 systems, ls supports the -X option, which displays the extended attributes of the file(s). This description is shown beneath the long output format already described.

For ls -X A or ls -X a, the display format is:

Attributes: attributelist

where attributelist is a comma-separated list of one or more of:

Verbose Terse 
Archive A
Compressed C
Directory D
Encrypted E
Hidden H
Normal N
Offline O
ReparsePoint R
ReadOnly RO
Sparse SP
System S
Temporary T

For ls -X D or ls -X d, the display format is:

ACE: perm usergrpname ace_flags accessmode

where:

perm 

is one of Allow or Deny.

usergrpname 

is the user or group name as taken from the XP/2003/Vista/7/2008/8/2012 Security Access Manager registry. Any spaces embedded in the name are replaced by + characters.

ace_flags 

is a comma-separated list of the flags for Discretionary Access Control Entities:

Verbose Terse 
ContainerInheritAce CIA
FailedAccessAceFlag FAAF
InheritOnlyAce IOA
NoPropagateInheritAce NPIA
ObjectInheritAce OIA
SuccessAccessAceFlag SAAF

If no flags are set, ls displays a single -. ACE stands for Access Control Entry; for more information, see your XP/2003/Vista/7/2008/8/2012 system documentation.

accessmode 

is the set of access permissions (if Allow is displayed) or restrictions (if Deny is displayed) for this ACE. These can be any or none of the following:

Verbose Terse  Note
Read R Read file data or list directory entries
Write W Write file data or create new file in directory
eXecute X Execute a file or traverse a directory
Append A Append data to a file or add subdirectory
DeleteChild DC For a directory, delete entries in directory
ReadEa RE Read extended attributes
WriteEa WE Write extended attributes
ReadAttr RA Read attributes
WriteAttr WA Write attributes
Delete D Delete access
ReadControl RC Read access to the owner, group, and discretionary access control list (ACL) of the security descriptor
WriteDac WD Write access to the owner, group, and discretionary access control list (ACL) of the security descriptor
takeOwnership O Write access to the owner
Synchronize S Synchronize access


ENVIRONMENT VARIABLES

COLUMNS 

contains the terminal width in columns. ls uses this value to determine the number of output columns to write using the -C option.

TK_NTLINKS_OFF 

MKS Toolkit supports hard links under XP/2003/Vista/7/2008/8/2012 on NTFS file systems. There is a slight loss of performance for this support. If you do not require hard link support, you should set and export the environment variable TK_NTLINKS_OFF to disable this support.

TK_NTSECURITYINFO_OFF 

MKS Toolkit supports XP/2003/Vista/7/2008/8/2012 security information on NTFS file systems. There is a slight loss of performance for this support. If you do not require any security information, you should set and export the environment variable TK_NTSECURITYINFO_OFF to disable this feature.

TK_NTSECURITYINFO_SID_TERSE 

Under XP/2003/Vista/7/2008/8/2012, files having an associated SID, whose name cannot be determined, display the value of the SID instead. SID values are usually very large. You should set and export the TK_NTSECURITYINFO_SID_TERSE which causes all SID values to be shortened by replacing all the subauthority values, except the last one, with the string -...-.

TK_USE_CURRENT_LOCALE 

When set, this environment variable causes months and days of the week to be displayed as defined in the current locale. By default, PTC MKS Toolkit utilities display months and days of the week in English.

TZ 

contains the time zone to be used when displaying date and time strings. On XP/2003/Vista/7/2008/8/2012, PTC MKS Toolkit uses the built-in timezone support, and you should not set the TZ environment variable.


DIAGNOSTICS

Possible exit status values are:

0 

Successful completion.

1 

Failure due to any of the following:

— out of memory
— inability to find a file's information
— too many directories
— file/directory not found
2 

Failure due to an invalid command line option.

File or directory "name" is not found 

The requested file or directory does not exist.

Cannot allocate memory for sorting 

To sort its output, ls needs to allocate memory; this message says that there was not enough memory for the sorting operation.

Too many directory entries in "dir

This message only appears when ls runs out of dynamically allocated memory.


PORTABILITY

POSIX.2. x/OPEN Portability Guide 4.0. All UNIX systems. Windows XP. Windows Server 2003. Windows Vista. Windows 7. Windows Server 2008. Windows 8. Windows Server 2012.

On Windows systems, ls treats files and directories marked with the hidden attribute like POSIX and UNIX file names beginning with . (period).

The -A, -b, -f, -g, -h, -L, -m, -n, -o, -p, -s, -X, and -x options are extensions to the POSIX and XPG.4 standard.

The -X option is specific to the XP/2003/Vista/7/2008/8/2012 version of ls.


AVAILABILITY

PTC MKS Toolkit for Power Users
PTC MKS Toolkit for System Administrators
PTC MKS Toolkit for Developers
PTC MKS Toolkit for Interoperability
PTC MKS Toolkit for Professional Developers
PTC MKS Toolkit for Enterprise Developers
PTC MKS Toolkit for Enterprise Developers 64-Bit Edition


SEE ALSO

Commands:
chmod, lc

Miscellaneous:
security, stat


PTC MKS Toolkit 9.6 Documentation Build 9.