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 [-ikqrs] [-glno] [-A|-a] [-C|-m|-x|-1] \
16 [-F|-p] [-H|-L] [-R|-d] [-S|-f|-t] [-c|-u] [file...]
17
19 For each operand that names a file of a type other than directory or
20 symbolic link to a directory, ls shall write the name of the file as
21 well as any requested, associated information. For each operand that
22 names a file of type directory, ls shall write the names of files con‐
23 tained within the directory as well as any requested, associated infor‐
24 mation. Filenames beginning with a <period> ('.') and any associated
25 information shall not be written out unless explicitly referenced, the
26 -A or -a option is supplied, or an implementation-defined condition
27 causes them to be written. If one or more of the -d, -F, or -l options
28 are specified, and neither the -H nor the -L option is specified, for
29 each operand that names a file of type symbolic link to a directory, ls
30 shall write the name of the file as well as any requested, associated
31 information. If none of the -d, -F, or -l options are specified, or the
32 -H or -L options are specified, for each operand that names a file of
33 type symbolic link to a directory, ls shall write the names of files
34 contained within the directory as well as any requested, associated
35 information. In each case where the names of files contained within a
36 directory are written, if the directory contains any symbolic links
37 then ls shall evaluate the file information and file type to be those
38 of the symbolic link itself, unless the -L option is specified.
39 If no operands are specified, ls shall behave as if a single operand of
41 dot ('.') had been specified. If more than one operand is specified,
42 ls shall write non-directory operands first; it shall sort directory
43 and non-directory operands separately according to the collating
44 sequence in the current locale.
45 Whenever ls sorts filenames or pathnames according to the collating
47 sequence in the current locale, if this collating sequence does not
48 have a total ordering of all characters (see the Base Definitions vol‐
49 ume of POSIX.1‐2017, Section 7.3.2, LC_COLLATE), then any filenames or
50 pathnames that collate equally should be further compared byte-by-byte
51 using the collating sequence for the POSIX locale.
52 The ls utility shall detect infinite loops; that is, entering a previ‐
54 ously visited directory that is an ancestor of the last file encoun‐
55 tered. When it detects an infinite loop, ls shall write a diagnostic
56 message to standard error and shall either recover its position in the
57 hierarchy or terminate.
58
60 The ls utility shall conform to the Base Definitions volume of
61 POSIX.1‐2017, Section 12.2, Utility Syntax Guidelines.
62 The following options shall be supported:
64 -A Write out all directory entries, including those whose names
66 begin with a <period> ('.') but excluding the entries dot
67 and dot-dot (if they exist).
68 -C Write multi-text-column output with entries sorted down the
70 columns, according to the collating sequence. The number of
71 text columns and the column separator characters are unspeci‐
72 fied, but should be adapted to the nature of the output
73 device. This option disables long format output.
74 -F Do not follow symbolic links named as operands unless the -H
76 or -L options are specified. Write a <slash> ('/') immedi‐
77 ately after each pathname that is a directory, an <asterisk>
78 ('*') after each that is executable, a <vertical-line> ('|')
79 after each that is a FIFO, and an at-sign ('@') after each
80 that is a symbolic link. For other file types, other symbols
81 may be written.
82 -H Evaluate the file information and file type for symbolic
84 links specified on the command line to be those of the file
85 referenced by the link, and not the link itself; however, ls
86 shall write the name of the link itself and not the file ref‐
87 erenced by the link.
88 -L Evaluate the file information and file type for all symbolic
90 links (whether named on the command line or encountered in a
91 file hierarchy) to be those of the file referenced by the
92 link, and not the link itself; however, ls shall write the
93 name of the link itself and not the file referenced by the
94 link. When -L is used with -l, write the contents of symbolic
95 links in the long format (see the STDOUT section).
96 -R Recursively list subdirectories encountered. When a symbolic
98 link to a directory is encountered, the directory shall not
99 be recursively listed unless the -L option is specified. The
100 use of -R with -d or -f produces unspecified results.
101 -S Sort with the primary key being file size (in decreasing
103 order) and the secondary key being filename in the collating
104 sequence (in increasing order).
105 -a Write out all directory entries, including those whose names
107 begin with a <period> ('.').
108 -c Use time of last modification of the file status information
110 (see the Base Definitions volume of POSIX.1‐2017,
111 <sys_stat.h>) instead of last modification of the file itself
112 for sorting (-t) or writing (-l).
113 -d Do not follow symbolic links named as operands unless the -H
115 or -L options are specified. Do not treat directories differ‐
116 ently than other types of files. The use of -d with -R or -f
117 produces unspecified results.
118 -f List the entries in directory operands in the order they
120 appear in the directory. The behavior for non-directory oper‐
121 ands is unspecified. This option shall turn on -a. When -f
122 is specified, any occurrences of the -r, -S, and -t options
123 shall be ignored and any occurrences of the -A, -g, -l, -n,
124 -o, and -s options may be ignored. The use of -f with -R or
125 -d produces unspecified results.
126 -g Turn on the -l (ell) option, but disable writing the file's
128 owner name or number. Disable the -C, -m, and -x options.
129 -i For each file, write the file's file serial number (see
131 stat() in the System Interfaces volume of POSIX.1‐2017).
132 -k Set the block size for the -s option and the per-directory
134 block count written for the -l, -n, -s, -g, and -o options
135 (see the STDOUT section) to 1024 bytes.
136 -l (The letter ell.) Do not follow symbolic links named as oper‐
138 ands unless the -H or -L options are specified. Write out in
139 long format (see the STDOUT section). Disable the -C, -m, and
140 -x options.
141 -m Stream output format; list pathnames across the page, sepa‐
143 rated by a <comma> character followed by a <space> character.
144 Use a <newline> character as the list terminator and after
145 the separator sequence when there is not room on a line for
146 the next list entry. This option disables long format output.
147 -n Turn on the -l (ell) option, but when writing the file's
149 owner or group, write the file's numeric UID or GID rather
150 than the user or group name, respectively. Disable the -C,
151 -m, and -x options.
152 -o Turn on the -l (ell) option, but disable writing the file's
154 group name or number. Disable the -C, -m, and -x options.
155 -p Write a <slash> ('/') after each filename if that file is a
157 directory.
158 -q Force each instance of non-printable filename characters and
160 <tab> characters to be written as the <question-mark> ('?')
161 character. Implementations may provide this option by default
162 if the output is to a terminal device.
163 -r Reverse the order of the sort to get reverse collating
165 sequence oldest first, or smallest file size first depending
166 on the other options given.
167 -s Indicate the total number of file system blocks consumed by
169 each file displayed. If the -k option is also specified, the
170 block size shall be 1024 bytes; otherwise, the block size is
171 implementation-defined.
172 -t Sort with the primary key being time modified (most recently
174 modified first) and the secondary key being filename in the
175 collating sequence. For a symbolic link, the time used as
176 the sort key is that of the symbolic link itself, unless ls
177 is evaluating its file information to be that of the file
178 referenced by the link (see the -H and -L options).
179 -u Use time of last access (see the Base Definitions volume of
181 POSIX.1‐2017, <sys_stat.h>) instead of last modification of
182 the file for sorting (-t) or writing (-l).
183 -x The same as -C, except that the multi-text-column output is
185 produced with entries sorted across, rather than down, the
186 columns. This option disables long format output.
187 -1 (The numeric digit one.) Force output to be one entry per
189 line. This option does not disable long format output. (Long
190 format output is enabled by -g, -l (ell), -n, and -o; and
191 disabled by -C, -m, and -x.)
192 If an option that enables long format output (-g, -l (ell), -n, and -o
194 is given with an option that disables long format output (-C, -m, and
195 -x), this shall not be considered an error. The last of these options
196 specified shall determine whether long format output is written.
197 If -R, -d, or -f are specified, the results of specifying these mutu‐
199 ally-exclusive options are specified by the descriptions of these
200 options above. If more than one of any of the other options shown in
201 the SYNOPSIS section in mutually-exclusive sets are given, this shall
202 not be considered an error; the last option specified in each set shall
203 determine the output.
204 Note that if -t is specified, -c and -u are not only mutually-exclusive
206 with each other, they are also mutually-exclusive with -S when deter‐
207 mining sort order. But even if -S is specified after all occurrences of
208 -c, -t, and -u, the last use of -c or -u determines the timestamp
209 printed when producing long format output.
210
212 The following operand shall be supported:
213 file A pathname of a file to be written. If the file specified is
215 not found, a diagnostic message shall be output on standard
216 error.
217
219 Not used.
220
222 None.
223
225 The following environment variables shall affect the execution of ls:
226 COLUMNS Determine the user's preferred column position width for
228 writing multiple text-column output. If this variable con‐
229 tains a string representing a decimal integer, the ls utility
230 shall calculate how many pathname text columns to write (see
231 -C) based on the width provided. If COLUMNS is not set or
232 invalid, an implementation-defined number of column positions
233 shall be assumed, based on the implementation's knowledge of
234 the output device. The column width chosen to write the names
235 of files in any given directory shall be constant. Filenames
236 shall not be truncated to fit into the multiple text-column
237 output.
238 LANG Provide a default value for the internationalization vari‐
240 ables that are unset or null. (See the Base Definitions vol‐
241 ume of POSIX.1‐2017, Section 8.2, Internationalization Vari‐
242 ables for the precedence of internationalization variables
243 used to determine the values of locale categories.)
244 LC_ALL If set to a non-empty string value, override the values of
246 all the other internationalization variables.
247 LC_COLLATE
249 Determine the locale for character collation information in
250 determining the pathname collation sequence.
251 LC_CTYPE Determine the locale for the interpretation of sequences of
253 bytes of text data as characters (for example, single-byte as
254 opposed to multi-byte characters in arguments) and which
255 characters are defined as printable (character class print).
256 LC_MESSAGES
258 Determine the locale that should be used to affect the format
259 and contents of diagnostic messages written to standard
260 error.
261 LC_TIME Determine the format and contents for date and time strings
263 written by ls.
264 NLSPATH Determine the location of message catalogs for the processing
266 of LC_MESSAGES.
267 TZ Determine the timezone for date and time strings written by
269 ls. If TZ is unset or null, an unspecified default timezone
270 shall be used.
271
273 Default.
274
276 The default format shall be to list one entry per line to standard out‐
277 put; the exceptions are to terminals or when one of the -C, -m, or -x
278 options is specified. If the output is to a terminal, the format is
279 implementation-defined.
280 When -m is specified, the format used for the last element of the list
282 shall be:
283 "%s\n", <filename>
286 The format used for each other element of the list shall be:
288 "%s,%s", <filename>, <separator>
291 where, if there is not room for the next element of the list to fit
293 within the current line length, <separator> is a string containing an
294 optional <space> character and a mandatory <newline> character; other‐
295 wise it is a single <space> character.
296 If the -i option is specified, the file's file serial number (see the
298 Base Definitions volume of POSIX.1‐2017, <sys_stat.h>) shall be written
299 in the following format before any other output for the corresponding
300 entry:
301 %u ", <file serial number>
304 If the -l option is specified, the following information shall be writ‐
306 ten for files other than character special and block special files:
307 "%s %u %s %s %u %s %s\n", <file mode>, <number of links>,
310 <owner name>, <group name>, <size>, <date and time>,
311 <pathname>
312 If the -l option is specified, the following information shall be writ‐
314 ten for character special and block special files:
315 "%s %u %s %s %s %s %s\n", <file mode>, <number of links>,
318 <owner name>, <group name>, <device info>, <date and time>,
319 <pathname>
320 In both cases if the file is a symbolic link and the -L option is also
322 specified, this information shall be for the file resolved from the
323 symbolic link, except that the <pathname> field shall contain the path‐
324 name of the symbolic link itself. If the file is a symbolic link and
325 the -L option is not specified, this information shall be about the
326 link itself and the <pathname> field shall be of the form:
327 "%s -> %s", <pathname of link>, <contents of link>
330 The -n, -g, and -o options use the same format as -l, but with omitted
332 items and their associated <blank> characters. See the OPTIONS section.
333 In both the preceding -l forms, if <owner name> or <group name> cannot
335 be determined, or if -n is given, they shall be replaced with their
336 associated numeric values using the format %u.
337 The <size> field shall contain the value that would be returned for the
339 file in the st_size field of struct stat (see the Base Definitions vol‐
340 ume of POSIX.1‐2017, <sys_stat.h>). Note that for some file types this
341 value is unspecified.
342 The <device info> field shall contain implementation-defined informa‐
344 tion associated with the device in question.
345 The <date and time> field shall contain the appropriate date and time‐
347 stamp of when the file was last modified. In the POSIX locale, the
348 field shall be the equivalent of the output of the following date com‐
349 mand:
350 date "+%b %e %H:%M"
353 if the file has been modified in the last six months, or:
355 date "+%b %e %Y"
358 (where two <space> characters are used between %e and %Y) if the file
360 has not been modified in the last six months or if the modification
361 date is in the future, except that, in both cases, the final <newline>
362 produced by date shall not be included and the output shall be as if
363 the date command were executed at the time of the last modification
364 date of the file rather than the current time. When the LC_TIME locale
365 category is not set to the POSIX locale, a different format and order
366 of presentation of this field may be used.
367 If the pathname was specified as a file operand, it shall be written as
369 specified.
370 The file mode written under the -l, -n, -g, and -o options shall con‐
372 sist of the following format:
373 "%c%s%s%s%s", <entry type>, <owner permissions>,
376 <group permissions>, <other permissions>,
377 <optional alternate access method flag>
378 The <optional alternate access method flag> shall be the empty string
380 if there is no alternate or additional access control method associated
381 with the file; otherwise, it shall be a string containing a single
382 printable character that is not a <blank>.
383 The <entry type> character shall describe the type of file, as follows:
385 d Directory.
387 b Block special file.
389 c Character special file.
391 l (ell) Symbolic link.
393 p FIFO.
395 - Regular file.
397 Implementations may add other characters to this list to represent
399 other implementation-defined file types.
400 The next three fields shall be three characters each:
402 <owner permissions>
404 Permissions for the file owner class (see the Base Definitions
405 volume of POSIX.1‐2017, Section 4.5, File Access Permissions).
406 <group permissions>
408 Permissions for the file group class.
409 <other permissions>
411 Permissions for the file other class.
412 Each field shall have three character positions:
414 1. If 'r', the file is readable; if '-', the file is not readable.
416 2. If 'w', the file is writable; if '-', the file is not writable.
418 3. The first of the following that applies:
420 S If in <owner permissions>, the file is not executable and
422 set-user-ID mode is set. If in <group permissions>, the file
423 is not executable and set-group-ID mode is set.
424 s If in <owner permissions>, the file is executable and set-
426 user-ID mode is set. If in <group permissions>, the file is
427 executable and set-group-ID mode is set.
428 T If in <other permissions> and the file is a directory, search
430 permission is not granted to others, and the restricted dele‐
431 tion flag is set.
432 t If in <other permissions> and the file is a directory, search
434 permission is granted to others, and the restricted deletion
435 flag is set.
436 x The file is executable or the directory is searchable.
438 - None of the attributes of 'S', 's', 'T', 't', or 'x' applies.
440 Implementations may add other characters to this list for the third
442 character position. Such additions shall, however, be written in
443 lowercase if the file is executable or searchable, and in uppercase
444 if it is not.
445 If any of the -l, -n, -s, -g, or -o options is specified, each list of
447 files within the directory shall be preceded by a status line indicat‐
448 ing the number of file system blocks occupied by files in the directory
449 in 512-byte units if the -k option is not specified, or 1024-byte units
450 if the -k option is specified, rounded up to the next integral number
451 of units, if necessary. In the POSIX locale, the format shall be:
452 "total %u\n", <number of units in the directory>
455 If more than one directory, or a combination of non-directory files and
457 directories are written, either as a result of specifying multiple op‐
458 erands, or the -R option, each list of files within a directory shall
459 be preceded by:
460 "\n%s:\n", <directory name>
463 If this string is the first thing to be written, the first <newline>
465 shall not be written. This output shall precede the number of units in
466 the directory.
467 If the -s option is given, each file shall be written with the number
469 of blocks used by the file. Along with -C, -1, -m, or -x, the number
470 and a <space> shall precede the filename; with -l, -n, -g, or -o, they
471 shall precede each line describing a file.
472
474 The standard error shall be used only for diagnostic messages.
475
477 None.
478
480 None.
481
483 The following exit values shall be returned:
484 0 Successful completion.
486 >0 An error occurred.
488
490 Default.
491 The following sections are informative.
493
495 Many implementations use the <equals-sign> ('=') to denote sockets
496 bound to the file system for the -F option. Similarly, many historical
497 implementations use the 's' character to denote sockets as the entry
498 type characters for the -l option.
499 It is difficult for an application to use every part of the file modes
501 field of ls -l in a portable manner. Certain file types and executable
502 bits are not guaranteed to be exactly as shown, as implementations may
503 have extensions. Applications can use this field to pass directly to a
504 user printout or prompt, but actions based on its contents should gen‐
505 erally be deferred, instead, to the test utility.
506 The output of ls (with the -l and related options) contains information
508 that logically could be used by utilities such as chmod and touch to
509 restore files to a known state. However, this information is presented
510 in a format that cannot be used directly by those utilities or be eas‐
511 ily translated into a format that can be used. A character has been
512 added to the end of the permissions string so that applications at
513 least have an indication that they may be working in an area they do
514 not understand instead of assuming that they can translate the permis‐
515 sions string into something that can be used. Future versions or
516 related documents may define one or more specific characters to be used
517 based on different standard additional or alternative access control
518 mechanisms.
519 As with many of the utilities that deal with filenames, the output of
521 ls for multiple files or in one of the long listing formats must be
522 used carefully on systems where filenames can contain embedded white
523 space. Systems and system administrators should institute policies and
524 user training to limit the use of such filenames.
525 The number of disk blocks occupied by the file that it reports varies
527 depending on underlying file system type, block size units reported,
528 and the method of calculating the number of blocks. On some file system
529 types, the number is the actual number of blocks occupied by the file
530 (counting indirect blocks and ignoring holes in the file); on others it
531 is calculated based on the file size (usually making an allowance for
532 indirect blocks, but ignoring holes).
533
535 An example of a small directory tree being fully listed with ls -laRF a
536 in the POSIX locale:
537 total 11
540 drwxr-xr-x 3 fox prog 64 Jul 4 12:07 ./
541 drwxrwxrwx 4 fox prog 3264 Jul 4 12:09 ../
542 drwxr-xr-x 2 fox prog 48 Jul 4 12:07 b/
543 -rwxr--r-- 1 fox prog 572 Jul 4 12:07 foo*
544 a/b:
546 total 4
547 drwxr-xr-x 2 fox prog 48 Jul 4 12:07 ./
548 drwxr-xr-x 3 fox prog 64 Jul 4 12:07 ../
549 -rw-r--r-- 1 fox prog 700 Jul 4 12:07 bar
550
552 Some historical implementations of the ls utility show all entries in a
553 directory except dot and dot-dot when a superuser invokes ls without
554 specifying the -a option. When ``normal'' users invoke ls without spec‐
555 ifying -a, they should not see information about any files with names
556 beginning with a <period> unless they were named as file operands.
557 Implementations are expected to traverse arbitrary depths when process‐
559 ing the -R option. The only limitation on depth should be based on run‐
560 ning out of physical storage for keeping track of untraversed directo‐
561 ries.
562 The -1 (one) option was historically found in BSD and BSD-derived
564 implementations only. It is required in this volume of POSIX.1‐2017 so
565 that conforming applications might ensure that output is one entry per
566 line, even if the output is to a terminal.
567 The -S option was added in Issue 7, but had been provided by several
569 implementations for many years. The description given in the standard
570 documents historic practice, but does not match much of the documenta‐
571 tion that described its behavior. Historical documentation typically
572 described it as something like:
573 -S Sort by size (largest size first) instead of by name. Special
575 character devices (listed last) are sorted by name.
576 even though the file type was never considered when sorting the output.
578 Character special files do typically sort close to the end of the list
579 because their file size on most implementations is zero. But they are
580 sorted alphabetically with any other files that happen to have the same
581 file size (zero), not sorted separately and added to the end.
582 This volume of POSIX.1‐2017 is frequently silent about what happens
584 when mutually-exclusive options are specified. Except for -R, -d, and
585 -f, the ls utility is required to accept multiple options from each
586 mutually-exclusive option set without treating them as errors and to
587 use the behavior specified by the last option given in each mutually-
588 exclusive set. Since ls is one of the most aliased commands, it is
589 important that the implementation perform intuitively. For example, if
590 the alias were:
591 alias ls="ls -C"
594 and the user typed ls -1 (one), single-text-column output should
596 result, not an error.
597 The -g, -l (ell), -n, and -o options are not mutually-exclusive
599 options. They all enable long format output. They work together to
600 determine whether the file's owner is written (no if -g is present),
601 file's group is written (no if -o is present), and if the file's group
602 or owner is written whether it is written as the name (default) or a
603 string representation of the UID or GID number (if -n is present). The
604 -C, -m, -x, and -1 (one) are mutually-exclusive options and the first
605 three of these disable long format output. The -1 (one) option does not
606 directly change whether or not long format output is enabled, but by
607 overriding -C, -m, and -x, it can re-enable long format output that had
608 been disabled by one of these options.
609 Earlier versions of this standard did not describe the BSD -A option
611 (like -a, but dot and dot-dot are not written out). It has been added
612 due to widespread implementation.
613 Implementations may make -q the default for terminals to prevent trojan
615 horse attacks on terminals with special escape sequences. This is not
616 required because:
617 * Some control characters may be useful on some terminals; for exam‐
619 ple, a system might write them as "\001" or "^A".
620 * Special behavior for terminals is not relevant to applications
622 portability.
623 An early proposal specified that the <optional alter‐
625 nate access method flag> had to be '+' if there was an alternate access
626 method used on the file or <space> if there was not. This was changed
627 to be <space> if there is not and a single printable character if there
628 is. This was done for three reasons:
629 1. There are historical implementations using characters other than
631 '+'.
632 2. There are implementations that vary this character used in that
634 position to distinguish between various alternate access methods in
635 use.
636 3. The standard developers did not want to preclude future specifica‐
638 tions that might need a way to specify more than one alternate
639 access method.
640 Nonetheless, implementations providing a single alternate access method
642 are encouraged to use '+'.
643 Earlier versions of this standard did not have the -k option, which
645 meant that the -s option could not be used portably as its block size
646 was implementation-defined, and the units used to specify the number of
647 blocks occupied by files in a directory in an ls -l listing were fixed
648 as 512-byte units. The -k option has been added to provide a way for
649 the -s option to be used portably, and for consistency it also changes
650 the aforementioned units from 512-byte to 1024-byte.
651 The <date and time> field in the -l format is specified only for the
653 POSIX locale. As noted, the format can be different in other locales.
654 No mechanism for defining this is present in this volume of
655 POSIX.1‐2017, as the appropriate vehicle is a messaging system; that
656 is, the format should be specified as a ``message''.
657
659 Allowing -f to ignore the -A, -g, -l, -n, -o, and -s options may be
660 removed in a future version.
661 A future version of this standard may require that if the collating
663 sequence for the current locale does not have a total ordering of all
664 characters, any filenames or pathnames that collate equally are further
665 compared byte-by-byte using the collating sequence for the POSIX
666 locale.
667
669 chmod, find
670 The Base Definitions volume of POSIX.1‐2017, Section 7.3.2, LC_COLLATE,
672 Section 4.5, File Access Permissions, Chapter 8, Environment Variables,
673 Section 12.2, Utility Syntax Guidelines, <sys_stat.h>
674 The System Interfaces volume of POSIX.1‐2017, fstatat()
676
678 Portions of this text are reprinted and reproduced in electronic form
679 from IEEE Std 1003.1-2017, Standard for Information Technology -- Por‐
680 table Operating System Interface (POSIX), The Open Group Base Specifi‐
681 cations Issue 7, 2018 Edition, Copyright (C) 2018 by the Institute of
682 Electrical and Electronics Engineers, Inc and The Open Group. In the
683 event of any discrepancy between this version and the original IEEE and
684 The Open Group Standard, the original IEEE and The Open Group Standard
685 is the referee document. The original Standard can be obtained online
686 at http://www.opengroup.org/unix/online.html .
687 Any typographical or formatting errors that appear in this page are
689 most likely to have been introduced during the conversion of the source
690 files to man page format. To report such errors, see https://www.ker‐
691 nel.org/doc/man-pages/reporting_bugs.html .
692IEEE/The Open Group 2017 LS(1P)