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
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
134 Symbolic links on the command line are followed.
135 This option is assumed if
140 options are specified.
144 from being automatically set for the super-user.
146 If argument is a symbolic link, list the file or directory the link references
147 rather than the link itself.
148 This option cancels the
152 If argument is a symbolic link, list the link itself rather than the
153 object the link references.
154 This option cancels the
160 Recursively list subdirectories encountered.
162 Sort by size (largest file first) before sorting the operands in
163 lexicographical order.
165 When printing in the long
167 format, display complete time information for the file, including
168 month, day, hour, minute, second, and year.
171 option gives even more control over the output format.
173 Use time when file was created for sorting or printing.
175 Display whiteouts when scanning directories.
177 Display each file's MAC label; see
180 Include directory entries whose names begin with a
188 escape codes whenever possible.
190 Use time when file status was last changed for sorting or printing.
192 Directories are listed as plain files (not searched recursively).
194 Output is not sorted.
196 This option is deprecated and is only available for compatibility
199 it was used to display the group name in the long
205 option, use unit suffixes: Byte, Kilobyte, Megabyte, Gigabyte, Terabyte
206 and Petabyte in order to reduce the number of digits to four or fewer
207 using base 2 for sizes.
209 For each file, print the file's file serial number (inode number).
211 This has the same effect as setting environment variable
213 to 1024, except that it also nullifies any
217 (The lowercase letter
219 List files in the long format, as described in the
223 Stream output format; list files across the page, separated by commas.
225 Display user and group IDs numerically rather than converting to a user
226 or group name in a long
230 Include the file flags in a long
236 after each filename if that file is a directory.
238 Force printing of non-graphic characters in file names as
241 this is the default when output is to a terminal.
243 Reverse the order of the sort.
245 Display the number of blocks used in the file system by each file.
246 Block sizes and directory totals are handled as described in
248 subsection below, except (if the long format is not also requested)
249 the directory totals are not output when the output is in a
250 single column, even if multi-column output is requested.
252 Sort by time modified (most recently modified
253 first) before sorting the operands in lexicographical
256 Use time of last access,
257 instead of last modification
258 of the file for sorting
263 Force raw printing of non-printable characters.
265 when output is not to a terminal.
269 except that the multi-column output is produced with entries sorted
270 across, rather than down, the columns.
276 This is the default when
277 output is not to a terminal.
284 options all override each other; the last one specified determines
291 options all override each other; the last one specified determines
298 options override each other; the last one specified determines
305 options all override each other; the last one specified determines
306 the format used for non-printable characters.
312 options all override each other (either partially or fully); they
313 are applied in the order specified.
317 lists one entry per line to standard
318 output; the exceptions are to terminals or when the
322 options are specified.
324 File information is displayed with one or more
326 separating the information associated with the
334 option is given, the following information
335 is displayed for each file:
337 number of links, owner name, group name,
339 number of bytes in the file, abbreviated
340 month, day-of-month file was last modified,
341 hour file last modified, minute file last
342 modified, and the pathname.
344 If the modification time of the file is more than 6 months
345 in the past or future, and the
350 then the year of the last modification
351 is displayed in place of the hour and minute fields.
353 If the owner or group names are not a known user or group name,
357 the numeric ID's are displayed.
359 If the file is a character special or block special file,
360 the major and minor device numbers for the file are displayed
362 If the file is a symbolic link the pathname of the
363 linked-to file is preceded by
366 The listing of a directory's contents is preceded
367 by a labeled total number of blocks used in the file system by the files
368 which are listed as the directory's contents
369 (which may or may not include
373 and other files which start with a dot, depending on other options).
375 The default block size is 512 bytes.
376 The block size may be set with option
378 or environment variable
380 Numbers of blocks in the output will have been rounded up so the
381 numbers of bytes is at least as many as used by the corresponding
382 file system blocks (which might have a different size).
384 The file mode printed under the
386 option consists of the
387 entry type and the permissions.
388 The entry type character describes the type of file, as
391 .Bl -tag -width 4n -offset indent -compact
397 Character special file.
410 The next three fields
411 are three characters each:
413 group permissions, and
415 Each field has three character positions:
416 .Bl -enum -offset indent
420 the file is readable; if
426 the file is writable; if
430 The first of the following that applies:
431 .Bl -tag -width 4n -offset indent
433 If in the owner permissions, the file is not executable and
434 set-user-ID mode is set.
435 If in the group permissions, the file is not executable
436 and set-group-ID mode is set.
438 If in the owner permissions, the file is executable
439 and set-user-ID mode is set.
440 If in the group permissions, the file is executable
441 and setgroup-ID mode is set.
443 The file is executable or the directory is
446 The file is neither readable, writable, executable,
447 nor set-user-ID nor set-group-ID mode, nor sticky.
451 These next two apply only to the third character in the last group
453 .Bl -tag -width 4n -offset indent
455 The sticky bit is set
458 but not execute or search permission.
464 The sticky bit is set (mode
466 and is searchable or executable.
474 The next field contains a
477 character if the file has an ACL, or a
483 utility does not show the actual ACL;
488 The following environment variables affect the execution of
490 .Bl -tag -width ".Ev CLICOLOR_FORCE"
492 If this is set, its value, rounded up to 512 or down to a
493 multiple of 512, will be used as the block size in bytes by the
500 subsection for more information.
504 color sequences to distinguish file types.
508 In addition to the file types mentioned in the
510 option some extra attributes (setuid bit set, etc.) are also displayed.
511 The colorization is dependent on a terminal type with the proper
516 console has the proper capabilities,
517 but to display the colors in an
522 variable must be set to
524 Other terminal types may require similar adjustments.
526 is silently disabled if the output is not directed to a terminal
530 .It Ev CLICOLOR_FORCE
531 Color sequences are normally disabled if the output is not directed to
533 This can be overridden by setting this flag.
536 variable still needs to reference a color capable terminal however
537 otherwise it is not possible to determine which color sequences to
540 If this variable contains a string representing a
541 decimal integer, it is used as the
542 column position width for displaying
543 multiple-text-column output.
546 utility calculates how
547 many pathname text columns to display
548 based on the width provided.
554 The locale to use when determining the order of day and month in the long
559 for more information.
561 The value of this variable describes what color to use for which
562 attribute when colors are enabled with
564 This string is a concatenation of pairs of the format
568 is the foreground color and
570 is the background color.
572 The color designators are as follows:
574 .Bl -tag -width 4n -offset indent -compact
592 bold black, usually shows up as dark grey
598 bold brown, usually shows up as yellow
606 bold light grey; looks like bright white
608 default foreground or background
611 Note that the above are standard
614 The actual display may differ
615 depending on the color capabilities of the terminal in use.
617 The order of the attributes are as follows:
619 .Bl -enum -offset indent -compact
635 executable with setuid bit set
637 executable with setgid bit set
639 directory writable to others, with sticky bit
641 directory writable to others, without sticky bit
645 .Qq "exfxcxdxbxegedabagacad" ,
646 i.e., blue foreground and
647 default background for regular directories, black foreground and red
648 background for setuid executables, etc.
650 If this variable is set, it is considered to be a
651 colon-delimited list of minimum column widths.
653 and insufficient widths are ignored (thus zero signifies
654 a dynamically sized column).
655 Not all columns have changeable widths.
657 in order: inode, block count, number of links, user name,
658 group name, flags, file size, file name.
662 functionality depends on a terminal type with color capabilities.
664 The timezone to use when displaying dates.
667 for more information.
672 The group field is now automatically included in the long listing for
673 files in order to be compatible with the
690 With the exception of options
699 The ACL support is compatible with
702 .Pq Dq Tn POSIX Ns .2c
711 To maintain backward compatibility, the relationships between the many
712 options are quite complex.
714 The exception mentioned in the
716 option description might be a feature that was
717 based on the fact that single-column output
718 usually goes to something other than a terminal.
719 It is debatable whether this is a design bug.