xref: /freebsd/bin/ls/ls.1 (revision 6472ac3d8a86336899b6cfb789a4cd9897e3fab5)
1.\"-
2.\" Copyright (c) 1980, 1990, 1991, 1993, 1994
3.\"	The Regents of the University of California.  All rights reserved.
4.\"
5.\" This code is derived from software contributed to Berkeley by
6.\" the Institute of Electrical and Electronics Engineers, Inc.
7.\"
8.\" Redistribution and use in source and binary forms, with or without
9.\" modification, are permitted provided that the following conditions
10.\" are met:
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.
19.\"
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
30.\" SUCH DAMAGE.
31.\"
32.\"     @(#)ls.1	8.7 (Berkeley) 7/29/94
33.\" $FreeBSD$
34.\"
35.Dd September 28, 2011
36.Dt LS 1
37.Os
38.Sh NAME
39.Nm ls
40.Nd list directory contents
41.Sh SYNOPSIS
42.Nm
43.Op Fl ABCFGHILPRSTUWZabcdfghiklmnopqrstuwx1
44.Op Fl D Ar format
45.Op Ar
46.Sh DESCRIPTION
47For each operand that names a
48.Ar file
49of a type other than
50directory,
51.Nm
52displays its name as well as any requested,
53associated information.
54For each operand that names a
55.Ar file
56of type directory,
57.Nm
58displays the names of files contained
59within that directory, as well as any requested, associated
60information.
61.Pp
62If no operands are given, the contents of the current
63directory are displayed.
64If more than one operand is given,
65non-directory operands are displayed first; directory
66and non-directory operands are sorted separately and in
67lexicographical order.
68.Pp
69The following options are available:
70.Bl -tag -width indent
71.It Fl A
72Include directory entries whose names begin with a
73dot
74.Pq Sq Pa \&.
75except for
76.Pa \&.
77and
78.Pa .. .
79Automatically set for the super-user unless
80.Fl I
81is specified.
82.It Fl B
83Force printing of non-printable characters (as defined by
84.Xr ctype 3
85and current locale settings) in file names as
86.Li \e Ns Va xxx ,
87where
88.Va xxx
89is the numeric value of the character in octal.
90.It Fl C
91Force multi-column output; this is the default when output is to a terminal.
92.It Fl D Ar format
93When printing in the long
94.Pq Fl l
95format, use
96.Ar format
97to format the date and time output.
98The argument
99.Ar format
100is a string used by
101.Xr strftime 3 .
102Depending on the choice of format string, this may result in a
103different number of columns in the output.
104This option overrides the
105.Fl T
106option.
107.It Fl F
108Display a slash
109.Pq Ql /
110immediately after each pathname that is a directory,
111an asterisk
112.Pq Ql *
113after each that is executable,
114an at sign
115.Pq Ql @
116after each symbolic link,
117an equals sign
118.Pq Ql =
119after each socket,
120a percent sign
121.Pq Ql %
122after each whiteout,
123and a vertical bar
124.Pq Ql \&|
125after each that is a
126.Tn FIFO .
127.It Fl G
128Enable colorized output.
129This option is equivalent to defining
130.Ev CLICOLOR
131in the environment.
132(See below.)
133.It Fl H
134Symbolic links on the command line are followed.
135This option is assumed if
136none of the
137.Fl F , d ,
138or
139.Fl l
140options are specified.
141.It Fl I
142Prevent
143.Fl A
144from being automatically set for the super-user.
145.It Fl L
146If argument is a symbolic link, list the file or directory the link references
147rather than the link itself.
148This option cancels the
149.Fl P
150option.
151.It Fl P
152If argument is a symbolic link, list the link itself rather than the
153object the link references.
154This option cancels the
155.Fl H
156and
157.Fl L
158options.
159.It Fl R
160Recursively list subdirectories encountered.
161.It Fl S
162Sort by size (largest file first) before sorting the operands in
163lexicographical order.
164.It Fl T
165When printing in the long
166.Pq Fl l
167format, display complete time information for the file, including
168month, day, hour, minute, second, and year.
169The
170.Fl D
171option gives even more control over the output format.
172.It Fl U
173Use time when file was created for sorting or printing.
174.It Fl W
175Display whiteouts when scanning directories.
176.It Fl Z
177Display each file's MAC label; see
178.Xr maclabel 7 .
179.It Fl a
180Include directory entries whose names begin with a
181dot
182.Pq Sq Pa \&. .
183.It Fl b
184As
185.Fl B ,
186but use
187.Tn C
188escape codes whenever possible.
189.It Fl c
190Use time when file status was last changed for sorting or printing.
191.It Fl d
192Directories are listed as plain files (not searched recursively).
193.It Fl f
194Output is not sorted.
195.It Fl g
196This option is deprecated and is only available for compatibility
197with
198.Bx 4.3 ;
199it was used to display the group name in the long
200.Pq Fl l
201format output.
202.It Fl h
203When used with the
204.Fl l
205option, use unit suffixes: Byte, Kilobyte, Megabyte, Gigabyte, Terabyte
206and Petabyte in order to reduce the number of digits to four or fewer
207using base 2 for sizes.
208.It Fl i
209For each file, print the file's file serial number (inode number).
210.It Fl k
211This has the same effect as setting environment variable
212.Ev BLOCKSIZE
213to 1024, except that it also nullifies any
214.Fl h
215options to its left.
216.It Fl l
217(The lowercase letter
218.Dq ell . )
219List files in the long format, as described in the
220.Sx The Long Format
221subsection below.
222.It Fl m
223Stream output format; list files across the page, separated by commas.
224.It Fl n
225Display user and group IDs numerically rather than converting to a user
226or group name in a long
227.Pq Fl l
228output.
229.It Fl o
230Include the file flags in a long
231.Pq Fl l
232output.
233.It Fl p
234Write a slash
235.Pq Ql /
236after each filename if that file is a directory.
237.It Fl q
238Force printing of non-graphic characters in file names as
239the character
240.Ql \&? ;
241this is the default when output is to a terminal.
242.It Fl r
243Reverse the order of the sort.
244.It Fl s
245Display the number of blocks used in the file system by each file.
246Block sizes and directory totals are handled as described in
247.Sx The Long Format
248subsection below, except (if the long format is not also requested)
249the directory totals are not output when the output is in a
250single column, even if multi-column output is requested.
251.It Fl t
252Sort by time modified (most recently modified
253first) before sorting the operands in lexicographical
254order.
255.It Fl u
256Use time of last access,
257instead of last modification
258of the file for sorting
259.Pq Fl t
260or printing
261.Pq Fl l .
262.It Fl w
263Force raw printing of non-printable characters.
264This is the default
265when output is not to a terminal.
266.It Fl x
267The same as
268.Fl C ,
269except that the multi-column output is produced with entries sorted
270across, rather than down, the columns.
271.It Fl 1
272(The numeric digit
273.Dq one . )
274Force output to be
275one entry per line.
276This is the default when
277output is not to a terminal.
278.El
279.Pp
280The
281.Fl 1 , C , x ,
282and
283.Fl l
284options all override each other; the last one specified determines
285the format used.
286.Pp
287The
288.Fl c , u ,
289and
290.Fl U
291options all override each other; the last one specified determines
292the file time used.
293.Pp
294The
295.Fl S
296and
297.Fl t
298options override each other; the last one specified determines
299the sort order used.
300.Pp
301The
302.Fl B , b , w ,
303and
304.Fl q
305options all override each other; the last one specified determines
306the format used for non-printable characters.
307.Pp
308The
309.Fl H , L
310and
311.Fl P
312options all override each other (either partially or fully); they
313are applied in the order specified.
314.Pp
315By default,
316.Nm
317lists one entry per line to standard
318output; the exceptions are to terminals or when the
319.Fl C
320or
321.Fl x
322options are specified.
323.Pp
324File information is displayed with one or more
325.Ao blank Ac Ns s
326separating the information associated with the
327.Fl i , s ,
328and
329.Fl l
330options.
331.Ss The Long Format
332If the
333.Fl l
334option is given, the following information
335is displayed for each file:
336file mode,
337number of links, owner name, group name,
338MAC label,
339number of bytes in the file, abbreviated
340month, day-of-month file was last modified,
341hour file last modified, minute file last
342modified, and the pathname.
343.Pp
344If the modification time of the file is more than 6 months
345in the past or future, and the
346.Fl D
347or
348.Fl T
349are not specified,
350then the year of the last modification
351is displayed in place of the hour and minute fields.
352.Pp
353If the owner or group names are not a known user or group name,
354or the
355.Fl n
356option is given,
357the numeric ID's are displayed.
358.Pp
359If the file is a character special or block special file,
360the device number for the file is displayed in the size field.
361If the file is a symbolic link the pathname of the
362linked-to file is preceded by
363.Dq Li -> .
364.Pp
365The listing of a directory's contents is preceded
366by a labeled total number of blocks used in the file system by the files
367which are listed as the directory's contents
368(which may or may not include
369.Pa \&.
370and
371.Pa ..
372and other files which start with a dot, depending on other options).
373.Pp
374The default block size is 512 bytes.
375The block size may be set with option
376.Fl k
377or environment variable
378.Ev BLOCKSIZE .
379Numbers of blocks in the output will have been rounded up so the
380numbers of bytes is at least as many as used by the corresponding
381file system blocks (which might have a different size).
382.Pp
383The file mode printed under the
384.Fl l
385option consists of the
386entry type and the permissions.
387The entry type character describes the type of file, as
388follows:
389.Pp
390.Bl -tag -width 4n -offset indent -compact
391.It Sy \-
392Regular file.
393.It Sy b
394Block special file.
395.It Sy c
396Character special file.
397.It Sy d
398Directory.
399.It Sy l
400Symbolic link.
401.It Sy p
402.Tn FIFO .
403.It Sy s
404Socket.
405.It Sy w
406Whiteout.
407.El
408.Pp
409The next three fields
410are three characters each:
411owner permissions,
412group permissions, and
413other permissions.
414Each field has three character positions:
415.Bl -enum -offset indent
416.It
417If
418.Sy r ,
419the file is readable; if
420.Sy \- ,
421it is not readable.
422.It
423If
424.Sy w ,
425the file is writable; if
426.Sy \- ,
427it is not writable.
428.It
429The first of the following that applies:
430.Bl -tag -width 4n -offset indent
431.It Sy S
432If in the owner permissions, the file is not executable and
433set-user-ID mode is set.
434If in the group permissions, the file is not executable
435and set-group-ID mode is set.
436.It Sy s
437If in the owner permissions, the file is executable
438and set-user-ID mode is set.
439If in the group permissions, the file is executable
440and setgroup-ID mode is set.
441.It Sy x
442The file is executable or the directory is
443searchable.
444.It Sy \-
445The file is neither readable, writable, executable,
446nor set-user-ID nor set-group-ID mode, nor sticky.
447(See below.)
448.El
449.Pp
450These next two apply only to the third character in the last group
451(other permissions).
452.Bl -tag -width 4n -offset indent
453.It Sy T
454The sticky bit is set
455(mode
456.Li 1000 ) ,
457but not execute or search permission.
458(See
459.Xr chmod 1
460or
461.Xr sticky 7 . )
462.It Sy t
463The sticky bit is set (mode
464.Li 1000 ) ,
465and is searchable or executable.
466(See
467.Xr chmod 1
468or
469.Xr sticky 7 . )
470.El
471.El
472.Pp
473The next field contains a
474plus
475.Pq Ql +
476character if the file has an ACL, or a
477space
478.Pq Ql " "
479if it does not.
480The
481.Nm
482utility does not show the actual ACL;
483use
484.Xr getfacl 1
485to do this.
486.Sh ENVIRONMENT
487The following environment variables affect the execution of
488.Nm :
489.Bl -tag -width ".Ev CLICOLOR_FORCE"
490.It Ev BLOCKSIZE
491If this is set, its value, rounded up to 512 or down to a
492multiple of 512, will be used as the block size in bytes by the
493.Fl l
494and
495.Fl s
496options.
497See
498.Sx The Long Format
499subsection for more information.
500.It Ev CLICOLOR
501Use
502.Tn ANSI
503color sequences to distinguish file types.
504See
505.Ev LSCOLORS
506below.
507In addition to the file types mentioned in the
508.Fl F
509option some extra attributes (setuid bit set, etc.) are also displayed.
510The colorization is dependent on a terminal type with the proper
511.Xr termcap 5
512capabilities.
513The default
514.Dq Li cons25
515console has the proper capabilities,
516but to display the colors in an
517.Xr xterm 1 ,
518for example,
519the
520.Ev TERM
521variable must be set to
522.Dq Li xterm-color .
523Other terminal types may require similar adjustments.
524Colorization
525is silently disabled if the output is not directed to a terminal
526unless the
527.Ev CLICOLOR_FORCE
528variable is defined.
529.It Ev CLICOLOR_FORCE
530Color sequences are normally disabled if the output is not directed to
531a terminal.
532This can be overridden by setting this flag.
533The
534.Ev TERM
535variable still needs to reference a color capable terminal however
536otherwise it is not possible to determine which color sequences to
537use.
538.It Ev COLUMNS
539If this variable contains a string representing a
540decimal integer, it is used as the
541column position width for displaying
542multiple-text-column output.
543The
544.Nm
545utility calculates how
546many pathname text columns to display
547based on the width provided.
548(See
549.Fl C
550and
551.Fl x . )
552.It Ev LANG
553The locale to use when determining the order of day and month in the long
554.Fl l
555format output.
556See
557.Xr environ 7
558for more information.
559.It Ev LSCOLORS
560The value of this variable describes what color to use for which
561attribute when colors are enabled with
562.Ev CLICOLOR .
563This string is a concatenation of pairs of the format
564.Ar f Ns Ar b ,
565where
566.Ar f
567is the foreground color and
568.Ar b
569is the background color.
570.Pp
571The color designators are as follows:
572.Pp
573.Bl -tag -width 4n -offset indent -compact
574.It Sy a
575black
576.It Sy b
577red
578.It Sy c
579green
580.It Sy d
581brown
582.It Sy e
583blue
584.It Sy f
585magenta
586.It Sy g
587cyan
588.It Sy h
589light grey
590.It Sy A
591bold black, usually shows up as dark grey
592.It Sy B
593bold red
594.It Sy C
595bold green
596.It Sy D
597bold brown, usually shows up as yellow
598.It Sy E
599bold blue
600.It Sy F
601bold magenta
602.It Sy G
603bold cyan
604.It Sy H
605bold light grey; looks like bright white
606.It Sy x
607default foreground or background
608.El
609.Pp
610Note that the above are standard
611.Tn ANSI
612colors.
613The actual display may differ
614depending on the color capabilities of the terminal in use.
615.Pp
616The order of the attributes are as follows:
617.Pp
618.Bl -enum -offset indent -compact
619.It
620directory
621.It
622symbolic link
623.It
624socket
625.It
626pipe
627.It
628executable
629.It
630block special
631.It
632character special
633.It
634executable with setuid bit set
635.It
636executable with setgid bit set
637.It
638directory writable to others, with sticky bit
639.It
640directory writable to others, without sticky bit
641.El
642.Pp
643The default is
644.Qq "exfxcxdxbxegedabagacad" ,
645i.e., blue foreground and
646default background for regular directories, black foreground and red
647background for setuid executables, etc.
648.It Ev LS_COLWIDTHS
649If this variable is set, it is considered to be a
650colon-delimited list of minimum column widths.
651Unreasonable
652and insufficient widths are ignored (thus zero signifies
653a dynamically sized column).
654Not all columns have changeable widths.
655The fields are,
656in order: inode, block count, number of links, user name,
657group name, flags, file size, file name.
658.It Ev TERM
659The
660.Ev CLICOLOR
661functionality depends on a terminal type with color capabilities.
662.It Ev TZ
663The timezone to use when displaying dates.
664See
665.Xr environ 7
666for more information.
667.El
668.Sh EXIT STATUS
669.Ex -std
670.Sh COMPATIBILITY
671The group field is now automatically included in the long listing for
672files in order to be compatible with the
673.St -p1003.2
674specification.
675.Sh SEE ALSO
676.Xr chflags 1 ,
677.Xr chmod 1 ,
678.Xr getfacl 1 ,
679.Xr sort 1 ,
680.Xr xterm 1 ,
681.Xr strftime 3 ,
682.Xr strmode 3 ,
683.Xr termcap 5 ,
684.Xr maclabel 7 ,
685.Xr sticky 7 ,
686.Xr symlink 7 ,
687.Xr getfmac 8
688.Sh STANDARDS
689With the exception of options
690.Fl I , g , n
691and
692.Fl o ,
693the
694.Nm
695utility conforms to
696.St -p1003.1-2001 .
697.Pp
698The ACL support is compatible with
699.Tn IEEE
700Std\~1003.2c
701.Pq Dq Tn POSIX Ns .2c
702Draft\~17
703(withdrawn).
704.Sh HISTORY
705An
706.Nm
707command appeared in
708.At v1 .
709.Sh BUGS
710To maintain backward compatibility, the relationships between the many
711options are quite complex.
712.Pp
713The exception mentioned in the
714.Fl s
715option description might be a feature that was
716based on the fact that single-column output
717usually goes to something other than a terminal.
718It is debatable whether this is a design bug.
719