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
43 .Nd list directory contents
46 .Op Fl ABCFGHLPRTWZabcdfghiklnoqrstuw1
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
74 List all entries except for
78 Always set for the super-user.
80 Force printing of non-printable characters (as defined by
82 and current locale settings) in file names as
86 is the numeric value of the character in octal.
88 Force multi-column output; this is the default when output is to a terminal.
92 immediately after each pathname that is a directory,
95 after each that is executable,
98 after each symbolic link,
110 Enable colorized output.
111 This option is equivalent to defining
116 Symbolic links on the command line are followed.
117 This option is assumed if
122 options are specified.
124 If argument is a symbolic link, list the file or directory the link references
125 rather than the link itself.
126 This option cancels the
130 If argument is a symbolic link, list the link itself rather than the
131 object the link references.
132 This option cancels the
138 Recursively list subdirectories encountered.
144 option, display complete time information for the file, including
145 month, day, hour, minute, second, and year.
147 Display whiteouts when scanning directories.
149 Display each file's LOMAC level.
151 Include directory entries whose names begin with a
159 escape codes whenever possible.
161 Use time when file status was last changed for sorting or printing.
163 Directories are listed as plain files (not searched recursively).
165 Output is not sorted.
167 This option is deprecated and is only available for compatibility
170 it was used to display the group name in the long
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.
180 For each file, print the file's file serial number (inode number).
184 option is specified, print the file size allocation in kilobytes,
186 This option overrides the environment variable
189 (The lowercase letter
193 If the output is to a terminal, a total sum for all the file
194 sizes is output on a line before the long listing.
196 Display user and group IDs numerically rather than converting to a user
197 or group name in a long
201 Include the file flags in a long
205 Force printing of non-graphic characters in file names as
208 this is the default when output is to a terminal.
210 Reverse the order of the sort to get reverse
211 lexicographical order or the oldest entries first.
213 Display the number of file system blocks actually used by each file, in units
214 of 512 bytes, where partial units are rounded up to the next integer value.
215 If the output is to a terminal, a total sum for all the file
216 sizes is output on a line before the listing.
217 The environment variable
219 overrides the unit size of 512 bytes.
221 Sort by time modified (most recently modified
222 first) before sorting the operands by lexicographical
225 Use time of last access,
226 instead of last modification
227 of the file for sorting
232 Force raw printing of non-printable characters.
234 when output is not to a terminal.
240 This is the default when
241 output is not to a terminal.
248 options all override each other; the last one specified determines
255 options override each other; the last one specified determines
262 options all override each other; the last one specified determines
263 the format used for non-printable characters.
269 options all override each other (either partially or fully); they
270 are applied in the order specified.
274 lists one entry per line to standard
275 output; the exceptions are to terminals or when the
279 File information is displayed with one or more
281 separating the information associated with the
289 option is given, the following information
290 is displayed for each file:
292 number of links, owner name, group name,
294 number of bytes in the file, abbreviated
295 month, day-of-month file was last modified,
296 hour file last modified, minute file last
297 modified, and the pathname.
298 In addition, for each directory whose contents are displayed, the total
299 number of 512-byte blocks used by the files in the directory is displayed
300 on a line by itself immediately before the information for the files in the
303 If the modification time of the file is more than 6 months
304 in the past or future, then the year of the last modification
305 is displayed in place of the hour and minute fields.
307 If the owner or group names are not a known user or group name,
311 the numeric ID's are displayed.
313 If the file is a character special or block special file,
314 the major and minor device numbers for the file are displayed
316 If the file is a symbolic link the pathname of the
317 linked-to file is preceded by
320 The file mode printed under the
322 option consists of the
323 entry type, owner permissions, and group permissions.
324 The entry type character describes the type of file, as
327 .Bl -tag -width 4n -offset indent -compact
331 Character special file.
344 The next three fields
345 are three characters each:
347 group permissions, and
349 Each field has three character positions:
350 .Bl -enum -offset indent
354 the file is readable; if
360 the file is writable; if
364 The first of the following that applies:
365 .Bl -tag -width 4n -offset indent
367 If in the owner permissions, the file is not executable and
368 set-user-ID mode is set.
369 If in the group permissions, the file is not executable
370 and set-group-ID mode is set.
372 If in the owner permissions, the file is executable
373 and set-user-ID mode is set.
374 If in the group permissions, the file is executable
375 and setgroup-ID mode is set.
377 The file is executable or the directory is
380 The file is neither readable, writable, executable,
381 nor set-user-ID nor set-group-ID mode, nor sticky.
385 These next two apply only to the third character in the last group
387 .Bl -tag -width 4n -offset indent
389 The sticky bit is set
392 but not execute or search permission.
398 The sticky bit is set (mode
400 and is searchable or executable.
408 The following is how to do an
410 listing sorted by size (and shows why
412 does not need a separate option for this):
414 .Dl "ls -l | sort -n +4"
421 to get the results sorted from largest to smallest (a reverse sort).
425 The following environment variables affect the execution of
427 .Bl -tag -width ".Ev CLICOLOR_FORCE"
429 If the environment variable
431 is set, the block counts
434 will be displayed in units of that size block.
438 color sequences to distinguish file types.
442 In addition to the file types mentioned in the
444 option some extra attributes (setuid bit set, etc.) are also displayed.
445 The colorization is dependent on a terminal type with the proper
450 console has the proper capabilities,
451 but to display the colors in an
456 variable must be set to
458 Other terminal types may require similar adjustments.
460 is silently disabled if the output isn't directed to a terminal
464 .It Ev CLICOLOR_FORCE
465 Color sequences are normally disabled if the output isn't directed to
467 This can be overridden by setting this flag.
470 variable still needs to reference a color capable terminal however
471 otherwise it is not possible to determine which color sequences to
474 If this variable contains a string representing a
475 decimal integer, it is used as the
476 column position width for displaying
477 multiple-text-column output.
480 utility calculates how
481 many pathname text columns to display
482 based on the width provided.
486 The locale to use when determining the order of day and month in the long
491 for more information.
493 The value of this variable describes what color to use for which
494 attribute when colors are enabled with
496 This string is a concatenation of pairs of the format
500 is the foreground color and
502 is the background color.
504 The color designators are as follows:
506 .Bl -tag -width 4n -offset indent -compact
524 bold black, usually shows up as dark grey
530 bold brown, usually shows up as yellow
538 bold light grey; looks like bright white
540 default foreground or background
543 Note that the above are standard
546 The actual display may differ
547 depending on the color capabilities of the terminal in use.
549 The order of the attributes are as follows:
551 .Bl -enum -offset indent -compact
567 executable with setuid bit set
569 executable with setgid bit set
571 directory writable to others, with sticky bit
573 directory writable to others, without sticky bit
577 .Qq "exfxcxdxbxegedabagacad" ,
578 i.e. blue foreground and
579 default background for regular directories, black foreground and red
580 background for setuid executables, etc.
582 If this variable is set, it is considered to be a
583 colon-delimited list of minimum column widths.
585 and insufficient widths are ignored (thus zero signifies
586 a dynamically sized column).
587 Not all columns have changeable widths.
589 in order: inode, block count, number of links, user name,
590 group name, flags, file size, file name.
594 functionality depends on a terminal type with color capabilities.
596 The timezone to use when displaying dates.
599 for more information.
602 The group field is now automatically included in the long listing for
603 files in order to be compatible with the
607 .Bl -tag -width ".Pa /dev/lomac" -compact
609 interface used to query the
630 utility is expected to be a superset of the
634 To maintain backward compatibility, the relationships between the many
635 options are quite complex.