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 ABCFGHLPRSTWZabcdfghiklmnopqrstuwx1
46 For each operand that names a
51 displays its name as well as any requested,
52 associated information.
53 For each operand that names a
57 displays the names of files contained
58 within that directory, as well as any requested, associated
61 If no operands are given, the contents of the current
62 directory are displayed.
63 If more than one operand is given,
64 non-directory operands are displayed first; directory
65 and non-directory operands are sorted separately and in
66 lexicographical order.
68 The following options are available:
69 .Bl -tag -width indent
71 List all entries except for
75 Always set for the super-user.
77 Force printing of non-printable characters (as defined by
79 and current locale settings) in file names as
83 is the numeric value of the character in octal.
85 Force multi-column output; this is the default when output is to a terminal.
89 immediately after each pathname that is a directory,
92 after each that is executable,
95 after each symbolic link,
107 Enable colorized output.
108 This option is equivalent to defining
113 Symbolic links on the command line are followed.
114 This option is assumed if
119 options are specified.
121 If argument is a symbolic link, list the file or directory the link references
122 rather than the link itself.
123 This option cancels the
127 If argument is a symbolic link, list the link itself rather than the
128 object the link references.
129 This option cancels the
135 Recursively list subdirectories encountered.
137 Sort by size (largest file first) before sorting the operands in
138 lexicographical order.
144 option, display complete time information for the file, including
145 month, day, hour, minute, second, and year.
147 Display whiteouts when scanning directories.
149 Display each file's MAC label; see
152 Include directory entries whose names begin with a
160 escape codes whenever possible.
162 Use time when file status was last changed for sorting or printing.
164 Directories are listed as plain files (not searched recursively).
166 Output is not sorted.
168 This option is deprecated and is only available for compatibility
171 it was used to display the group name in the long
177 option, use unit suffixes: Byte, Kilobyte, Megabyte, Gigabyte, Terabyte
178 and Petabyte in order to reduce the number of digits to four or fewer
179 using base 2 for sizes.
181 For each file, print the file's file serial number (inode number).
183 This has the same effect as setting environment variable
185 to 1024, except that it also nullifies any
189 (The lowercase letter
191 List files in the long format, as described in the
195 Stream output format; list files across the page, separated by commas.
197 Display user and group IDs numerically rather than converting to a user
198 or group name in a long
202 Include the file flags in a long
208 after each filename if that file is a directory.
210 Force printing of non-graphic characters in file names as
213 this is the default when output is to a terminal.
215 Reverse the order of the sort.
217 Display the number of blocks used in the file system by each file.
218 Block sizes and directory totals are handled as described in
220 subsection below, except (if the long format is not also requested)
221 the directory totals are not output when the output is in a
222 single column, even if multi-column output is requested.
224 Sort by time modified (most recently modified
225 first) before sorting the operands in lexicographical
228 Use time of last access,
229 instead of last modification
230 of the file for sorting
235 Force raw printing of non-printable characters.
237 when output is not to a terminal.
241 except that the multi-column output is produced with entries sorted
242 across, rather than down, the columns.
248 This is the default when
249 output is not to a terminal.
256 options all override each other; the last one specified determines
263 options override each other; the last one specified determines
270 options all override each other; the last one specified determines
271 the format used for non-printable characters.
277 options all override each other (either partially or fully); they
278 are applied in the order specified.
282 lists one entry per line to standard
283 output; the exceptions are to terminals or when the
287 options are specified.
289 File information is displayed with one or more
291 separating the information associated with the
299 option is given, the following information
300 is displayed for each file:
302 number of links, owner name, group name,
304 number of bytes in the file, abbreviated
305 month, day-of-month file was last modified,
306 hour file last modified, minute file last
307 modified, and the pathname.
309 If the modification time of the file is more than 6 months
310 in the past or future, then the year of the last modification
311 is displayed in place of the hour and minute fields.
313 If the owner or group names are not a known user or group name,
317 the numeric ID's are displayed.
319 If the file is a character special or block special file,
320 the major and minor device numbers for the file are displayed
322 If the file is a symbolic link the pathname of the
323 linked-to file is preceded by
326 The listing of a directory's contents is preceded
327 by a labeled total number of blocks used in the file system by the files
328 which are listed as the directory's contents
329 (which may or may not include
333 and other files which start with a dot, depending on other options).
335 The default block size is 512 bytes.
336 The block size may be set with option
338 or environment variable
340 Numbers of blocks in the output will have been rounded up so the
341 numbers of bytes is at least as many as used by the corresponding
342 file system blocks (which might have a different size).
344 The file mode printed under the
346 option consists of the
347 entry type and the permissions.
348 The entry type character describes the type of file, as
351 .Bl -tag -width 4n -offset indent -compact
355 Character special file.
368 The next three fields
369 are three characters each:
371 group permissions, and
373 Each field has three character positions:
374 .Bl -enum -offset indent
378 the file is readable; if
384 the file is writable; if
388 The first of the following that applies:
389 .Bl -tag -width 4n -offset indent
391 If in the owner permissions, the file is not executable and
392 set-user-ID mode is set.
393 If in the group permissions, the file is not executable
394 and set-group-ID mode is set.
396 If in the owner permissions, the file is executable
397 and set-user-ID mode is set.
398 If in the group permissions, the file is executable
399 and setgroup-ID mode is set.
401 The file is executable or the directory is
404 The file is neither readable, writable, executable,
405 nor set-user-ID nor set-group-ID mode, nor sticky.
409 These next two apply only to the third character in the last group
411 .Bl -tag -width 4n -offset indent
413 The sticky bit is set
416 but not execute or search permission.
422 The sticky bit is set (mode
424 and is searchable or executable.
432 The next field contains a
435 character if the file has an ACL, or a
441 utility does not show the actual ACL;
446 The following environment variables affect the execution of
448 .Bl -tag -width ".Ev CLICOLOR_FORCE"
450 If this is set, its value, rounded up to 512 or down to a
451 multiple of 512, will be used as the block size in bytes by the
458 subsection for more information.
462 color sequences to distinguish file types.
466 In addition to the file types mentioned in the
468 option some extra attributes (setuid bit set, etc.) are also displayed.
469 The colorization is dependent on a terminal type with the proper
474 console has the proper capabilities,
475 but to display the colors in an
480 variable must be set to
482 Other terminal types may require similar adjustments.
484 is silently disabled if the output is not directed to a terminal
488 .It Ev CLICOLOR_FORCE
489 Color sequences are normally disabled if the output is not directed to
491 This can be overridden by setting this flag.
494 variable still needs to reference a color capable terminal however
495 otherwise it is not possible to determine which color sequences to
498 If this variable contains a string representing a
499 decimal integer, it is used as the
500 column position width for displaying
501 multiple-text-column output.
504 utility calculates how
505 many pathname text columns to display
506 based on the width provided.
512 The locale to use when determining the order of day and month in the long
517 for more information.
519 The value of this variable describes what color to use for which
520 attribute when colors are enabled with
522 This string is a concatenation of pairs of the format
526 is the foreground color and
528 is the background color.
530 The color designators are as follows:
532 .Bl -tag -width 4n -offset indent -compact
550 bold black, usually shows up as dark grey
556 bold brown, usually shows up as yellow
564 bold light grey; looks like bright white
566 default foreground or background
569 Note that the above are standard
572 The actual display may differ
573 depending on the color capabilities of the terminal in use.
575 The order of the attributes are as follows:
577 .Bl -enum -offset indent -compact
593 executable with setuid bit set
595 executable with setgid bit set
597 directory writable to others, with sticky bit
599 directory writable to others, without sticky bit
603 .Qq "exfxcxdxbxegedabagacad" ,
604 i.e., blue foreground and
605 default background for regular directories, black foreground and red
606 background for setuid executables, etc.
608 If this variable is set, it is considered to be a
609 colon-delimited list of minimum column widths.
611 and insufficient widths are ignored (thus zero signifies
612 a dynamically sized column).
613 Not all columns have changeable widths.
615 in order: inode, block count, number of links, user name,
616 group name, flags, file size, file name.
620 functionality depends on a terminal type with color capabilities.
622 The timezone to use when displaying dates.
625 for more information.
630 The group field is now automatically included in the long listing for
631 files in order to be compatible with the
646 With the exception of options
656 The ACL support is compatible with
659 .Pq Dq Tn POSIX Ns .2c
668 To maintain backward compatibility, the relationships between the many
669 options are quite complex.
671 The exception mentioned in the
673 option description might be a feature that was
674 based on the fact that single-column output
675 usually goes to something other than a terminal.
676 It is debatable whether this is a design bug.