1LS(1P) POSIX Programmer's Manual LS(1P)
2
6 This manual page is part of the POSIX Programmer's Manual. The Linux
7 implementation of this interface may differ (consult the corresponding
8 Linux manual page for details of Linux behavior), or the interface may
9 not be implemented on Linux.
10
12 ls - list directory contents
13
15 ls [-CFRacdilqrtu1][-H | -L ][-fgmnopsx][file...]
16
18 For each operand that names a file of a type other than directory or
19 symbolic link to a directory, ls shall write the name of the file as
20 well as any requested, associated information. For each operand that
21 names a file of type directory, ls shall write the names of files con‐
22 tained within the directory as well as any requested, associated infor‐
23 mation. If one of the -d, -F, or -l options are specified, and one of
24 the -H or -L options are not specified, for each operand that names a
25 file of type symbolic link to a directory, ls shall write the name of
26 the file as well as any requested, associated information. If none of
27 the -d, -F, or -l options are specified, or the -H or -L options are
28 specified, for each operand that names a file of type symbolic link to
29 a directory, ls shall write the names of files contained within the
30 directory as well as any requested, associated information.
31 If no operands are specified, ls shall write the contents of the cur‐
33 rent directory. If more than one operand is specified, ls shall write
34 non-directory operands first; it shall sort directory and non-directory
35 operands separately according to the collating sequence in the current
36 locale.
37 The ls utility shall detect infinite loops; that is, entering a previ‐
39 ously visited directory that is an ancestor of the last file encoun‐
40 tered. When it detects an infinite loop, ls shall write a diagnostic
41 message to standard error and shall either recover its position in the
42 hierarchy or terminate.
43
45 The ls utility shall conform to the Base Definitions volume of
46 IEEE Std 1003.1-2001, Section 12.2, Utility Syntax Guidelines.
47 The following options shall be supported:
49 -C Write multi-text-column output with entries sorted down the col‐
51 umns, according to the collating sequence. The number of text
52 columns and the column separator characters are unspecified, but
53 should be adapted to the nature of the output device.
54 -F Do not follow symbolic links named as operands unless the -H or
56 -L options are specified. Write a slash ( '/' ) immediately
57 after each pathname that is a directory, an asterisk ( '*' )
58 after each that is executable, a vertical bar ( '|' ) after each
59 that is a FIFO, and an at sign ( '@' ) after each that is a sym‐
60 bolic link. For other file types, other symbols may be written.
61 -H If a symbolic link referencing a file of type directory is spec‐
63 ified on the command line, ls shall evaluate the file informa‐
64 tion and file type to be those of the file referenced by the
65 link, and not the link itself; however, ls shall write the name
66 of the link itself and not the file referenced by the link.
67 -L Evaluate the file information and file type for all symbolic
69 links (whether named on the command line or encountered in a
70 file hierarchy) to be those of the file referenced by the link,
71 and not the link itself; however, ls shall write the name of the
72 link itself and not the file referenced by the link. When -L is
73 used with -l, write the contents of symbolic links in the long
74 format (see the STDOUT section).
75 -R Recursively list subdirectories encountered.
77 -a Write out all directory entries, including those whose names
79 begin with a period ( '.' ). Entries beginning with a period
80 shall not be written out unless explicitly referenced, the -a
81 option is supplied, or an implementation-defined condition shall
82 cause them to be written.
83 -c Use time of last modification of the file status information
85 (see <sys/stat.h> in the System Interfaces volume of
86 IEEE Std 1003.1-2001) instead of last modification of the file
87 itself for sorting ( -t) or writing ( -l).
88 -d Do not follow symbolic links named as operands unless the -H or
90 -L options are specified. Do not treat directories differently
91 than other types of files. The use of -d with -R produces
92 unspecified results.
93 -f Force each argument to be interpreted as a directory and list
95 the name found in each slot. This option shall turn off -l, -t,
96 -s, and -r, and shall turn on -a; the order is the order in
97 which entries appear in the directory.
98 -g The same as -l, except that the owner shall not be written.
100 -i For each file, write the file's file serial number (see stat()
102 in the System Interfaces volume of IEEE Std 1003.1-2001).
103 -l (The letter ell.) Do not follow symbolic links named as operands
105 unless the -H or -L options are specified. Write out in long
106 format (see the STDOUT section). When -l (ell) is specified, -1
107 (one) shall be assumed.
108 -m Stream output format; list files across the page, separated by
110 commas.
111 -n The same as -l, except that the owner's UID and GID numbers
113 shall be written, rather than the associated character strings.
114 -o The same as -l, except that the group shall not be written.
116 -p Write a slash ( '/' ) after each filename if that file is a
118 directory.
119 -q Force each instance of non-printable filename characters and
121 <tab>s to be written as the question-mark ( '?' ) character.
122 Implementations may provide this option by default if the output
123 is to a terminal device.
124 -r Reverse the order of the sort to get reverse collating sequence
126 or oldest first.
127 -s Indicate the total number of file system blocks consumed by each
129 file displayed. The block size is implementation-defined.
130 -t Sort with the primary key being time modified (most recently
132 modified first) and the secondary key being filename in the col‐
133 lating sequence.
134 -u Use time of last access (see <sys/stat.h>) instead of last modi‐
136 fication of the file for sorting ( -t) or writing ( -l).
137 -x The same as -C, except that the multi-text-column output is pro‐
139 duced with entries sorted across, rather than down, the columns.
140 -1 (The numeric digit one.) Force output to be one entry per line.
142 Specifying more than one of the options in the following mutually-
145 exclusive pairs shall not be considered an error: -C and -l (ell), -m
146 and -l (ell), -x and -l (ell), -C and -1 (one), -H and -L, -c and -u.
147 The last option specified in each pair shall determine the output for‐
148 mat.
149
151 The following operand shall be supported:
152 file A pathname of a file to be written. If the file specified is not
154 found, a diagnostic message shall be output on standard error.
155
158 Not used.
159
161 None.
162
164 The following environment variables shall affect the execution of ls:
165 COLUMNS
167 Determine the user's preferred column position width for writing
168 multiple text-column output. If this variable contains a string
169 representing a decimal integer, the ls utility shall calculate
170 how many pathname text columns to write (see -C) based on the
171 width provided. If COLUMNS is not set or invalid, an implementa‐
172 tion-defined number of column positions shall be assumed, based
173 on the implementation's knowledge of the output device. The col‐
174 umn width chosen to write the names of files in any given direc‐
175 tory shall be constant. Filenames shall not be truncated to fit
176 into the multiple text-column output.
177 LANG Provide a default value for the internationalization variables
179 that are unset or null. (See the Base Definitions volume of
180 IEEE Std 1003.1-2001, Section 8.2, Internationalization Vari‐
181 ables for the precedence of internationalization variables used
182 to determine the values of locale categories.)
183 LC_ALL If set to a non-empty string value, override the values of all
185 the other internationalization variables.
186 LC_COLLATE
188 Determine the locale for character collation information in
190 determining the pathname collation sequence.
191 LC_CTYPE
193 Determine the locale for the interpretation of sequences of
194 bytes of text data as characters (for example, single-byte as
195 opposed to multi-byte characters in arguments) and which charac‐
196 ters are defined as printable (character class print).
197 LC_MESSAGES
199 Determine the locale that should be used to affect the format
200 and contents of diagnostic messages written to standard error.
201 LC_TIME
203 Determine the format and contents for date and time strings
204 written by ls.
205 NLSPATH
207 Determine the location of message catalogs for the processing of
208 LC_MESSAGES .
209 TZ Determine the timezone for date and time strings written by ls.
211 If TZ is unset or null, an unspecified default timezone shall be
212 used.
213
216 Default.
217
219 The default format shall be to list one entry per line to standard out‐
220 put; the exceptions are to terminals or when one of the -C, -m, or -x
221 options is specified. If the output is to a terminal, the format is
222 implementation-defined.
223 When -m is specified, the format used shall be:
225 "%s, %s, ...\n", <filename1>, <filename2>
228 where the largest number of filenames shall be written without exceed‐
230 ing the length of the line.
231 If the -i option is specified, the file's file serial number (see
233 <sys/stat.h>) shall be written in the following format before any other
234 output for the corresponding entry:
235 %u ", <file serial number>
238 If the -l option is specified without -L, the following information
240 shall be written:
241 "%s %u %s %s %u %s %s\n", <file mode>, <number of links>,
244 <owner name>, <group name>, <number of bytes in the file>,
245 <date and time>, <pathname>
246 If the file is a symbolic link, this information shall be about the
248 link itself and the <pathname> field shall be of the form:
249 "%s -> %s", <pathname of link>, <contents of link>
252 If both -l and -L are specified, the following information shall be
254 written:
255 "%s %u %s %s %u %s %s\n", <file mode>, <number of links>,
258 <owner name>, <group name>, <number of bytes in the file>,
259 <date and time>, <pathname of link>
260 where all fields except <pathname of link> shall be for the file
262 resolved from the symbolic link.
263 The -g, -n, and -o options use the same format as -l, but with omitted
265 items and their associated <blank>s. See the OPTIONS section.
266 In both the preceding -l forms, if <owner name> or <group name> cannot
268 be determined, or if -n is given, they shall be replaced with their
269 associated numeric values using the format %u .
270 The <date and time> field shall contain the appropriate date and time‐
272 stamp of when the file was last modified. In the POSIX locale, the
273 field shall be the equivalent of the output of the following date com‐
274 mand:
275 date "+%b %e %H:%M"
278 if the file has been modified in the last six months, or:
280 date "+%b %e %Y"
283 (where two <space>s are used between %e and %Y ) if the file has not
285 been modified in the last six months or if the modification date is in
286 the future, except that, in both cases, the final <newline> produced by
287 date shall not be included and the output shall be as if the date com‐
288 mand were executed at the time of the last modification date of the
289 file rather than the current time. When the LC_TIME locale category is
290 not set to the POSIX locale, a different format and order of presenta‐
291 tion of this field may be used.
292 If the file is a character special or block special file, the size of
294 the file may be replaced with implementation-defined information asso‐
295 ciated with the device in question.
296 If the pathname was specified as a file operand, it shall be written as
298 specified.
299 The file mode written under the -l, -g, -n, and -o options shall
301 consist of the following format:
302 "%c%s%s%s%c", <entry type>, <owner permissions>,
305 <group permissions>, <other permissions>,
306 <optional alternate access method flag>
307 The <optional alternate access method flag> shall be a single <space>
309 if there is no alternate or additional access control method associated
310 with the file; otherwise, a printable character shall be used.
311 The <entry type> character shall describe the type of file, as follows:
313 d Directory.
315 b Block special file.
317 c Character special file.
319 l (ell)
321 Symbolic link.
322 p FIFO.
324 - Regular file.
326 Implementations may add other characters to this list to represent
329 other implementation-defined file types.
330 The next three fields shall be three characters each:
332 <owner permissions>
334 Permissions for the file owner class (see the Base Definitions
336 volume of IEEE Std 1003.1-2001, Section 4.4, File Access Permis‐
337 sions).
338 <group permissions>
340 Permissions for the file group class.
342 <other permissions>
344 Permissions for the file other class.
346 Each field shall have three character positions:
349 1. If 'r', the file is readable; if '-', the file is not readable.
351 2. If 'w', the file is writable; if '-', the file is not writable.
353 3. The first of the following that applies:
355 S
357 If in <owner permissions>, the file is not executable and set-
358 user-ID mode is set. If in <group permissions>, the file is not
359 executable and set-group-ID mode is set.
360 s
362 If in <owner permissions>, the file is executable and set-user-
363 ID mode is set. If in <group permissions>, the file is exe‐
364 cutable and set-group-ID mode is set.
365 T
367 If in <other permissions> and the file is a directory, search
368 permission is not granted to others, and the restricted deletion
369 flag is set.
370 t
372 If in <other permissions> and the file is a directory, search
373 permission is granted to others, and the restricted deletion
374 flag is set.
375 x
377 The file is executable or the directory is searchable.
378 -
380 None of the attributes of 'S', 's', 'T', 't', or 'x' applies.
381 Implementations may add other characters to this list for the third
384 character position. Such additions shall, however, be written in lower‐
385 case if the file is executable or searchable, and in uppercase if it is
386 not.
387 If any of the -l, -g, -n, -o, or -s options is specified, each list
389 of files within the directory shall be preceded by a status line indi‐
390 cating the number of file system blocks occupied by files in the direc‐
391 tory in 512-byte units, rounded up to the next integral number of
392 units, if necessary. In the POSIX locale, the format shall be:
393 "total %u\n", <number of units in the directory>
396 If more than one directory, or a combination of non-directory files and
398 directories are written, either as a result of specifying multiple op‐
399 erands, or the -R option, each list of files within a directory shall
400 be preceded by:
401 "\n%s:\n", <directory name>
404 If this string is the first thing to be written, the first <newline>
406 shall not be written. This output shall precede the number of units in
407 the directory.
408 If the -s option is given, each file shall be written with the number
410 of blocks used by the file. Along with -C, -1, -m, or -x, the number
411 and a <space> shall precede the filename; with -g, -l, -n, or -o, they
412 shall precede each line describing a file.
413
415 The standard error shall be used only for diagnostic messages.
416
418 None.
419
421 None.
422
424 The following exit values shall be returned:
425 0 Successful completion.
427 >0 An error occurred.
429
432 Default.
433 The following sections are informative.
435
437 Many implementations use the equal sign ( '=' ) to denote sockets bound
438 to the file system for the -F option. Similarly, many historical
439 implementations use the 's' character to denote sockets as the entry
440 type characters for the -l option.
441 It is difficult for an application to use every part of the file modes
443 field of ls -l in a portable manner. Certain file types and executable
444 bits are not guaranteed to be exactly as shown, as implementations may
445 have extensions. Applications can use this field to pass directly to a
446 user printout or prompt, but actions based on its contents should gen‐
447 erally be deferred, instead, to the test utility.
448 The output of ls (with the -l and related options) contains information
450 that logically could be used by utilities such as chmod and touch to
451 restore files to a known state. However, this information is presented
452 in a format that cannot be used directly by those utilities or be eas‐
453 ily translated into a format that can be used. A character has been
454 added to the end of the permissions string so that applications at
455 least have an indication that they may be working in an area they do
456 not understand instead of assuming that they can translate the permis‐
457 sions string into something that can be used. Future issues or related
458 documents may define one or more specific characters to be used based
459 on different standard additional or alternative access control mecha‐
460 nisms.
461 As with many of the utilities that deal with filenames, the output of
463 ls for multiple files or in one of the long listing formats must be
464 used carefully on systems where filenames can contain embedded white
465 space. Systems and system administrators should institute policies and
466 user training to limit the use of such filenames.
467 The number of disk blocks occupied by the file that it reports varies
469 depending on underlying file system type, block size units reported,
470 and the method of calculating the number of blocks. On some file system
471 types, the number is the actual number of blocks occupied by the file
472 (counting indirect blocks and ignoring holes in the file); on others it
473 is calculated based on the file size (usually making an allowance for
474 indirect blocks, but ignoring holes).
475
477 An example of a small directory tree being fully listed with ls -laRF a
478 in the POSIX locale:
479 total 11
482 drwxr-xr-x 3 hlj prog 64 Jul 4 12:07 ./
483 drwxrwxrwx 4 hlj prog 3264 Jul 4 12:09 ../
484 drwxr-xr-x 2 hlj prog 48 Jul 4 12:07 b/
485 -rwxr--r-- 1 hlj prog 572 Jul 4 12:07 foo*
486 a/b:
489 total 4
490 drwxr-xr-x 2 hlj prog 48 Jul 4 12:07 ./
491 drwxr-xr-x 3 hlj prog 64 Jul 4 12:07 ../
492 -rw-r--r-- 1 hlj prog 700 Jul 4 12:07 bar
493
495 Some historical implementations of the ls utility show all entries in a
496 directory except dot and dot-dot when a superuser invokes ls without
497 specifying the -a option. When "normal" users invoke ls without speci‐
498 fying -a, they should not see information about any files with names
499 beginning with a period unless they were named as file operands.
500 Implementations are expected to traverse arbitrary depths when process‐
502 ing the -R option. The only limitation on depth should be based on run‐
503 ning out of physical storage for keeping track of untraversed directo‐
504 ries.
505 The -1 (one) option was historically found in BSD and BSD-derived
507 implementations only. It is required in this volume of
508 IEEE Std 1003.1-2001 so that conforming applications might ensure that
509 output is one entry per line, even if the output is to a terminal.
510 Generally, this volume of IEEE Std 1003.1-2001 is silent about what
512 happens when options are given multiple times. In the cases of -C, -l,
513 and -1, however, it does specify the results of these overlapping
514 options. Since ls is one of the most aliased commands, it is important
515 that the implementation perform intuitively. For example, if the alias
516 were:
517 alias ls="ls -C"
520 and the user typed ls -1, single-text-column output should result, not
522 an error.
523 The BSD ls provides a -A option (like -a, but dot and dot-dot are not
525 written out). The small difference from -a did not seem important
526 enough to require both.
527 Implementations may make -q the default for terminals to prevent trojan
529 horse attacks on terminals with special escape sequences. This is not
530 required because:
531 * Some control characters may be useful on some terminals; for exam‐
533 ple, a system might write them as "\001" or "^A" .
534 * Special behavior for terminals is not relevant to applications
536 portability.
537 An early proposal specified that the optional alternate access method
539 flag had to be '+' if there was an alternate access method used on the
540 file or <space> if there was not. This was changed to be <space> if
541 there is not and a single printable character if there is. This was
542 done for three reasons:
543 1. There are historical implementations using characters other than
545 '+' .
546 2. There are implementations that vary this character used in that
548 position to distinguish between various alternate access methods in
549 use.
550 3. The standard developers did not want to preclude future specifica‐
552 tions that might need a way to specify more than one alternate
553 access method.
554 Nonetheless, implementations providing a single alternate access method
556 are encouraged to use '+' .
557 In an early proposal, the units used to specify the number of blocks
559 occupied by files in a directory in an ls -l listing were implementa‐
560 tion-defined. This was because BSD systems have historically used
561 1024-byte units and System V systems have historically used 512-byte
562 units. It was pointed out by BSD developers that their system has used
563 512-byte units in some places and 1024-byte units in other places.
564 (System V has consistently used 512.) Therefore, this volume of
565 IEEE Std 1003.1-2001 usually specifies 512. Future releases of BSD are
566 expected to consistently provide 512 bytes as a default with a way of
567 specifying 1024-byte units where appropriate.
568 The <date and time> field in the -l format is specified only for the
570 POSIX locale. As noted, the format can be different in other locales.
571 No mechanism for defining this is present in this volume of
572 IEEE Std 1003.1-2001, as the appropriate vehicle is a messaging system;
573 that is, the format should be specified as a "message".
574
576 The -s uses implementation-defined units and cannot be used portably;
577 it may be withdrawn in a future version.
578
580 chmod(), find, the System Interfaces volume of IEEE Std 1003.1-2001,
581 stat(), the Base Definitions volume of IEEE Std 1003.1-2001,
582 <sys/stat.h>
583
585 Portions of this text are reprinted and reproduced in electronic form
586 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
587 -- Portable Operating System Interface (POSIX), The Open Group Base
588 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
589 Electrical and Electronics Engineers, Inc and The Open Group. In the
590 event of any discrepancy between this version and the original IEEE and
591 The Open Group Standard, the original IEEE and The Open Group Standard
592 is the referee document. The original Standard can be obtained online
593 at http://www.opengroup.org/unix/online.html .
594IEEE/The Open Group 2003 LS(1P)