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.33.2.21 2003/05/07 23:56:14 trhodes Exp $
37 .\" $DragonFly: src/bin/ls/ls.1,v 1.3 2005/09/17 07:08:43 dillon Exp $
44 .Nd list directory contents
47 .Op Fl ABCFGHLPRTWabcdfghiklmnopqrstuwx1
50 For each operand that names a
55 displays its name as well as any requested,
56 associated information.
57 For each operand that names a
61 displays the names of files contained
62 within that directory, as well as any requested, associated
65 If no operands are given, the contents of the current
66 directory are displayed.
67 If more than one operand is given,
68 non-directory operands are displayed first; directory
69 and non-directory operands are sorted separately and in
70 lexicographical order.
72 The following options are available:
73 .Bl -tag -width indent
75 List all entries except for
79 Always set for the super-user.
81 Force printing of non-printable characters (as defined by
83 and current locale settings) in file names as
87 is the numeric value of the character in octal.
89 Force multi-column output; this is the default when output is to a terminal.
93 immediately after each pathname that is a directory,
96 after each that is executable,
99 after each symbolic link,
111 Enable colorized output.
112 This option is equivalent to defining
117 Symbolic links on the command line are followed.
118 This option is assumed if
123 options are specified.
125 If argument is a symbolic link, list the file or directory the link references
126 rather than the link itself.
127 This option cancels the
131 If argument is a symbolic link, list the link itself rather than the
132 object the link references.
133 This option cancels the
139 Recursively list subdirectories encountered.
145 option, display complete time information for the file, including
146 month, day, hour, minute, second, and year.
148 Display whiteouts when scanning directories.
150 Include directory entries whose names begin with a
158 escape codes whenever possible.
160 Use time when file status was last changed for sorting or printing.
162 Directories are listed as plain files (not searched recursively).
164 Output is not sorted.
166 This option is deprecated and is only available for compatibility
169 it was used to display the group name in the long
175 option, use unit suffixes: Byte, Kilobyte, Megabyte, Gigabyte, Terabyte
176 and Petabyte in order to reduce the number of digits to four or fewer
177 using base 2 for sizes.
179 For each file, print the file's file serial number (inode number).
183 option is specified, print the file size allocation in kilobytes,
185 This option overrides the environment variable
188 (The lowercase letter
192 If the output is to a terminal, a total sum for all the file
193 sizes is output on a line before the long listing.
195 Stream output format; list files across the page, separated by commas.
197 Display user and group IDs numerically rather than converting to a user
198 or group name in a long
202 Include the file flags in a long
208 after each filename if that file is a directory.
210 Force printing of non-graphic characters in file names as
213 this is the default when output is to a terminal.
215 Reverse the order of the sort to get reverse
216 lexicographical order or the oldest entries first.
218 Display the number of file system blocks actually used by each file, in units
219 of 512 bytes, where partial units are rounded up to the next integer value.
220 If the output is to a terminal, a total sum for all the file
221 sizes is output on a line before the listing.
222 The environment variable
224 overrides the unit size of 512 bytes.
226 Sort by time modified (most recently modified
227 first) before sorting the operands by lexicographical
230 Use time of last access,
231 instead of last modification
232 of the file for sorting
237 Force raw printing of non-printable characters.
239 when output is not to a terminal.
243 except that the multi-column output is produced with entries sorted
244 across, rather than down, the columns.
246 Include the FSMID field in a long
254 This is the default when
255 output is not to a terminal.
262 options all override each other; the last one specified determines
269 options override each other; the last one specified determines
276 options all override each other; the last one specified determines
277 the format used for non-printable characters.
283 options all override each other (either partially or fully); they
284 are applied in the order specified.
288 lists one entry per line to standard
289 output; the exceptions are to terminals or when the
293 options are specified.
295 File information is displayed with one or more
297 separating the information associated with the
305 option is given, the following information
306 is displayed for each file:
308 number of links, owner name, group name,
309 number of bytes in the file, abbreviated
310 month, day-of-month file was last modified,
311 hour file last modified, minute file last
312 modified, and the pathname.
313 In addition, for each directory whose contents are displayed, the total
314 number of 512-byte blocks used by the files in the directory is displayed
315 on a line by itself immediately before the information for the files in the
318 If the modification time of the file is more than 6 months
319 in the past or future, then the year of the last modification
320 is displayed in place of the hour and minute fields.
322 If the owner or group names are not a known user or group name,
326 the numeric ID's are displayed.
328 If the file is a character special or block special file,
329 the major and minor device numbers for the file are displayed
331 If the file is a symbolic link the pathname of the
332 linked-to file is preceded by
335 The file mode printed under the
337 option consists of the
338 entry type, owner permissions, and group permissions.
339 The entry type character describes the type of file, as
342 .Bl -tag -width 4n -offset indent -compact
346 Character special file.
359 The next three fields
360 are three characters each:
362 group permissions, and
364 Each field has three character positions:
365 .Bl -enum -offset indent
369 the file is readable; if
375 the file is writable; if
379 The first of the following that applies:
380 .Bl -tag -width 4n -offset indent
382 If in the owner permissions, the file is not executable and
383 set-user-ID mode is set.
384 If in the group permissions, the file is not executable
385 and set-group-ID mode is set.
387 If in the owner permissions, the file is executable
388 and set-user-ID mode is set.
389 If in the group permissions, the file is executable
390 and setgroup-ID mode is set.
392 The file is executable or the directory is
395 The file is neither readable, writable, executable,
396 nor set-user-ID nor set-group-ID mode, nor sticky.
400 These next two apply only to the third character in the last group
402 .Bl -tag -width 4n -offset indent
404 The sticky bit is set
407 but not execute or search permission.
413 The sticky bit is set (mode
415 and is searchable or executable.
423 The following is how to do an
425 listing sorted by size (and shows why
427 does not need a separate option for this):
429 .Dl "ls -l | sort -n +4"
436 to get the results sorted from largest to smallest (a reverse sort).
440 The following environment variables affect the execution of
442 .Bl -tag -width ".Ev CLICOLOR_FORCE"
444 If the environment variable
446 is set, the block counts
449 will be displayed in units of that size block.
453 color sequences to distinguish file types.
457 In addition to the file types mentioned in the
459 option some extra attributes (setuid bit set, etc.) are also displayed.
460 The colorization is dependent on a terminal type with the proper
465 console has the proper capabilities,
466 but to display the colors in an
471 variable must be set to
473 Other terminal types may require similar adjustments.
475 is silently disabled if the output isn't directed to a terminal
479 .It Ev CLICOLOR_FORCE
480 Color sequences are normally disabled if the output isn't directed to
482 This can be overridden by setting this flag.
485 variable still needs to reference a color capable terminal however
486 otherwise it is not possible to determine which color sequences to
489 If this variable contains a string representing a
490 decimal integer, it is used as the
491 column position width for displaying
492 multiple-text-column output.
495 utility calculates how
496 many pathname text columns to display
497 based on the width provided.
503 The locale to use when determining the order of day and month in the long
508 for more information.
510 The value of this variable describes what color to use for which
511 attribute when colors are enabled with
513 This string is a concatenation of pairs of the format
517 is the foreground color and
519 is the background color.
521 The color designators are as follows:
523 .Bl -tag -width 4n -offset indent -compact
541 bold black, usually shows up as dark grey
547 bold brown, usually shows up as yellow
555 bold light grey; looks like bright white
557 default foreground or background
560 Note that the above are standard
563 The actual display may differ
564 depending on the color capabilities of the terminal in use.
566 The order of the attributes are as follows:
568 .Bl -enum -offset indent -compact
584 executable with setuid bit set
586 executable with setgid bit set
588 directory writable to others, with sticky bit
590 directory writable to others, without sticky bit
594 .Qq "exfxcxdxbxegedabagacad" ,
595 i.e. blue foreground and
596 default background for regular directories, black foreground and red
597 background for setuid executables, etc.
599 If this variable is set, it is considered to be a
600 colon-delimited list of minimum column widths.
602 and insufficient widths are ignored (thus zero signifies
603 a dynamically sized column).
604 Not all columns have changeable widths.
606 in order: inode, block count, number of links, user name,
607 group name, flags, file size, file name.
611 functionality depends on a terminal type with color capabilities.
613 The timezone to use when displaying dates.
616 for more information.
619 The group field is now automatically included in the long listing for
620 files in order to be compatible with the
642 To maintain backward compatibility, the relationships between the many
643 options are quite complex.