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 1ABCFGHILPRSTW_abcdfghiklmnopqrstuwxy
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.
86 When printing in the long
90 to format the date and time output.
95 Depending on the choice of format string, this may result in a
96 different number of columns in the output.
97 This option overrides the
103 immediately after each pathname that is a directory,
106 after each that is executable,
109 after each symbolic link,
121 Enable colorized output.
122 This option is equivalent to defining
126 This functionality can be compiled out by removing the definition of
129 Symbolic links on the command line are followed.
130 This option is assumed if
135 options are specified.
137 This turns off the listing of dot files.
138 Dot files are listed by default when
145 options will override each other.
147 If argument is a symbolic link, list the file or directory the link references
148 rather than the link itself.
149 This option cancels the
153 If argument is a symbolic link, list the link itself rather than the
154 object the link references.
155 This option cancels the
161 Recursively list subdirectories encountered.
163 Sort by size (largest file first) before sorting the operands in
164 lexicographical order.
170 option, display complete time information for the file, including
171 month, day, hour, minute, second, and year (named locales use the
172 ISO 8601 extended format).
174 Display whiteouts when scanning directories.
176 Include directory entries whose names begin with a
184 escape codes whenever possible.
186 Use time when file status was last changed for sorting or printing.
188 Directories are listed as plain files (not searched recursively).
190 Output is not sorted.
194 This option is deprecated and is only available for compatibility
197 it was used to display the group name in the long
203 option, use unit suffixes: Byte, Kilobyte, Megabyte, Gigabyte, Terabyte
204 and Petabyte in order to reduce the number of digits to four or fewer
205 using base 2 for sizes.
207 For each file, print the file's file serial number (inode number).
211 option is specified, print the file size allocation in kilobytes,
213 This option overrides the environment variable
217 is mutually exclusive to
224 (The lowercase letter
228 A total sum (in blocks, see the
230 option for the block size unit) for all the file
231 sizes is output on a line before the long listing.
233 Stream output format; list files across the page, separated by commas.
235 Display user and group IDs numerically rather than converting to a user
236 or group name in a long
240 Include the file flags in a long
246 after each filename if that file is a directory.
248 Force printing of non-graphic characters in file names as
251 this is the default when output is to a terminal.
253 Reverse the order of the sort to get reverse
254 lexicographical order or the oldest entries first.
256 Display the number of file system blocks actually used by each file, in units
257 of 512 bytes, where partial units are rounded up to the next integer value.
258 A total sum for all the file
259 sizes is output on a line before the listing.
260 The environment variable
262 overrides the unit size of 512 bytes.
264 Sort by time modified (most recently modified
265 first) before sorting the operands by lexicographical
268 Use time of last access,
269 instead of last modification
270 of the file for sorting
275 Force raw printing of non-printable characters.
277 when output is not to a terminal.
281 except that the multi-column output is produced with entries sorted
282 across, rather than down, the columns.
284 Include the FSMID field in a long
292 This is the default when
293 output is not to a terminal.
295 (underscore) When printing in the long
297 format, use GMT based date and time output with nanotime timestamp.
304 options all override each other; the last one specified determines
311 options override each other; the last one specified determines
318 options override each other; the last one specified determines
325 options all override each other; the last one specified determines
326 the format used for non-printable characters.
332 options all override each other (either partially or fully); they
333 are applied in the order specified.
337 lists one entry per line to standard
338 output; the exceptions are to terminals or when the
342 options are specified.
344 File information is displayed with one or more
346 separating the information associated with the
354 option is given, the following information
355 is displayed for each file:
357 number of links, owner name, group name,
358 number of bytes in the file,
359 last modified time in either per POSIX requirements or
360 using the format DD-MMM-YYYY hh:ss, and the pathname.
361 In addition, for each directory whose contents are displayed, the total
362 number of 512-byte blocks used by the files in the directory is displayed
363 on a line by itself immediately before the information for the files in the
366 In the POSIX locale, If the modification time of the file is in the future,
367 or more than 6 months in the past, then the year of the last modification
368 is displayed in place of the hour and minute fields.
370 If the owner or group names are not a known user or group name,
374 the numeric ID's are displayed.
376 If the file is a character special or block special file,
377 the major and minor device numbers for the file are displayed
379 If the file is a symbolic link the pathname of the
380 linked-to file is preceded by
383 The file mode printed under the
385 option consists of the
386 entry type and the permissions.
387 The entry type character describes the type of file, as
390 .Bl -tag -width 4n -offset indent -compact
394 Character special file.
407 The next three fields
408 are three characters each:
410 group permissions, and
412 Each field has three character positions:
413 .Bl -enum -offset indent
417 the file is readable; if
423 the file is writable; if
427 The first of the following that applies:
428 .Bl -tag -width 4n -offset indent
430 If in the owner permissions, the file is not executable and
431 set-user-ID mode is set.
432 If in the group permissions, the file is not executable
433 and set-group-ID mode is set.
435 If in the owner permissions, the file is executable
436 and set-user-ID mode is set.
437 If in the group permissions, the file is executable
438 and setgroup-ID mode is set.
440 The file is executable or the directory is
443 The file is neither readable, writable, executable,
444 nor set-user-ID nor set-group-ID mode, nor sticky.
448 These next two apply only to the third character in the last group
450 .Bl -tag -width 4n -offset indent
452 The sticky bit is set
455 but not execute or search permission.
461 The sticky bit is set (mode
463 and is searchable or executable.
471 The following environment variables affect the execution of
473 .Bl -tag -width ".Ev CLICOLOR_FORCE"
475 If the environment variable
477 is set, the block counts
480 will be displayed in units of that size block.
484 color sequences to distinguish file types.
488 In addition to the file types mentioned in the
490 option some extra attributes (setuid bit set, etc.) are also displayed.
491 The colorization is dependent on a terminal type with the proper
496 console has the proper capabilities,
497 but to display the colors in an
502 variable must be set to
504 Other terminal types may require similar adjustments.
506 is silently disabled if the output is not directed to a terminal
510 .It Ev CLICOLOR_FORCE
511 Color sequences are normally disabled if the output is not directed to
513 This can be overridden by setting this variable.
516 variable still needs to reference a color capable terminal however
517 otherwise it is not possible to determine which color sequences to
520 If this variable contains a string representing a
521 decimal integer, it is used as the
522 column position width for displaying
523 multiple-text-column output.
526 utility calculates how
527 many pathname text columns to display
528 based on the width provided.
534 The locale to use when determining the order of day and month in the long
539 for more information.
541 The value of this variable describes what color to use for which
542 attribute when colors are enabled with
544 This string is a concatenation of pairs of the format
548 is the foreground color and
550 is the background color.
552 The color designators are as follows:
554 .Bl -tag -width 4n -offset indent -compact
572 bold black, usually shows up as dark grey
578 bold brown, usually shows up as yellow
586 bold light grey; looks like bright white
588 default foreground or background
591 Note that the above are standard
594 The actual display may differ
595 depending on the color capabilities of the terminal in use.
597 The order of the attributes are as follows:
599 .Bl -enum -offset indent -compact
615 executable with setuid bit set
617 executable with setgid bit set
619 directory writable to others, with sticky bit
621 directory writable to others, without sticky bit
625 .Qq "exfxcxdxbxegedabagacad" ,
626 i.e., blue foreground and
627 default background for regular directories, black foreground and red
628 background for setuid executables, etc.
630 If this variable is set, it is considered to be a
631 colon-delimited list of minimum column widths.
633 and insufficient widths are ignored (thus zero signifies
634 a dynamically sized column).
635 Not all columns have changeable widths.
637 in order: inode, block count, number of links, user name,
638 group name, flags, file size, file name.
642 functionality depends on a terminal type with color capabilities.
644 The timezone to use when displaying dates.
647 for more information.
650 The group field is now automatically included in the long listing for
651 files in order to be compatible with the
658 .Xr xterm 1 Pq Pa x11/xterm ,
664 With the exception of options
674 .Fl B , D , G , I , T , W , b , h , w , y
677 are compatible extensions not defined in
685 To maintain backward compatibility, the relationships between the many
686 options are quite complex.