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 ABCFGHILPRSTUWZabcdfghiklmnopqrstuwx1
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 Automatically set for the super-user unless
79 Force printing of non-printable characters (as defined by
81 and current locale settings) in file names as
85 is the numeric value of the character in octal.
87 Force multi-column output; this is the default when output is to a terminal.
91 immediately after each pathname that is a directory,
94 after each that is executable,
97 after each symbolic link,
109 Enable colorized output.
110 This option is equivalent to defining
115 Symbolic links on the command line are followed.
116 This option is assumed if
121 options are specified.
125 from being automatically set for the super-user.
127 If argument is a symbolic link, list the file or directory the link references
128 rather than the link itself.
129 This option cancels the
133 If argument is a symbolic link, list the link itself rather than the
134 object the link references.
135 This option cancels the
141 Recursively list subdirectories encountered.
143 Sort by size (largest file first) before sorting the operands in
144 lexicographical order.
150 option, display complete time information for the file, including
151 month, day, hour, minute, second, and year.
153 Use time when file was created for sorting or printing.
155 Display whiteouts when scanning directories.
157 Display each file's MAC label; see
160 Include directory entries whose names begin with a
168 escape codes whenever possible.
170 Use time when file status was last changed for sorting or printing.
172 Directories are listed as plain files (not searched recursively).
174 Output is not sorted.
176 This option is deprecated and is only available for compatibility
179 it was used to display the group name in the long
185 option, use unit suffixes: Byte, Kilobyte, Megabyte, Gigabyte, Terabyte
186 and Petabyte in order to reduce the number of digits to four or fewer
187 using base 2 for sizes.
189 For each file, print the file's file serial number (inode number).
191 This has the same effect as setting environment variable
193 to 1024, except that it also nullifies any
197 (The lowercase letter
199 List files in the long format, as described in the
203 Stream output format; list files across the page, separated by commas.
205 Display user and group IDs numerically rather than converting to a user
206 or group name in a long
210 Include the file flags in a long
216 after each filename if that file is a directory.
218 Force printing of non-graphic characters in file names as
221 this is the default when output is to a terminal.
223 Reverse the order of the sort.
225 Display the number of blocks used in the file system by each file.
226 Block sizes and directory totals are handled as described in
228 subsection below, except (if the long format is not also requested)
229 the directory totals are not output when the output is in a
230 single column, even if multi-column output is requested.
232 Sort by time modified (most recently modified
233 first) before sorting the operands in lexicographical
236 Use time of last access,
237 instead of last modification
238 of the file for sorting
243 Force raw printing of non-printable characters.
245 when output is not to a terminal.
249 except that the multi-column output is produced with entries sorted
250 across, rather than down, the columns.
256 This is the default when
257 output is not to a terminal.
264 options all override each other; the last one specified determines
271 options all override each other; the last one specified determines
278 options override each other; the last one specified determines
285 options all override each other; the last one specified determines
286 the format used for non-printable characters.
292 options all override each other (either partially or fully); they
293 are applied in the order specified.
297 lists one entry per line to standard
298 output; the exceptions are to terminals or when the
302 options are specified.
304 File information is displayed with one or more
306 separating the information associated with the
314 option is given, the following information
315 is displayed for each file:
317 number of links, owner name, group name,
319 number of bytes in the file, abbreviated
320 month, day-of-month file was last modified,
321 hour file last modified, minute file last
322 modified, and the pathname.
324 If the modification time of the file is more than 6 months
325 in the past or future, then the year of the last modification
326 is displayed in place of the hour and minute fields.
328 If the owner or group names are not a known user or group name,
332 the numeric ID's are displayed.
334 If the file is a character special or block special file,
335 the major and minor device numbers for the file are displayed
337 If the file is a symbolic link the pathname of the
338 linked-to file is preceded by
341 The listing of a directory's contents is preceded
342 by a labeled total number of blocks used in the file system by the files
343 which are listed as the directory's contents
344 (which may or may not include
348 and other files which start with a dot, depending on other options).
350 The default block size is 512 bytes.
351 The block size may be set with option
353 or environment variable
355 Numbers of blocks in the output will have been rounded up so the
356 numbers of bytes is at least as many as used by the corresponding
357 file system blocks (which might have a different size).
359 The file mode printed under the
361 option consists of the
362 entry type and the permissions.
363 The entry type character describes the type of file, as
366 .Bl -tag -width 4n -offset indent -compact
370 Character special file.
383 The next three fields
384 are three characters each:
386 group permissions, and
388 Each field has three character positions:
389 .Bl -enum -offset indent
393 the file is readable; if
399 the file is writable; if
403 The first of the following that applies:
404 .Bl -tag -width 4n -offset indent
406 If in the owner permissions, the file is not executable and
407 set-user-ID mode is set.
408 If in the group permissions, the file is not executable
409 and set-group-ID mode is set.
411 If in the owner permissions, the file is executable
412 and set-user-ID mode is set.
413 If in the group permissions, the file is executable
414 and setgroup-ID mode is set.
416 The file is executable or the directory is
419 The file is neither readable, writable, executable,
420 nor set-user-ID nor set-group-ID mode, nor sticky.
424 These next two apply only to the third character in the last group
426 .Bl -tag -width 4n -offset indent
428 The sticky bit is set
431 but not execute or search permission.
437 The sticky bit is set (mode
439 and is searchable or executable.
447 The next field contains a
450 character if the file has an ACL, or a
456 utility does not show the actual ACL;
461 The following environment variables affect the execution of
463 .Bl -tag -width ".Ev CLICOLOR_FORCE"
465 If this is set, its value, rounded up to 512 or down to a
466 multiple of 512, will be used as the block size in bytes by the
473 subsection for more information.
477 color sequences to distinguish file types.
481 In addition to the file types mentioned in the
483 option some extra attributes (setuid bit set, etc.) are also displayed.
484 The colorization is dependent on a terminal type with the proper
489 console has the proper capabilities,
490 but to display the colors in an
495 variable must be set to
497 Other terminal types may require similar adjustments.
499 is silently disabled if the output is not directed to a terminal
503 .It Ev CLICOLOR_FORCE
504 Color sequences are normally disabled if the output is not directed to
506 This can be overridden by setting this flag.
509 variable still needs to reference a color capable terminal however
510 otherwise it is not possible to determine which color sequences to
513 If this variable contains a string representing a
514 decimal integer, it is used as the
515 column position width for displaying
516 multiple-text-column output.
519 utility calculates how
520 many pathname text columns to display
521 based on the width provided.
527 The locale to use when determining the order of day and month in the long
532 for more information.
534 The value of this variable describes what color to use for which
535 attribute when colors are enabled with
537 This string is a concatenation of pairs of the format
541 is the foreground color and
543 is the background color.
545 The color designators are as follows:
547 .Bl -tag -width 4n -offset indent -compact
565 bold black, usually shows up as dark grey
571 bold brown, usually shows up as yellow
579 bold light grey; looks like bright white
581 default foreground or background
584 Note that the above are standard
587 The actual display may differ
588 depending on the color capabilities of the terminal in use.
590 The order of the attributes are as follows:
592 .Bl -enum -offset indent -compact
608 executable with setuid bit set
610 executable with setgid bit set
612 directory writable to others, with sticky bit
614 directory writable to others, without sticky bit
618 .Qq "exfxcxdxbxegedabagacad" ,
619 i.e., blue foreground and
620 default background for regular directories, black foreground and red
621 background for setuid executables, etc.
623 If this variable is set, it is considered to be a
624 colon-delimited list of minimum column widths.
626 and insufficient widths are ignored (thus zero signifies
627 a dynamically sized column).
628 Not all columns have changeable widths.
630 in order: inode, block count, number of links, user name,
631 group name, flags, file size, file name.
635 functionality depends on a terminal type with color capabilities.
637 The timezone to use when displaying dates.
640 for more information.
645 The group field is now automatically included in the long listing for
646 files in order to be compatible with the
661 With the exception of options
670 The ACL support is compatible with
673 .Pq Dq Tn POSIX Ns .2c
682 To maintain backward compatibility, the relationships between the many
683 options are quite complex.
685 The exception mentioned in the
687 option description might be a feature that was
688 based on the fact that single-column output
689 usually goes to something other than a terminal.
690 It is debatable whether this is a design bug.