2 .\" Copyright (c) 1980, 1990, 1991, 1993, 1994
3 .\" The Regents of the University of California. All rights reserved.
5 .\" This code is derived from software contributed to Berkeley by
6 .\" the Institute of Electrical and Electronics Engineers, Inc.
8 .\" Redistribution and use in source and binary forms, with or without
9 .\" modification, are permitted provided that the following conditions
11 .\" 1. Redistributions of source code must retain the above copyright
12 .\" notice, this list of conditions and the following disclaimer.
13 .\" 2. Redistributions in binary form must reproduce the above copyright
14 .\" notice, this list of conditions and the following disclaimer in the
15 .\" documentation and/or other materials provided with the distribution.
16 .\" 4. Neither the name of the University nor the names of its contributors
17 .\" may be used to endorse or promote products derived from this software
18 .\" without specific prior written permission.
20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
32 .\" @(#)ls.1 8.7 (Berkeley) 7/29/94
35 .Dd September 27, 2015
40 .Nd list directory contents
44 .Op Fl ABCFGHILPRSTUWZabcdfghiklmnopqrstuwxy1,
48 For each operand that names a
53 displays its name as well as any requested,
54 associated information.
55 For each operand that names a
59 displays the names of files contained
60 within that directory, as well as any requested, associated
63 If no operands are given, the contents of the current
64 directory are displayed.
65 If more than one operand is given,
66 non-directory operands are displayed first; directory
67 and non-directory operands are sorted separately and in
68 lexicographical order.
70 The following options are available:
71 .Bl -tag -width indent
73 Include directory entries whose names begin with a
80 Automatically set for the super-user unless
84 Force printing of non-printable characters (as defined by
86 and current locale settings) in file names as
90 is the numeric value of the character in octal.
91 This option is not defined in
94 Force multi-column output; this is the default when output is to a terminal.
96 When printing in the long
100 to format the date and time output.
105 Depending on the choice of format string, this may result in a
106 different number of columns in the output.
107 This option overrides the
110 This option is not defined in
115 immediately after each pathname that is a directory,
118 after each that is executable,
121 after each symbolic link,
133 Enable colorized output.
134 This option is equivalent to defining
138 This functionality can be compiled out by removing the definition of
140 This option is not defined in
143 Symbolic links on the command line are followed.
144 This option is assumed if
149 options are specified.
153 from being automatically set for the super-user.
154 This option is not defined in
157 If argument is a symbolic link, list the file or directory the link references
158 rather than the link itself.
159 This option cancels the
163 If argument is a symbolic link, list the link itself rather than the
164 object the link references.
165 This option cancels the
171 Recursively list subdirectories encountered.
173 Sort by size (largest file first) before sorting the operands in
174 lexicographical order.
176 When printing in the long
178 format, display complete time information for the file, including
179 month, day, hour, minute, second, and year.
182 option gives even more control over the output format.
183 This option is not defined in
186 Use time when file was created for sorting or printing.
187 This option is not defined in
190 Display whiteouts when scanning directories.
191 This option is not defined in
194 Display each file's MAC label; see
196 This option is not defined in
199 Include directory entries whose names begin with a
207 escape codes whenever possible.
208 This option is not defined in
211 Use time when file status was last changed for sorting or printing.
213 Directories are listed as plain files (not searched recursively).
215 Output is not sorted.
218 It also negates the effect of the
226 this option has no effect on the
234 This option has no effect.
235 It is only available for compatibility with
237 where it was used to display the group name in the long
240 This option is incompatible with
245 option, use unit suffixes: Byte, Kilobyte, Megabyte, Gigabyte, Terabyte
246 and Petabyte in order to reduce the number of digits to four or fewer
247 using base 2 for sizes.
248 This option is not defined in
251 For each file, print the file's file serial number (inode number).
253 This has the same effect as setting environment variable
255 to 1024, except that it also nullifies any
259 (The lowercase letter
261 List files in the long format, as described in the
265 Stream output format; list files across the page, separated by commas.
267 Display user and group IDs numerically rather than converting to a user
268 or group name in a long
272 Include the file flags in a long
275 This option is incompatible with
279 for a list of file flags and their meanings.
283 after each filename if that file is a directory.
285 Force printing of non-graphic characters in file names as
288 this is the default when output is to a terminal.
290 Reverse the order of the sort.
292 Display the number of blocks used in the file system by each file.
293 Block sizes and directory totals are handled as described in
295 subsection below, except (if the long format is not also requested)
296 the directory totals are not output when the output is in a
297 single column, even if multi-column output is requested.
299 Sort by descending time modified (most recently modified first).
300 If two files have the same modification timestamp, sort their names
301 in ascending lexicographical order.
304 option reverses both of these sort orders.
306 Note that these sort orders are contradictory: the time sequence is in
307 descending order, the lexicographical sort is in ascending order.
308 This behavior is mandated by
310 This feature can cause problems listing files stored with sequential names on
311 FAT file systems, such as from digital cameras, where it is possible to have
312 more than one image with the same timestamp.
313 In such a case, the photos cannot be listed in the sequence in which
315 To ensure the same sort order for time and for lexicographical sorting, set the
323 to reverse the lexicographical sort order when sorting files with the
324 same modification timestamp.
326 Use time of last access,
327 instead of time of last modification
328 of the file for sorting
333 Force raw printing of non-printable characters.
335 when output is not to a terminal.
336 This option is not defined in
341 except that the multi-column output is produced with entries sorted
342 across, rather than down, the columns.
346 option is set, sort the alphabetical output in the same order as the time output.
347 This has the same effect as setting
349 See the description of the
351 option for more details.
352 This option is not defined in
359 This is the default when
360 output is not to a terminal.
364 option is set, print file sizes grouped and separated by thousands using the
365 non-monetary separator returned by
367 typically a comma or period.
368 If no locale is set, or the locale does not have a non-monetary separator, this
369 option has no effect.
370 This option is not defined in
378 options all override each other; the last one specified determines
385 options all override each other; the last one specified determines
392 options override each other; the last one specified determines
399 options all override each other; the last one specified determines
400 the format used for non-printable characters.
406 options all override each other (either partially or fully); they
407 are applied in the order specified.
411 lists one entry per line to standard
412 output; the exceptions are to terminals or when the
416 options are specified.
418 File information is displayed with one or more
420 separating the information associated with the
428 option is given, the following information
429 is displayed for each file:
431 number of links, owner name, group name,
433 number of bytes in the file, abbreviated
434 month, day-of-month file was last modified,
435 hour file last modified, minute file last
436 modified, and the pathname.
438 If the modification time of the file is more than 6 months
439 in the past or future, and the
444 then the year of the last modification
445 is displayed in place of the hour and minute fields.
447 If the owner or group names are not a known user or group name,
451 the numeric ID's are displayed.
453 If the file is a character special or block special file,
454 the device number for the file is displayed in the size field.
455 If the file is a symbolic link the pathname of the
456 linked-to file is preceded by
459 The listing of a directory's contents is preceded
460 by a labeled total number of blocks used in the file system by the files
461 which are listed as the directory's contents
462 (which may or may not include
466 and other files which start with a dot, depending on other options).
468 The default block size is 512 bytes.
469 The block size may be set with option
471 or environment variable
473 Numbers of blocks in the output will have been rounded up so the
474 numbers of bytes is at least as many as used by the corresponding
475 file system blocks (which might have a different size).
477 The file mode printed under the
479 option consists of the
480 entry type and the permissions.
481 The entry type character describes the type of file, as
484 .Bl -tag -width 4n -offset indent -compact
490 Character special file.
503 The next three fields
504 are three characters each:
506 group permissions, and
508 Each field has three character positions:
509 .Bl -enum -offset indent
513 the file is readable; if
519 the file is writable; if
523 The first of the following that applies:
524 .Bl -tag -width 4n -offset indent
526 If in the owner permissions, the file is not executable and
527 set-user-ID mode is set.
528 If in the group permissions, the file is not executable
529 and set-group-ID mode is set.
531 If in the owner permissions, the file is executable
532 and set-user-ID mode is set.
533 If in the group permissions, the file is executable
534 and setgroup-ID mode is set.
536 The file is executable or the directory is
539 The file is neither readable, writable, executable,
540 nor set-user-ID nor set-group-ID mode, nor sticky.
544 These next two apply only to the third character in the last group
546 .Bl -tag -width 4n -offset indent
548 The sticky bit is set
551 but not execute or search permission.
557 The sticky bit is set (mode
559 and is searchable or executable.
567 The next field contains a
570 character if the file has an ACL, or a
576 utility does not show the actual ACL;
581 The following environment variables affect the execution of
583 .Bl -tag -width ".Ev CLICOLOR_FORCE"
585 If this is set, its value, rounded up to 512 or down to a
586 multiple of 512, will be used as the block size in bytes by the
593 subsection for more information.
597 color sequences to distinguish file types.
601 In addition to the file types mentioned in the
603 option some extra attributes (setuid bit set, etc.) are also displayed.
604 The colorization is dependent on a terminal type with the proper
609 console has the proper capabilities,
610 but to display the colors in an
615 variable must be set to
617 Other terminal types may require similar adjustments.
619 is silently disabled if the output is not directed to a terminal
623 .It Ev CLICOLOR_FORCE
624 Color sequences are normally disabled if the output is not directed to
626 This can be overridden by setting this variable.
629 variable still needs to reference a color capable terminal however
630 otherwise it is not possible to determine which color sequences to
633 If this variable contains a string representing a
634 decimal integer, it is used as the
635 column position width for displaying
636 multiple-text-column output.
639 utility calculates how
640 many pathname text columns to display
641 based on the width provided.
647 The locale to use when determining the order of day and month in the long
652 for more information.
654 The value of this variable describes what color to use for which
655 attribute when colors are enabled with
657 This string is a concatenation of pairs of the format
661 is the foreground color and
663 is the background color.
665 The color designators are as follows:
667 .Bl -tag -width 4n -offset indent -compact
685 bold black, usually shows up as dark grey
691 bold brown, usually shows up as yellow
699 bold light grey; looks like bright white
701 default foreground or background
704 Note that the above are standard
707 The actual display may differ
708 depending on the color capabilities of the terminal in use.
710 The order of the attributes are as follows:
712 .Bl -enum -offset indent -compact
728 executable with setuid bit set
730 executable with setgid bit set
732 directory writable to others, with sticky bit
734 directory writable to others, without sticky bit
738 .Qq "exfxcxdxbxegedabagacad" ,
739 i.e., blue foreground and
740 default background for regular directories, black foreground and red
741 background for setuid executables, etc.
743 If this variable is set, it is considered to be a
744 colon-delimited list of minimum column widths.
746 and insufficient widths are ignored (thus zero signifies
747 a dynamically sized column).
748 Not all columns have changeable widths.
750 in order: inode, block count, number of links, user name,
751 group name, flags, file size, file name.
753 If this variable is set, the
755 option sorts the names of files with the same modification timestamp in the same
756 sense as the time sort.
757 See the description of the
759 option for more details.
763 functionality depends on a terminal type with color capabilities.
765 The timezone to use when displaying dates.
768 for more information.
773 List the contents of the current working directory in long format:
777 In addition to listing the contents of the current working directory in
778 long format, show inode numbers, file flags (see
780 and suffix each filename with a symbol representing its file type:
786 sorting the output such that the mostly recently modified entries are
789 .Dl $ ls -lt /var/log
791 The group field is now automatically included in the long listing for
792 files in order to be compatible with the
805 .Xr xo_parse_args 3 ,
812 With the exception of options
821 .Fl B , D , G , I , T , U , W , Z , b , h , w , y
824 are compatible extensions not defined in
827 The ACL support is compatible with
830 .Pq Dq Tn POSIX Ns .2c
839 To maintain backward compatibility, the relationships between the many
840 options are quite complex.
842 The exception mentioned in the
844 option description might be a feature that was
845 based on the fact that single-column output
846 usually goes to something other than a terminal.
847 It is debatable whether this is a design bug.
850 mandates opposite sort orders for files with the same timestamp when