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).
185 option is specified, print the file size allocation in kilobytes,
187 This option overrides the environment variable
191 is mutually exclusive to
198 (The lowercase letter
202 A total sum (in blocks, see the
204 option for the block size unit) for all the file
205 sizes is output on a line before the long listing.
207 Stream output format; list files across the page, separated by commas.
209 Display user and group IDs numerically rather than converting to a user
210 or group name in a long
214 Include the file flags in a long
220 after each filename if that file is a directory.
222 Force printing of non-graphic characters in file names as
225 this is the default when output is to a terminal.
227 Reverse the order of the sort.
229 Display the number of file system blocks actually used by each file, in units
230 of 512 bytes, where partial units are rounded up to the next integer value.
231 A total sum for all the file
232 sizes is output on a line before the listing.
233 The environment variable
235 overrides the unit size of 512 bytes.
237 Sort by time modified (most recently modified
238 first) before sorting the operands in lexicographical
241 Use time of last access,
242 instead of last modification
243 of the file for sorting
248 Force raw printing of non-printable characters.
250 when output is not to a terminal.
254 except that the multi-column output is produced with entries sorted
255 across, rather than down, the columns.
261 This is the default when
262 output is not to a terminal.
269 options all override each other; the last one specified determines
276 options override each other; the last one specified determines
283 options all override each other; the last one specified determines
284 the format used for non-printable characters.
290 options all override each other (either partially or fully); they
291 are applied in the order specified.
295 lists one entry per line to standard
296 output; the exceptions are to terminals or when the
300 options are specified.
302 File information is displayed with one or more
304 separating the information associated with the
312 option is given, the following information
313 is displayed for each file:
315 number of links, owner name, group name,
317 number of bytes in the file, abbreviated
318 month, day-of-month file was last modified,
319 hour file last modified, minute file last
320 modified, and the pathname.
321 In addition, for each directory whose contents are displayed, the total
322 number of 512-byte blocks used by the files in the directory is displayed
323 on a line by itself immediately before the information for the files in the
326 If the modification time of the file is more than 6 months
327 in the past or future, then the year of the last modification
328 is displayed in place of the hour and minute fields.
330 If the owner or group names are not a known user or group name,
334 the numeric ID's are displayed.
336 If the file is a character special or block special file,
337 the major and minor device numbers for the file are displayed
339 If the file is a symbolic link the pathname of the
340 linked-to file is preceded by
343 The file mode printed under the
345 option consists of the
346 entry type and the permissions.
347 The entry type character describes the type of file, as
350 .Bl -tag -width 4n -offset indent -compact
354 Character special file.
367 The next three fields
368 are three characters each:
370 group permissions, and
372 Each field has three character positions:
373 .Bl -enum -offset indent
377 the file is readable; if
383 the file is writable; if
387 The first of the following that applies:
388 .Bl -tag -width 4n -offset indent
390 If in the owner permissions, the file is not executable and
391 set-user-ID mode is set.
392 If in the group permissions, the file is not executable
393 and set-group-ID mode is set.
395 If in the owner permissions, the file is executable
396 and set-user-ID mode is set.
397 If in the group permissions, the file is executable
398 and setgroup-ID mode is set.
400 The file is executable or the directory is
403 The file is neither readable, writable, executable,
404 nor set-user-ID nor set-group-ID mode, nor sticky.
408 These next two apply only to the third character in the last group
410 .Bl -tag -width 4n -offset indent
412 The sticky bit is set
415 but not execute or search permission.
421 The sticky bit is set (mode
423 and is searchable or executable.
431 The next field contains a
434 character if the file has an ACL, or a
440 utility does not show the actual ACL;
445 The following environment variables affect the execution of
447 .Bl -tag -width ".Ev CLICOLOR_FORCE"
449 If the environment variable
451 is set, the block counts
454 will be displayed in units of that size block.
458 color sequences to distinguish file types.
462 In addition to the file types mentioned in the
464 option some extra attributes (setuid bit set, etc.) are also displayed.
465 The colorization is dependent on a terminal type with the proper
470 console has the proper capabilities,
471 but to display the colors in an
476 variable must be set to
478 Other terminal types may require similar adjustments.
480 is silently disabled if the output is not directed to a terminal
484 .It Ev CLICOLOR_FORCE
485 Color sequences are normally disabled if the output is not directed to
487 This can be overridden by setting this flag.
490 variable still needs to reference a color capable terminal however
491 otherwise it is not possible to determine which color sequences to
494 If this variable contains a string representing a
495 decimal integer, it is used as the
496 column position width for displaying
497 multiple-text-column output.
500 utility calculates how
501 many pathname text columns to display
502 based on the width provided.
508 The locale to use when determining the order of day and month in the long
513 for more information.
515 The value of this variable describes what color to use for which
516 attribute when colors are enabled with
518 This string is a concatenation of pairs of the format
522 is the foreground color and
524 is the background color.
526 The color designators are as follows:
528 .Bl -tag -width 4n -offset indent -compact
546 bold black, usually shows up as dark grey
552 bold brown, usually shows up as yellow
560 bold light grey; looks like bright white
562 default foreground or background
565 Note that the above are standard
568 The actual display may differ
569 depending on the color capabilities of the terminal in use.
571 The order of the attributes are as follows:
573 .Bl -enum -offset indent -compact
589 executable with setuid bit set
591 executable with setgid bit set
593 directory writable to others, with sticky bit
595 directory writable to others, without sticky bit
599 .Qq "exfxcxdxbxegedabagacad" ,
600 i.e., blue foreground and
601 default background for regular directories, black foreground and red
602 background for setuid executables, etc.
604 If this variable is set, it is considered to be a
605 colon-delimited list of minimum column widths.
607 and insufficient widths are ignored (thus zero signifies
608 a dynamically sized column).
609 Not all columns have changeable widths.
611 in order: inode, block count, number of links, user name,
612 group name, flags, file size, file name.
616 functionality depends on a terminal type with color capabilities.
618 The timezone to use when displaying dates.
621 for more information.
626 The group field is now automatically included in the long listing for
627 files in order to be compatible with the
642 With the exception of options
652 The ACL support is compatible with
655 .Pq Dq Tn POSIX Ns .2c
664 To maintain backward compatibility, the relationships between the many
665 options are quite complex.