2 .\" Copyright (c) 1980, 1990, 1991, 1993, 1994
3 .\" The Regents of the University of California. All rights reserved.
5 .\" This code is derived from software contributed to Berkeley by
6 .\" the Institute of Electrical and Electronics Engineers, Inc.
8 .\" Redistribution and use in source and binary forms, with or without
9 .\" modification, are permitted provided that the following conditions
11 .\" 1. Redistributions of source code must retain the above copyright
12 .\" notice, this list of conditions and the following disclaimer.
13 .\" 2. Redistributions in binary form must reproduce the above copyright
14 .\" notice, this list of conditions and the following disclaimer in the
15 .\" documentation and/or other materials provided with the distribution.
16 .\" 4. Neither the name of the University nor the names of its contributors
17 .\" may be used to endorse or promote products derived from this software
18 .\" without specific prior written permission.
20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
32 .\" @(#)ls.1 8.7 (Berkeley) 7/29/94
40 .Nd list directory contents
43 .Op Fl ABCFGHILPRSTUWZabcdfghiklmnopqrstuwxy1,
47 For each operand that names a
52 displays its name as well as any requested,
53 associated information.
54 For each operand that names a
58 displays the names of files contained
59 within that directory, as well as any requested, associated
62 If no operands are given, the contents of the current
63 directory are displayed.
64 If more than one operand is given,
65 non-directory operands are displayed first; directory
66 and non-directory operands are sorted separately and in
67 lexicographical order.
69 The following options are available:
70 .Bl -tag -width indent
72 Include directory entries whose names begin with a
79 Automatically set for the super-user unless
83 Force printing of non-printable characters (as defined by
85 and current locale settings) in file names as
89 is the numeric value of the character in octal.
91 Force multi-column output; this is the default when output is to a terminal.
93 When printing in the long
97 to format the date and time output.
102 Depending on the choice of format string, this may result in a
103 different number of columns in the output.
104 This option overrides the
110 immediately after each pathname that is a directory,
113 after each that is executable,
116 after each symbolic link,
128 Enable colorized output.
129 This option is equivalent to defining
133 This functionality can be compiled out by removing the definition of
136 Symbolic links on the command line are followed.
137 This option is assumed if
142 options are specified.
146 from being automatically set for the super-user.
148 If argument is a symbolic link, list the file or directory the link references
149 rather than the link itself.
150 This option cancels the
154 If argument is a symbolic link, list the link itself rather than the
155 object the link references.
156 This option cancels the
162 Recursively list subdirectories encountered.
164 Sort by size (largest file first) before sorting the operands in
165 lexicographical order.
167 When printing in the long
169 format, display complete time information for the file, including
170 month, day, hour, minute, second, and year.
173 option gives even more control over the output format.
175 Use time when file was created for sorting or printing.
177 Display whiteouts when scanning directories.
179 Display each file's MAC label; see
182 Include directory entries whose names begin with a
190 escape codes whenever possible.
192 Use time when file status was last changed for sorting or printing.
194 Directories are listed as plain files (not searched recursively).
196 Output is not sorted.
198 This option is deprecated and is only available for compatibility
201 it was used to display the group name in the long
207 option, use unit suffixes: Byte, Kilobyte, Megabyte, Gigabyte, Terabyte
208 and Petabyte in order to reduce the number of digits to four or fewer
209 using base 2 for sizes.
211 For each file, print the file's file serial number (inode number).
213 This has the same effect as setting environment variable
215 to 1024, except that it also nullifies any
219 (The lowercase letter
221 List files in the long format, as described in the
225 Stream output format; list files across the page, separated by commas.
227 Display user and group IDs numerically rather than converting to a user
228 or group name in a long
232 Include the file flags in a long
237 for a list of file flags and their meanings.
241 after each filename if that file is a directory.
243 Force printing of non-graphic characters in file names as
246 this is the default when output is to a terminal.
248 Reverse the order of the sort.
250 Display the number of blocks used in the file system by each file.
251 Block sizes and directory totals are handled as described in
253 subsection below, except (if the long format is not also requested)
254 the directory totals are not output when the output is in a
255 single column, even if multi-column output is requested.
257 Sort by descending time modified (most recently modified first). If two files
258 have the same modification timestamp, sort their names in ascending
259 lexicographical order.
262 option reverses both of these sort orders.
264 Note that these sort orders are contradictory: the time sequence is in
265 descending order, the lexicographical sort is in ascending order.
266 This behavior is mandated by
268 This feature can cause problems listing files stored with sequential names on
269 FAT file systems, such as from digital cameras, where it is possible to have
270 more than one image with the same timestamp.
271 In such a case, the photos cannot be listed in the sequence in which
273 To ensure the same sort order for time and for lexicographical sorting, set the
281 to reverse the lexicographal sort order when sorting files with the
282 same modification timestamp.
284 Use time of last access,
285 instead of time of last modification
286 of the file for sorting
291 Force raw printing of non-printable characters.
293 when output is not to a terminal.
297 except that the multi-column output is produced with entries sorted
298 across, rather than down, the columns.
302 option is set, sort the alphabetical output in the same order as the time output.
303 This has the same effect as setting
305 See the description of the
307 option for more details.
313 This is the default when
314 output is not to a terminal.
318 option is set, print file sizes grouped and separated by thousands using the
319 non-monetary separator returned by
321 typically a comma or period.
322 If no locale is set, or the locale does not have a non-monetary separator, this
323 option has no effect.
330 options all override each other; the last one specified determines
337 options all override each other; the last one specified determines
344 options override each other; the last one specified determines
351 options all override each other; the last one specified determines
352 the format used for non-printable characters.
358 options all override each other (either partially or fully); they
359 are applied in the order specified.
363 lists one entry per line to standard
364 output; the exceptions are to terminals or when the
368 options are specified.
370 File information is displayed with one or more
372 separating the information associated with the
380 option is given, the following information
381 is displayed for each file:
383 number of links, owner name, group name,
385 number of bytes in the file, abbreviated
386 month, day-of-month file was last modified,
387 hour file last modified, minute file last
388 modified, and the pathname.
390 If the modification time of the file is more than 6 months
391 in the past or future, and the
396 then the year of the last modification
397 is displayed in place of the hour and minute fields.
399 If the owner or group names are not a known user or group name,
403 the numeric ID's are displayed.
405 If the file is a character special or block special file,
406 the device number for the file is displayed in the size field.
407 If the file is a symbolic link the pathname of the
408 linked-to file is preceded by
411 The listing of a directory's contents is preceded
412 by a labeled total number of blocks used in the file system by the files
413 which are listed as the directory's contents
414 (which may or may not include
418 and other files which start with a dot, depending on other options).
420 The default block size is 512 bytes.
421 The block size may be set with option
423 or environment variable
425 Numbers of blocks in the output will have been rounded up so the
426 numbers of bytes is at least as many as used by the corresponding
427 file system blocks (which might have a different size).
429 The file mode printed under the
431 option consists of the
432 entry type and the permissions.
433 The entry type character describes the type of file, as
436 .Bl -tag -width 4n -offset indent -compact
442 Character special file.
455 The next three fields
456 are three characters each:
458 group permissions, and
460 Each field has three character positions:
461 .Bl -enum -offset indent
465 the file is readable; if
471 the file is writable; if
475 The first of the following that applies:
476 .Bl -tag -width 4n -offset indent
478 If in the owner permissions, the file is not executable and
479 set-user-ID mode is set.
480 If in the group permissions, the file is not executable
481 and set-group-ID mode is set.
483 If in the owner permissions, the file is executable
484 and set-user-ID mode is set.
485 If in the group permissions, the file is executable
486 and setgroup-ID mode is set.
488 The file is executable or the directory is
491 The file is neither readable, writable, executable,
492 nor set-user-ID nor set-group-ID mode, nor sticky.
496 These next two apply only to the third character in the last group
498 .Bl -tag -width 4n -offset indent
500 The sticky bit is set
503 but not execute or search permission.
509 The sticky bit is set (mode
511 and is searchable or executable.
519 The next field contains a
522 character if the file has an ACL, or a
528 utility does not show the actual ACL;
533 The following environment variables affect the execution of
535 .Bl -tag -width ".Ev CLICOLOR_FORCE"
537 If this is set, its value, rounded up to 512 or down to a
538 multiple of 512, will be used as the block size in bytes by the
545 subsection for more information.
549 color sequences to distinguish file types.
553 In addition to the file types mentioned in the
555 option some extra attributes (setuid bit set, etc.) are also displayed.
556 The colorization is dependent on a terminal type with the proper
561 console has the proper capabilities,
562 but to display the colors in an
567 variable must be set to
569 Other terminal types may require similar adjustments.
571 is silently disabled if the output is not directed to a terminal
575 .It Ev CLICOLOR_FORCE
576 Color sequences are normally disabled if the output is not directed to
578 This can be overridden by setting this variable.
581 variable still needs to reference a color capable terminal however
582 otherwise it is not possible to determine which color sequences to
585 If this variable contains a string representing a
586 decimal integer, it is used as the
587 column position width for displaying
588 multiple-text-column output.
591 utility calculates how
592 many pathname text columns to display
593 based on the width provided.
599 The locale to use when determining the order of day and month in the long
604 for more information.
606 The value of this variable describes what color to use for which
607 attribute when colors are enabled with
609 This string is a concatenation of pairs of the format
613 is the foreground color and
615 is the background color.
617 The color designators are as follows:
619 .Bl -tag -width 4n -offset indent -compact
637 bold black, usually shows up as dark grey
643 bold brown, usually shows up as yellow
651 bold light grey; looks like bright white
653 default foreground or background
656 Note that the above are standard
659 The actual display may differ
660 depending on the color capabilities of the terminal in use.
662 The order of the attributes are as follows:
664 .Bl -enum -offset indent -compact
680 executable with setuid bit set
682 executable with setgid bit set
684 directory writable to others, with sticky bit
686 directory writable to others, without sticky bit
690 .Qq "exfxcxdxbxegedabagacad" ,
691 i.e., blue foreground and
692 default background for regular directories, black foreground and red
693 background for setuid executables, etc.
695 If this variable is set, it is considered to be a
696 colon-delimited list of minimum column widths.
698 and insufficient widths are ignored (thus zero signifies
699 a dynamically sized column).
700 Not all columns have changeable widths.
702 in order: inode, block count, number of links, user name,
703 group name, flags, file size, file name.
705 If this variable is set, the
707 option sorts the names of files with the same modification timestamp in the same
708 sense as the time sort.
709 See the description of the
711 option for more details.
715 functionality depends on a terminal type with color capabilities.
717 The timezone to use when displaying dates.
720 for more information.
725 List the contents of the current working directory in long format:
729 In addition to listing the contents of the current working directory in
730 long format, show inode numbers, file flags (see
732 and suffix each filename with a symbol representing its file type:
738 sorting the output such that the mostly recently modified entries are
741 .Dl $ ls -lt /var/log
743 The group field is now automatically included in the long listing for
744 files in order to be compatible with the
762 With the exception of options
771 The ACL support is compatible with
774 .Pq Dq Tn POSIX Ns .2c
783 To maintain backward compatibility, the relationships between the many
784 options are quite complex.
786 The exception mentioned in the
788 option description might be a feature that was
789 based on the fact that single-column output
790 usually goes to something other than a terminal.
791 It is debatable whether this is a design bug.
794 mandates opposite sort orders for files with the same timestamp when