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 ABCFGHLPRSTW@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
75 Display extended attribute keys and sizes.
81 This is the default when
82 output is not to a terminal.
85 List all entries except for
89 Always set for the super-user.
92 Include directory entries whose names begin with a
97 Force printing of non-printable characters (as defined by
99 and current locale settings) in file names as
103 is the numeric value of the character in octal.
110 escape codes whenever possible.
113 Force multi-column output; this is the default when output is to a terminal.
116 Use time when file status was last changed for sorting or printing.
119 Directories are listed as plain files (not searched recursively).
122 Print the Access Control List (ACL) associated with the file, if present.
127 immediately after each pathname that is a directory,
130 after each that is executable,
133 after each symbolic link,
146 Output is not sorted.
147 This option turns on the
152 Enable colorized output.
153 This option is equivalent to defining
159 This option is only available for compatibility with POSIX;
160 it is used to display the group name in the long
162 format output (the owner name is suppressed).
165 Symbolic links on the command line are followed.
166 This option is assumed if
171 options are specified.
176 option, use unit suffixes: Byte, Kilobyte, Megabyte, Gigabyte, Terabyte
177 and Petabyte in order to reduce the number of digits to three or less
178 using base 2 for sizes.
181 For each file, print the file's file serial number (inode number).
186 option is specified, print the file size allocation in kilobytes,
188 This option overrides the environment variable
192 If argument is a symbolic link, list the file or directory the link references
193 rather than the link itself.
194 This option cancels the
199 (The lowercase letter
203 If the output is to a terminal, a total sum for all the file
204 sizes is output on a line before the long listing.
207 Stream output format; list files across the page, separated by commas.
210 Display user and group IDs numerically,
211 rather than converting to a user or group name in a long
214 This option turns on the
219 Include the file flags in a long
224 List in long format, but omit the group id.
227 If argument is a symbolic link, list the link itself rather than the
228 object the link references.
229 This option cancels the
238 after each filename if that file is a directory.
241 Force printing of non-graphic characters in file names as
244 this is the default when output is to a terminal.
247 Recursively list subdirectories encountered.
250 Reverse the order of the sort to get reverse
251 lexicographical order or the oldest entries first (or largest files
252 last, if combined with sort by size
258 Display the number of file system blocks actually used by each file, in units
259 of 512 bytes, where partial units are rounded up to the next integer value.
260 If the output is to a terminal, a total sum for all the file
261 sizes is output on a line before the listing.
262 The environment variable
264 overrides the unit size of 512 bytes.
271 option, display complete time information for the file, including
272 month, day, hour, minute, second, and year.
275 Sort by time modified (most recently modified
276 first) before sorting the operands by lexicographical
280 Use time of last access,
281 instead of last modification
282 of the file for sorting
288 Force unedited printing of non-graphic characters; this is the default when
289 output is not to a terminal.
292 Display whiteouts when scanning directories.
297 Force raw printing of non-printable characters.
299 when output is not to a terminal.
304 except that the multi-column output is produced with entries sorted
305 across, rather than down, the columns.
312 options all override each other;
313 the last one specified determines the format used.
319 options override each other; the last one specified determines
326 options all override each other;
327 the last one specified determines the format used
328 for non-printable characters.
334 options all override each other (either partially or fully); they
335 are applied in the order specified.
339 lists one entry per line to standard
340 output; the exceptions are to terminals or when the
344 options are specified.
346 File information is displayed with one or more
348 separating the information associated with the
356 option is given, the following information
357 is displayed for each file:
359 number of links, owner name, group name,
360 number of bytes in the file, abbreviated
361 month, day-of-month file was last modified,
362 hour file last modified, minute file last
363 modified, and the pathname.
364 In addition, for each directory whose contents are displayed,
365 the total number of 512-byte blocks used by the files in the directory
366 is displayed on a line by itself,
367 immediately before the information for the files in the directory.
368 If the file or directory has extended attributes,
369 the permissions field printed by the
371 option is followed by a '@' character.
372 Otherwise, if the file or directory has extended security information,
373 the permissions field printed by the
375 option is followed by a '+' character.
377 If the modification time of the file
378 is more than 6 months in the past or future,
379 then the year of the last modification
380 is displayed in place of the hour and minute fields.
382 If the owner or group names are not a known user or group name,
386 the numeric ID's are displayed.
388 If the file is a character special or block special file,
389 the major and minor device numbers for the file are displayed
391 If the file is a symbolic link,
392 the pathname of the linked-to file is preceded by
395 The file mode printed under the
397 option consists of the
398 entry type, owner permissions, and group permissions.
399 The entry type character describes the type of file,
402 .Bl -tag -width 4n -offset indent -compact
406 Character special file.
419 The next three fields
420 are three characters each:
422 group permissions, and
424 Each field has three character positions:
425 .Bl -enum -offset indent
429 the file is readable; if
435 the file is writable; if
439 The first of the following that applies:
440 .Bl -tag -width 4n -offset indent
442 If in the owner permissions, the file is not executable and
443 set-user-ID mode is set.
444 If in the group permissions, the file is not executable
445 and set-group-ID mode is set.
447 If in the owner permissions, the file is executable
448 and set-user-ID mode is set.
449 If in the group permissions, the file is executable
450 and setgroup-ID mode is set.
452 The file is executable or the directory is
455 The file is neither readable, writable, executable,
456 nor set-user-ID nor set-group-ID mode, nor sticky.
460 These next two apply only to the third character in the last group
462 .Bl -tag -width 4n -offset indent
464 The sticky bit is set
467 but not execute or search permission.
473 The sticky bit is set (mode
475 and is searchable or executable.
483 The following is how to do an
485 listing sorted by increasing size
491 The following environment variables affect the execution of
493 .Bl -tag -width ".Ev CLICOLOR_FORCE"
495 If the environment variable
497 is set, the block counts
500 will be displayed in units of that size block.
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 isn't directed to a terminal
530 .It Ev CLICOLOR_FORCE
531 Color sequences are normally disabled if the output isn't 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.
670 The group field is now automatically included in the long listing for
671 files in order to be compatible with the
674 .Sh LEGACY DESCRIPTION
677 option does not turn on the
684 options do not turn on the
690 option causes the file flags to be included in a long (-l) output;
697 is specified (and not overridden by
701 and a file argument is a symlink
702 that resolves to a non-directory file,
703 the output will reflect the nature of the link,
704 rather than that of the file.
705 In legacy operation, the output will describe the file.
726 To maintain backward compatibility, the relationships between the many
727 options are quite complex.