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 .\" 4. 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 $
33 .\" $DragonFly: src/bin/ls/ls.1,v 1.9 2008/09/25 09:09:06 matthias Exp $
35 .Dd September 25, 2008
40 .Nd list directory contents
43 .Op Fl ABCFGHILPRTWabcdfghiklmnopqrstuwxy1
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, including dot files, except for dot and dot-dot.
72 Always set for the super-user, but may be turned
76 Force printing of non-printable characters (as defined by
78 and current locale settings) in file names as
82 is the numeric value of the character in octal.
84 Force multi-column output; this is the default when output is to a terminal.
88 immediately after each pathname that is a directory,
91 after each that is executable,
94 after each symbolic link,
106 Enable colorized output.
107 This option is equivalent to defining
112 Symbolic links on the command line are followed.
113 This option is assumed if
118 options are specified.
120 This turns off the listing of dot files.
121 Dot files are listed by default when
128 options will override each other.
130 If argument is a symbolic link, list the file or directory the link references
131 rather than the link itself.
132 This option cancels the
136 If argument is a symbolic link, list the link itself rather than the
137 object the link references.
138 This option cancels the
144 Recursively list subdirectories encountered.
146 Use the size of a file for sorting
153 option, display complete time information for the file, including
154 month, day, hour, minute, second, and year.
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.
174 This option is deprecated and is only available for compatibility
177 it was used to display the group name in the long
183 option, use unit suffixes: Byte, Kilobyte, Megabyte, Gigabyte, Terabyte
184 and Petabyte in order to reduce the number of digits to four or fewer
185 using base 2 for sizes.
187 For each file, print the file's file serial number (inode number).
191 option is specified, print the file size allocation in kilobytes,
193 This option overrides the environment variable
197 is mutually exclusive to
204 (The lowercase letter
208 A total sum (in blocks, see the
210 option for the block size unit) for all the file
211 sizes is output on a line before the long listing.
213 Stream output format; list files across the page, separated by commas.
215 Display user and group IDs numerically rather than converting to a user
216 or group name in a long
220 Include the file flags in a long
226 after each filename if that file is a directory.
228 Force printing of non-graphic characters in file names as
231 this is the default when output is to a terminal.
233 Reverse the order of the sort to get reverse
234 lexicographical order or the oldest entries first.
236 Display the number of file system blocks actually used by each file, in units
237 of 512 bytes, where partial units are rounded up to the next integer value.
238 A total sum for all the file
239 sizes is output on a line before the listing.
240 The environment variable
242 overrides the unit size of 512 bytes.
244 Sort by time modified (most recently modified
245 first) before sorting the operands by lexicographical
248 Use time of last access,
249 instead of last modification
250 of the file for sorting
255 Force raw printing of non-printable characters.
257 when output is not to a terminal.
261 except that the multi-column output is produced with entries sorted
262 across, rather than down, the columns.
264 Include the FSMID field in a long
272 This is the default when
273 output is not to a terminal.
280 options all override each other; the last one specified determines
287 options override each other; the last one specified determines
294 options all override each other; the last one specified determines
295 the format used for non-printable characters.
301 options all override each other (either partially or fully); they
302 are applied in the order specified.
306 lists one entry per line to standard
307 output; the exceptions are to terminals or when the
311 options are specified.
313 File information is displayed with one or more
315 separating the information associated with the
323 option is given, the following information
324 is displayed for each file:
326 number of links, owner name, group name,
327 number of bytes in the file, abbreviated
328 month, day-of-month file was last modified,
329 hour file last modified, minute file last
330 modified, and the pathname.
331 In addition, for each directory whose contents are displayed, the total
332 number of 512-byte blocks used by the files in the directory is displayed
333 on a line by itself immediately before the information for the files in the
336 If the modification time of the file is more than 6 months
337 in the past or future, then the year of the last modification
338 is displayed in place of the hour and minute fields.
340 If the owner or group names are not a known user or group name,
344 the numeric ID's are displayed.
346 If the file is a character special or block special file,
347 the major and minor device numbers for the file are displayed
349 If the file is a symbolic link the pathname of the
350 linked-to file is preceded by
353 The file mode printed under the
355 option consists of the
356 entry type and the permissions.
357 The entry type character describes the type of file, as
360 .Bl -tag -width 4n -offset indent -compact
364 Character special file.
377 The next three fields
378 are three characters each:
380 group permissions, and
382 Each field has three character positions:
383 .Bl -enum -offset indent
387 the file is readable; if
393 the file is writable; if
397 The first of the following that applies:
398 .Bl -tag -width 4n -offset indent
400 If in the owner permissions, the file is not executable and
401 set-user-ID mode is set.
402 If in the group permissions, the file is not executable
403 and set-group-ID mode is set.
405 If in the owner permissions, the file is executable
406 and set-user-ID mode is set.
407 If in the group permissions, the file is executable
408 and setgroup-ID mode is set.
410 The file is executable or the directory is
413 The file is neither readable, writable, executable,
414 nor set-user-ID nor set-group-ID mode, nor sticky.
418 These next two apply only to the third character in the last group
420 .Bl -tag -width 4n -offset indent
422 The sticky bit is set
425 but not execute or search permission.
431 The sticky bit is set (mode
433 and is searchable or executable.
441 The following environment variables affect the execution of
443 .Bl -tag -width ".Ev CLICOLOR_FORCE"
445 If the environment variable
447 is set, the block counts
450 will be displayed in units of that size block.
454 color sequences to distinguish file types.
458 In addition to the file types mentioned in the
460 option some extra attributes (setuid bit set, etc.) are also displayed.
461 The colorization is dependent on a terminal type with the proper
466 console has the proper capabilities,
467 but to display the colors in an
472 variable must be set to
474 Other terminal types may require similar adjustments.
476 is silently disabled if the output is not directed to a terminal
480 .It Ev CLICOLOR_FORCE
481 Color sequences are normally disabled if the output is not directed to
483 This can be overridden by setting this flag.
486 variable still needs to reference a color capable terminal however
487 otherwise it is not possible to determine which color sequences to
490 If this variable contains a string representing a
491 decimal integer, it is used as the
492 column position width for displaying
493 multiple-text-column output.
496 utility calculates how
497 many pathname text columns to display
498 based on the width provided.
504 The locale to use when determining the order of day and month in the long
509 for more information.
511 The value of this variable describes what color to use for which
512 attribute when colors are enabled with
514 This string is a concatenation of pairs of the format
518 is the foreground color and
520 is the background color.
522 The color designators are as follows:
524 .Bl -tag -width 4n -offset indent -compact
542 bold black, usually shows up as dark grey
548 bold brown, usually shows up as yellow
556 bold light grey; looks like bright white
558 default foreground or background
561 Note that the above are standard
564 The actual display may differ
565 depending on the color capabilities of the terminal in use.
567 The order of the attributes are as follows:
569 .Bl -enum -offset indent -compact
585 executable with setuid bit set
587 executable with setgid bit set
589 directory writable to others, with sticky bit
591 directory writable to others, without sticky bit
595 .Qq "exfxcxdxbxegedabagacad" ,
596 i.e., blue foreground and
597 default background for regular directories, black foreground and red
598 background for setuid executables, etc.
600 If this variable is set, it is considered to be a
601 colon-delimited list of minimum column widths.
603 and insufficient widths are ignored (thus zero signifies
604 a dynamically sized column).
605 Not all columns have changeable widths.
607 in order: inode, block count, number of links, user name,
608 group name, flags, file size, file name.
612 functionality depends on a terminal type with color capabilities.
614 The timezone to use when displaying dates.
617 for more information.
620 The group field is now automatically included in the long listing for
621 files in order to be compatible with the
628 .Xr xterm 1 Pq Pa pkgsrc/x11/xterm ,
633 With the exception of options
648 To maintain backward compatibility, the relationships between the many
649 options are quite complex.