1 .\" Copyright (c) 1980, 1990, 1991, 1993, 1994
2 .\" The Regents of the University of California. All rights reserved.
4 .\" This code is derived from software contributed to Berkeley by
5 .\" the Institute of Electrical and Electronics Engineers, Inc.
7 .\" Redistribution and use in source and binary forms, with or without
8 .\" modification, are permitted provided that the following conditions
10 .\" 1. Redistributions of source code must retain the above copyright
11 .\" notice, this list of conditions and the following disclaimer.
12 .\" 2. Redistributions in binary form must reproduce the above copyright
13 .\" notice, this list of conditions and the following disclaimer in the
14 .\" documentation and/or other materials provided with the distribution.
15 .\" 3. All advertising materials mentioning features or use of this software
16 .\" must display the following acknowledgment:
17 .\" This product includes software developed by the University of
18 .\" California, Berkeley and its contributors.
19 .\" 4. Neither the name of the University nor the names of its contributors
20 .\" may be used to endorse or promote products derived from this software
21 .\" without specific prior written permission.
23 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
24 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
25 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
26 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
27 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
28 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
29 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
30 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
31 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
32 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
35 .\" @(#)ls.1 8.7 (Berkeley) 7/29/94
36 .\" $FreeBSD: src/bin/ls/ls.1,v 1.69 2002/08/21 17:32:34 trhodes Exp $
43 .Nd list directory contents
46 .Op Fl ABCFGHLOPRSTUW@abcdefghiklmnopqrstuwx1
49 For each operand that names a
54 displays its name as well as any requested,
55 associated information.
56 For each operand that names a
60 displays the names of files contained
61 within that directory, as well as any requested, associated
64 If no operands are given, the contents of the current
65 directory are displayed.
66 If more than one operand is given,
67 non-directory operands are displayed first; directory
68 and non-directory operands are sorted separately and in
69 lexicographical order.
71 The following options are available:
72 .Bl -tag -width indent
74 Display extended attribute keys and sizes in long
82 This is the default when
83 output is not to a terminal.
85 List all entries except for
89 Always set for the super-user.
91 Include directory entries whose names begin with a
95 Force printing of non-printable characters (as defined by
97 and current locale settings) in file names as
101 is the numeric value of the character in octal.
107 escape codes whenever possible.
109 Force multi-column output; this is the default when output is to a terminal.
111 Use time when file status was last changed for sorting
116 Directories are listed as plain files (not searched recursively).
118 Print the Access Control List (ACL) associated with the file, if present, in long
124 immediately after each pathname that is a directory,
127 after each that is executable,
130 after each symbolic link,
142 Output is not sorted.
143 This option turns on the
147 Enable colorized output.
148 This option is equivalent to defining
153 This option is only available for compatibility with POSIX;
154 it is used to display the group name in the long
156 format output (the owner name is suppressed).
158 Symbolic links on the command line are followed.
159 This option is assumed if
164 options are specified.
168 option, use unit suffixes: Byte, Kilobyte, Megabyte, Gigabyte, Terabyte
169 and Petabyte in order to reduce the number of digits to three or less
170 using base 2 for sizes.
172 For each file, print the file's file serial number (inode number).
176 option is specified, print the file size allocation in kilobytes,
178 This option overrides the environment variable
181 Follow all symbolic links to final target and list the file or directory the link references
182 rather than the link itself.
183 This option cancels the
187 (The lowercase letter
191 If the output is to a terminal, a total sum for all the file
192 sizes is output on a line before the long listing.
194 Stream output format; list files across the page, separated by commas.
196 Display user and group IDs numerically,
197 rather than converting to a user or group name in a long
200 This option turns on the
204 Include the file flags in a long
208 List in long format, but omit the group id.
210 If argument is a symbolic link, list the link itself rather than the
211 object the link references.
212 This option cancels the
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 Recursively list subdirectories encountered.
229 Reverse the order of the sort to get reverse
230 lexicographical order or the oldest entries first (or largest files
231 last, if combined with sort by size
235 Display the number of file system blocks actually used by each file, in units
236 of 512 bytes, where partial units are rounded up to the next integer value.
237 If the output is to a terminal, a total sum for all the file
238 sizes is output on a line before the listing.
239 The environment variable
241 overrides the unit size of 512 bytes.
247 option, display complete time information for the file, including
248 month, day, hour, minute, second, and year.
250 Sort by time modified (most recently modified
251 first) before sorting the operands by lexicographical
254 Use time of last access,
255 instead of last modification
256 of the file for sorting
261 Use time of file creation, instead of last modification for sorting
266 Force unedited printing of non-graphic characters; this is the default when
267 output is not to a terminal.
269 Display whiteouts when scanning directories.
273 Force raw printing of non-printable characters.
275 when output is not to a terminal.
279 except that the multi-column output is produced with entries sorted
280 across, rather than down, the columns.
287 options all override each other;
288 the last one specified determines the format used.
294 options override each other; the last one specified determines
301 options all override each other;
302 the last one specified determines the format used
303 for non-printable characters.
309 options all override each other (either partially or fully); they
310 are applied in the order specified.
314 lists one entry per line to standard
315 output; the exceptions are to terminals or when the
319 options are specified.
321 File information is displayed with one or more
323 separating the information associated with the
331 option is given, the following information
332 is displayed for each file:
334 number of links, owner name, group name,
335 number of bytes in the file, abbreviated
336 month, day-of-month file was last modified,
337 hour file last modified, minute file last
338 modified, and the pathname.
339 In addition, for each directory whose contents are displayed,
340 the total number of 512-byte blocks used by the files in the directory
341 is displayed on a line by itself,
342 immediately before the information for the files in the directory.
343 If the file or directory has extended attributes,
344 the permissions field printed by the
346 option is followed by a '@' character.
347 Otherwise, if the file or directory has extended security information
348 (such as an access control list),
349 the permissions field printed by the
351 option is followed by a '+' character.
353 If the modification time of the file
354 is more than 6 months in the past or future,
355 then the year of the last modification
356 is displayed in place of the hour and minute fields.
358 If the owner or group names are not a known user or group name,
362 the numeric ID's are displayed.
364 If the file is a character special or block special file,
365 the major and minor device numbers for the file are displayed
367 If the file is a symbolic link,
368 the pathname of the linked-to file is preceded by
371 The file mode printed under the
373 option consists of the
374 entry type, owner permissions, and group permissions.
375 The entry type character describes the type of file,
378 .Bl -tag -width 4n -offset indent -compact
382 Character special file.
395 The next three fields
396 are three characters each:
398 group permissions, and
400 Each field has three character positions:
401 .Bl -enum -offset indent
405 the file is readable; if
411 the file is writable; if
415 The first of the following that applies:
416 .Bl -tag -width 4n -offset indent
418 If in the owner permissions, the file is not executable and
419 set-user-ID mode is set.
420 If in the group permissions, the file is not executable
421 and set-group-ID mode is set.
423 If in the owner permissions, the file is executable
424 and set-user-ID mode is set.
425 If in the group permissions, the file is executable
426 and setgroup-ID mode is set.
428 The file is executable or the directory is
431 The file is neither readable, writable, executable,
432 nor set-user-ID nor set-group-ID mode, nor sticky.
436 These next two apply only to the third character in the last group
438 .Bl -tag -width 4n -offset indent
440 The sticky bit is set
443 but not execute or search permission.
449 The sticky bit is set (mode
451 and is searchable or executable.
459 The following is how to do an
461 listing sorted by increasing size
467 The following environment variables affect the execution of
469 .Bl -tag -width ".Ev CLICOLOR_FORCE"
471 If the environment variable
473 is set, the block counts
476 will be displayed in units of that size block.
480 color sequences to distinguish file types.
484 In addition to the file types mentioned in the
486 option some extra attributes (setuid bit set, etc.) are also displayed.
487 The colorization is dependent on a terminal type with the proper
492 console has the proper capabilities,
493 but to display the colors in an
498 variable must be set to
500 Other terminal types may require similar adjustments.
502 is silently disabled if the output isn't directed to a terminal
506 .It Ev CLICOLOR_FORCE
507 Color sequences are normally disabled if the output isn't directed to
509 This can be overridden by setting this flag.
512 variable still needs to reference a color capable terminal however
513 otherwise it is not possible to determine which color sequences to
516 If this variable contains a string representing a
517 decimal integer, it is used as the
518 column position width for displaying
519 multiple-text-column output.
522 utility calculates how
523 many pathname text columns to display
524 based on the width provided.
530 The locale to use when determining the order of day and month in the long
535 for more information.
537 The value of this variable describes what color to use for which
538 attribute when colors are enabled with
540 This string is a concatenation of pairs of the format
544 is the foreground color and
546 is the background color.
548 The color designators are as follows:
550 .Bl -tag -width 4n -offset indent -compact
568 bold black, usually shows up as dark grey
574 bold brown, usually shows up as yellow
582 bold light grey; looks like bright white
584 default foreground or background
587 Note that the above are standard
590 The actual display may differ
591 depending on the color capabilities of the terminal in use.
593 The order of the attributes are as follows:
595 .Bl -enum -offset indent -compact
611 executable with setuid bit set
613 executable with setgid bit set
615 directory writable to others, with sticky bit
617 directory writable to others, without sticky bit
621 .Qq "exfxcxdxbxegedabagacad" ,
622 i.e. blue foreground and
623 default background for regular directories, black foreground and red
624 background for setuid executables, etc.
626 If this variable is set, it is considered to be a
627 colon-delimited list of minimum column widths.
629 and insufficient widths are ignored (thus zero signifies
630 a dynamically sized column).
631 Not all columns have changeable widths.
633 in order: inode, block count, number of links, user name,
634 group name, flags, file size, file name.
638 functionality depends on a terminal type with color capabilities.
640 The timezone to use when displaying dates.
643 for more information.
646 The group field is now automatically included in the long listing for
647 files in order to be compatible with the
650 .Sh LEGACY DESCRIPTION
653 option does not turn on the
660 options do not turn on the
666 option causes the file flags to be included in a long (-l) output;
673 is specified (and not overridden by
677 and a file argument is a symlink
678 that resolves to a non-directory file,
679 the output will reflect the nature of the link,
680 rather than that of the file.
681 In legacy operation, the output will describe the file.
683 For more information about legacy mode, see
705 To maintain backward compatibility, the relationships between the many
706 options are quite complex.