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. Neither the name of the University nor the names of its contributors
16 .\" may be used to endorse or promote products derived from this software
17 .\" without specific prior written permission.
19 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
20 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
21 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
22 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
23 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
24 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
25 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
26 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
27 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
28 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
31 .\" @(#)ls.1 8.7 (Berkeley) 7/29/94
32 .\" $FreeBSD: src/bin/ls/ls.1,v 1.86 2005/02/13 22:25:09 ru Exp $
39 .Nd list directory contents
42 .Op Fl ABCFGHILPRTWabcdfghiklmnopqrstuwxy1
45 For each operand that names a
50 displays its name as well as any requested,
51 associated information.
52 For each operand that names a
56 displays the names of files contained
57 within that directory, as well as any requested, associated
60 If no operands are given, the contents of the current
61 directory are displayed.
62 If more than one operand is given,
63 non-directory operands are displayed first; directory
64 and non-directory operands are sorted separately and in
65 lexicographical order.
67 The following options are available:
68 .Bl -tag -width indent
70 List all entries, including dot files, except for dot and dot-dot.
71 Always set for the super-user, but may be turned
75 Force printing of non-printable characters (as defined by
77 and current locale settings) in file names as
81 is the numeric value of the character in octal.
83 Force multi-column output; this is the default when output is to a terminal.
87 immediately after each pathname that is a directory,
90 after each that is executable,
93 after each symbolic link,
105 Enable colorized output.
106 This option is equivalent to defining
111 Symbolic links on the command line are followed.
112 This option is assumed if
117 options are specified.
119 This turns off the listing of dot files.
120 Dot files are listed by default when
127 options will override each other.
129 If argument is a symbolic link, list the file or directory the link references
130 rather than the link itself.
131 This option cancels the
135 If argument is a symbolic link, list the link itself rather than the
136 object the link references.
137 This option cancels the
143 Recursively list subdirectories encountered.
145 Sort by size (largest file first) before sorting the operands in
146 lexicographical order.
152 option, display complete time information for the file, including
153 month, day, hour, minute, second, and year (named locales use the
154 ISO 8601 extended format).
156 Display whiteouts when scanning directories.
158 Include directory entries whose names begin with a
166 escape codes whenever possible.
168 Use time when file status was last changed for sorting or printing.
170 Directories are listed as plain files (not searched recursively).
172 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).
193 option is specified, print the file size allocation in kilobytes,
195 This option overrides the environment variable
199 is mutually exclusive to
206 (The lowercase letter
210 A total sum (in blocks, see the
212 option for the block size unit) for all the file
213 sizes is output on a line before the long listing.
215 Stream output format; list files across the page, separated by commas.
217 Display user and group IDs numerically rather than converting to a user
218 or group name in a long
222 Include the file flags in a long
228 after each filename if that file is a directory.
230 Force printing of non-graphic characters in file names as
233 this is the default when output is to a terminal.
235 Reverse the order of the sort to get reverse
236 lexicographical order or the oldest entries first.
238 Display the number of file system blocks actually used by each file, in units
239 of 512 bytes, where partial units are rounded up to the next integer value.
240 A total sum for all the file
241 sizes is output on a line before the listing.
242 The environment variable
244 overrides the unit size of 512 bytes.
246 Sort by time modified (most recently modified
247 first) before sorting the operands by lexicographical
250 Use time of last access,
251 instead of last modification
252 of the file for sorting
257 Force raw printing of non-printable characters.
259 when output is not to a terminal.
263 except that the multi-column output is produced with entries sorted
264 across, rather than down, the columns.
266 Include the FSMID field in a long
274 This is the default when
275 output is not to a terminal.
282 options all override each other; the last one specified determines
289 options override each other; the last one specified determines
296 options override each other; the last one specified determines
303 options all override each other; the last one specified determines
304 the format used for non-printable characters.
310 options all override each other (either partially or fully); they
311 are applied in the order specified.
315 lists one entry per line to standard
316 output; the exceptions are to terminals or when the
320 options are specified.
322 File information is displayed with one or more
324 separating the information associated with the
332 option is given, the following information
333 is displayed for each file:
335 number of links, owner name, group name,
336 number of bytes in the file,
337 last modified time in either per POSIX requirements or
338 using the format DD-MMM-YYYY hh:ss, and the pathname.
339 In addition, for each directory whose contents are displayed, the total
340 number of 512-byte blocks used by the files in the directory is displayed
341 on a line by itself immediately before the information for the files in the
344 In the POSIX locale, If the modification time of the file is in the future,
345 or more than 6 months in the past, then the year of the last modification
346 is displayed in place of the hour and minute fields.
348 If the owner or group names are not a known user or group name,
352 the numeric ID's are displayed.
354 If the file is a character special or block special file,
355 the major and minor device numbers for the file are displayed
357 If the file is a symbolic link the pathname of the
358 linked-to file is preceded by
361 The file mode printed under the
363 option consists of the
364 entry type and the permissions.
365 The entry type character describes the type of file, as
368 .Bl -tag -width 4n -offset indent -compact
372 Character special file.
385 The next three fields
386 are three characters each:
388 group permissions, and
390 Each field has three character positions:
391 .Bl -enum -offset indent
395 the file is readable; if
401 the file is writable; if
405 The first of the following that applies:
406 .Bl -tag -width 4n -offset indent
408 If in the owner permissions, the file is not executable and
409 set-user-ID mode is set.
410 If in the group permissions, the file is not executable
411 and set-group-ID mode is set.
413 If in the owner permissions, the file is executable
414 and set-user-ID mode is set.
415 If in the group permissions, the file is executable
416 and setgroup-ID mode is set.
418 The file is executable or the directory is
421 The file is neither readable, writable, executable,
422 nor set-user-ID nor set-group-ID mode, nor sticky.
426 These next two apply only to the third character in the last group
428 .Bl -tag -width 4n -offset indent
430 The sticky bit is set
433 but not execute or search permission.
439 The sticky bit is set (mode
441 and is searchable or executable.
449 The following environment variables affect the execution of
451 .Bl -tag -width ".Ev CLICOLOR_FORCE"
453 If the environment variable
455 is set, the block counts
458 will be displayed in units of that size block.
462 color sequences to distinguish file types.
466 In addition to the file types mentioned in the
468 option some extra attributes (setuid bit set, etc.) are also displayed.
469 The colorization is dependent on a terminal type with the proper
474 console has the proper capabilities,
475 but to display the colors in an
480 variable must be set to
482 Other terminal types may require similar adjustments.
484 is silently disabled if the output is not directed to a terminal
488 .It Ev CLICOLOR_FORCE
489 Color sequences are normally disabled if the output is not directed to
491 This can be overridden by setting this flag.
494 variable still needs to reference a color capable terminal however
495 otherwise it is not possible to determine which color sequences to
498 If this variable contains a string representing a
499 decimal integer, it is used as the
500 column position width for displaying
501 multiple-text-column output.
504 utility calculates how
505 many pathname text columns to display
506 based on the width provided.
512 The locale to use when determining the order of day and month in the long
517 for more information.
519 The value of this variable describes what color to use for which
520 attribute when colors are enabled with
522 This string is a concatenation of pairs of the format
526 is the foreground color and
528 is the background color.
530 The color designators are as follows:
532 .Bl -tag -width 4n -offset indent -compact
550 bold black, usually shows up as dark grey
556 bold brown, usually shows up as yellow
564 bold light grey; looks like bright white
566 default foreground or background
569 Note that the above are standard
572 The actual display may differ
573 depending on the color capabilities of the terminal in use.
575 The order of the attributes are as follows:
577 .Bl -enum -offset indent -compact
593 executable with setuid bit set
595 executable with setgid bit set
597 directory writable to others, with sticky bit
599 directory writable to others, without sticky bit
603 .Qq "exfxcxdxbxegedabagacad" ,
604 i.e., blue foreground and
605 default background for regular directories, black foreground and red
606 background for setuid executables, etc.
608 If this variable is set, it is considered to be a
609 colon-delimited list of minimum column widths.
611 and insufficient widths are ignored (thus zero signifies
612 a dynamically sized column).
613 Not all columns have changeable widths.
615 in order: inode, block count, number of links, user name,
616 group name, flags, file size, file name.
620 functionality depends on a terminal type with color capabilities.
622 The timezone to use when displaying dates.
625 for more information.
628 The group field is now automatically included in the long listing for
629 files in order to be compatible with the
636 .Xr xterm 1 Pq Pa x11/xterm ,
641 With the exception of options
656 To maintain backward compatibility, the relationships between the many
657 options are quite complex.