xref: /freebsd/bin/ls/ls.1 (revision da477bcdc0c335171bb0ed3813f570026de6df85)
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.\" 3. 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 August 21, 2020
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 ABCFGHILPRSTUWZabcdfghiklmnopqrstuwxy1,
44.Op Fl -color Ns = Ns Ar when
45.Op Fl D Ar format
46.Op Ar
47.Sh DESCRIPTION
48For each operand that names a
49.Ar file
50of a type other than
51directory,
52.Nm
53displays its name as well as any requested,
54associated information.
55For each operand that names a
56.Ar file
57of type directory,
58.Nm
59displays the names of files contained
60within that directory, as well as any requested, associated
61information.
62.Pp
63If no operands are given, the contents of the current
64directory are displayed.
65If more than one operand is given,
66non-directory operands are displayed first; directory
67and non-directory operands are sorted separately and in
68lexicographical order.
69.Pp
70The following options are available:
71.Bl -tag -width indent
72.It Fl A
73Include directory entries whose names begin with a
74dot
75.Pq Sq Pa \&.
76except for
77.Pa \&.
78and
79.Pa .. .
80Automatically set for the super-user unless
81.Fl I
82is specified.
83.It Fl B
84Force printing of non-printable characters (as defined by
85.Xr ctype 3
86and current locale settings) in file names as
87.Li \e Ns Va xxx ,
88where
89.Va xxx
90is the numeric value of the character in octal.
91This option is not defined in
92.St -p1003.1-2008 .
93.It Fl C
94Force multi-column output; this is the default when output is to a terminal.
95.It Fl D Ar format
96When printing in the long
97.Pq Fl l
98format, use
99.Ar format
100to format the date and time output.
101The argument
102.Ar format
103is a string used by
104.Xr strftime 3 .
105Depending on the choice of format string, this may result in a
106different number of columns in the output.
107This option overrides the
108.Fl T
109option.
110This option is not defined in
111.St -p1003.1-2008 .
112.It Fl F
113Display a slash
114.Pq Ql /
115immediately after each pathname that is a directory,
116an asterisk
117.Pq Ql *
118after each that is executable,
119an at sign
120.Pq Ql @
121after each symbolic link,
122an equals sign
123.Pq Ql =
124after each socket,
125a percent sign
126.Pq Ql %
127after each whiteout,
128and a vertical bar
129.Pq Ql \&|
130after each that is a
131.Tn FIFO .
132.It Fl G
133Enable colorized output.
134This option is equivalent to defining
135.Ev CLICOLOR
136or
137.Ev COLORTERM
138in the environment and setting
139.Fl -color Ns = Ns Ar auto .
140(See below.)
141This functionality can be compiled out by removing the definition of
142.Ev COLORLS .
143This option is not defined in
144.St -p1003.1-2008 .
145.It Fl H
146Symbolic links on the command line are followed.
147This option is assumed if
148none of the
149.Fl F , d ,
150or
151.Fl l
152options are specified.
153.It Fl I
154Prevent
155.Fl A
156from being automatically set for the super-user.
157This option is not defined in
158.St -p1003.1-2008 .
159.It Fl L
160If argument is a symbolic link, list the file or directory the link references
161rather than the link itself.
162This option cancels the
163.Fl P
164option.
165.It Fl P
166If argument is a symbolic link, list the link itself rather than the
167object the link references.
168This option cancels the
169.Fl H
170and
171.Fl L
172options.
173.It Fl R
174Recursively list subdirectories encountered.
175.It Fl S
176Sort by size (largest file first) before sorting the operands in
177lexicographical order.
178.It Fl T
179When printing in the long
180.Pq Fl l
181format, display complete time information for the file, including
182month, day, hour, minute, second, and year.
183The
184.Fl D
185option gives even more control over the output format.
186This option is not defined in
187.St -p1003.1-2008 .
188.It Fl U
189Use time when file was created for sorting or printing.
190This option is not defined in
191.St -p1003.1-2008 .
192.It Fl W
193Display whiteouts when scanning directories.
194This option is not defined in
195.St -p1003.1-2008 .
196.It Fl Z
197Display each file's MAC label; see
198.Xr maclabel 7 .
199This option is not defined in
200.St -p1003.1-2001 .
201.It Fl a
202Include directory entries whose names begin with a
203dot
204.Pq Sq Pa \&. .
205.It Fl b
206As
207.Fl B ,
208but use
209.Tn C
210escape codes whenever possible.
211This option is not defined in
212.St -p1003.1-2001 .
213.It Fl c
214Use time when file status was last changed for sorting or printing.
215.It Fl -color Ns = Ns Ar when
216Output colored escape sequences based on
217.Ar when ,
218which may be set to either
219.Cm always ,
220.Cm auto ,
221or
222.Cm never .
223.Pp
224.Cm always
225will make
226.Nm
227always output color.
228If
229.Ev TERM
230is unset or set to an invalid terminal, then
231.Nm
232will fall back to explicit
233.Tn ANSI
234escape sequences without the help of
235.Xr termcap 5 .
236.Cm always
237is the default if
238.Fl -color
239is specified without an argument.
240.Pp
241.Cm auto
242will make
243.Nm
244output escape sequences based on
245.Xr termcap 5 ,
246but only if
247.Dv stdout
248is a tty and either the
249.Fl G
250flag is specified or the
251.Ev COLORTERM
252environment variable is set and not empty.
253.Pp
254.Cm never
255will disable color regardless of environment variables.
256.Cm never
257is the default when neither
258.Fl -color
259nor
260.Fl G
261is specified.
262.Pp
263For compatibility with GNU coreutils,
264.Nm
265supports
266.Cm yes
267or
268.Cm force
269as equivalent to
270.Cm always ,
271.Cm no
272or
273.Cm none
274as equivalent to
275.Cm never ,
276and
277.Cm tty
278or
279.Cm if-tty
280as equivalent to
281.Cm auto .
282.It Fl d
283Directories are listed as plain files (not searched recursively).
284.It Fl f
285Output is not sorted.
286This option turns on
287.Fl a .
288It also negates the effect of the
289.Fl r ,
290.Fl S
291and
292.Fl t
293options.
294As allowed by
295.St -p1003.1-2001 ,
296this option has no effect on the
297.Fl d ,
298.Fl l ,
299.Fl R
300and
301.Fl s
302options.
303.It Fl g
304This option has no effect.
305It is only available for compatibility with
306.Bx 4.3 ,
307where it was used to display the group name in the long
308.Pq Fl l
309format output.
310This option is incompatible with
311.St -p1003.1-2001 .
312.It Fl h
313When used with the
314.Fl l
315option, use unit suffixes: Byte, Kilobyte, Megabyte, Gigabyte, Terabyte
316and Petabyte in order to reduce the number of digits to four or fewer
317using base 2 for sizes.
318This option is not defined in
319.St -p1003.1-2001 .
320.It Fl i
321For each file, print the file's file serial number (inode number).
322.It Fl k
323This has the same effect as setting environment variable
324.Ev BLOCKSIZE
325to 1024, except that it also nullifies any
326.Fl h
327options to its left.
328.It Fl l
329(The lowercase letter
330.Dq ell . )
331List files in the long format, as described in the
332.Sx The Long Format
333subsection below.
334.It Fl m
335Stream output format; list files across the page, separated by commas.
336.It Fl n
337Display user and group IDs numerically rather than converting to a user
338or group name in a long
339.Pq Fl l
340output.
341.It Fl o
342Include the file flags in a long
343.Pq Fl l
344output.
345This option is incompatible with
346.St -p1003.1-2001 .
347See
348.Xr chflags 1
349for a list of file flags and their meanings.
350.It Fl p
351Write a slash
352.Pq Ql /
353after each filename if that file is a directory.
354.It Fl q
355Force printing of non-graphic characters in file names as
356the character
357.Ql \&? ;
358this is the default when output is to a terminal.
359.It Fl r
360Reverse the order of the sort.
361.It Fl s
362Display the number of blocks used in the file system by each file.
363Block sizes and directory totals are handled as described in
364.Sx The Long Format
365subsection below, except (if the long format is not also requested)
366the directory totals are not output when the output is in a
367single column, even if multi-column output is requested.
368.It Fl t
369Sort by descending time modified (most recently modified first).
370If two files have the same modification timestamp, sort their names
371in ascending lexicographical order.
372The
373.Fl r
374option reverses both of these sort orders.
375.Pp
376Note that these sort orders are contradictory: the time sequence is in
377descending order, the lexicographical sort is in ascending order.
378This behavior is mandated by
379.St -p1003.2 .
380This feature can cause problems listing files stored with sequential names on
381FAT file systems, such as from digital cameras, where it is possible to have
382more than one image with the same timestamp.
383In such a case, the photos cannot be listed in the sequence in which
384they were taken.
385To ensure the same sort order for time and for lexicographical sorting, set the
386environment variable
387.Ev LS_SAMESORT
388or use the
389.Fl y
390option.
391This causes
392.Nm
393to reverse the lexicographical sort order when sorting files with the
394same modification timestamp.
395.It Fl u
396Use time of last access,
397instead of time of last modification
398of the file for sorting
399.Pq Fl t
400or printing
401.Pq Fl l .
402.It Fl w
403Force raw printing of non-printable characters.
404This is the default
405when output is not to a terminal.
406This option is not defined in
407.St -p1003.1-2001 .
408.It Fl x
409The same as
410.Fl C ,
411except that the multi-column output is produced with entries sorted
412across, rather than down, the columns.
413.It Fl y
414When the
415.Fl t
416option is set, sort the alphabetical output in the same order as the time output.
417This has the same effect as setting
418.Ev LS_SAMESORT .
419See the description of the
420.Fl t
421option for more details.
422This option is not defined in
423.St -p1003.1-2001 .
424.It Fl 1
425(The numeric digit
426.Dq one . )
427Force output to be
428one entry per line.
429This is the default when
430output is not to a terminal.
431.It Fl ,
432(Comma) When the
433.Fl l
434option is set, print file sizes grouped and separated by thousands using the
435non-monetary separator returned by
436.Xr localeconv 3 ,
437typically a comma or period.
438If no locale is set, or the locale does not have a non-monetary separator, this
439option has no effect.
440This option is not defined in
441.St -p1003.1-2001 .
442.El
443.Pp
444The
445.Fl 1 , C , x ,
446and
447.Fl l
448options all override each other; the last one specified determines
449the format used.
450.Pp
451The
452.Fl c , u ,
453and
454.Fl U
455options all override each other; the last one specified determines
456the file time used.
457.Pp
458The
459.Fl S
460and
461.Fl t
462options override each other; the last one specified determines
463the sort order used.
464.Pp
465The
466.Fl B , b , w ,
467and
468.Fl q
469options all override each other; the last one specified determines
470the format used for non-printable characters.
471.Pp
472The
473.Fl H , L
474and
475.Fl P
476options all override each other (either partially or fully); they
477are applied in the order specified.
478.Pp
479By default,
480.Nm
481lists one entry per line to standard
482output; the exceptions are to terminals or when the
483.Fl C
484or
485.Fl x
486options are specified.
487.Pp
488File information is displayed with one or more
489.Ao blank Ac Ns s
490separating the information associated with the
491.Fl i , s ,
492and
493.Fl l
494options.
495.Ss The Long Format
496If the
497.Fl l
498option is given, the following information
499is displayed for each file:
500file mode,
501number of links, owner name, group name,
502MAC label,
503number of bytes in the file, abbreviated
504month, day-of-month file was last modified,
505hour file last modified, minute file last
506modified, and the pathname.
507.Pp
508If the modification time of the file is more than 6 months
509in the past or future, and the
510.Fl D
511or
512.Fl T
513are not specified,
514then the year of the last modification
515is displayed in place of the hour and minute fields.
516.Pp
517If the owner or group names are not a known user or group name,
518or the
519.Fl n
520option is given,
521the numeric ID's are displayed.
522.Pp
523If the file is a character special or block special file,
524the device number for the file is displayed in the size field.
525If the file is a symbolic link the pathname of the
526linked-to file is preceded by
527.Dq Li -> .
528.Pp
529The listing of a directory's contents is preceded
530by a labeled total number of blocks used in the file system by the files
531which are listed as the directory's contents
532(which may or may not include
533.Pa \&.
534and
535.Pa ..
536and other files which start with a dot, depending on other options).
537.Pp
538The default block size is 512 bytes.
539The block size may be set with option
540.Fl k
541or environment variable
542.Ev BLOCKSIZE .
543Numbers of blocks in the output will have been rounded up so the
544numbers of bytes is at least as many as used by the corresponding
545file system blocks (which might have a different size).
546.Pp
547The file mode printed under the
548.Fl l
549option consists of the
550entry type and the permissions.
551The entry type character describes the type of file, as
552follows:
553.Pp
554.Bl -tag -width 4n -offset indent -compact
555.It Sy \-
556Regular file.
557.It Sy b
558Block special file.
559.It Sy c
560Character special file.
561.It Sy d
562Directory.
563.It Sy l
564Symbolic link.
565.It Sy p
566.Tn FIFO .
567.It Sy s
568Socket.
569.It Sy w
570Whiteout.
571.El
572.Pp
573The next three fields
574are three characters each:
575owner permissions,
576group permissions, and
577other permissions.
578Each field has three character positions:
579.Bl -enum -offset indent
580.It
581If
582.Sy r ,
583the file is readable; if
584.Sy \- ,
585it is not readable.
586.It
587If
588.Sy w ,
589the file is writable; if
590.Sy \- ,
591it is not writable.
592.It
593The first of the following that applies:
594.Bl -tag -width 4n -offset indent
595.It Sy S
596If in the owner permissions, the file is not executable and
597set-user-ID mode is set.
598If in the group permissions, the file is not executable
599and set-group-ID mode is set.
600.It Sy s
601If in the owner permissions, the file is executable
602and set-user-ID mode is set.
603If in the group permissions, the file is executable
604and setgroup-ID mode is set.
605.It Sy x
606The file is executable or the directory is
607searchable.
608.It Sy \-
609The file is neither readable, writable, executable,
610nor set-user-ID nor set-group-ID mode, nor sticky.
611(See below.)
612.El
613.Pp
614These next two apply only to the third character in the last group
615(other permissions).
616.Bl -tag -width 4n -offset indent
617.It Sy T
618The sticky bit is set
619(mode
620.Li 1000 ) ,
621but not execute or search permission.
622(See
623.Xr chmod 1
624or
625.Xr sticky 7 . )
626.It Sy t
627The sticky bit is set (mode
628.Li 1000 ) ,
629and is searchable or executable.
630(See
631.Xr chmod 1
632or
633.Xr sticky 7 . )
634.El
635.El
636.Pp
637The next field contains a
638plus
639.Pq Ql +
640character if the file has an ACL, or a
641space
642.Pq Ql " "
643if it does not.
644The
645.Nm
646utility does not show the actual ACL;
647use
648.Xr getfacl 1
649to do this.
650.Sh ENVIRONMENT
651The following environment variables affect the execution of
652.Nm :
653.Bl -tag -width ".Ev CLICOLOR_FORCE"
654.It Ev BLOCKSIZE
655If this is set, its value, rounded up to 512 or down to a
656multiple of 512, will be used as the block size in bytes by the
657.Fl l
658and
659.Fl s
660options.
661See
662.Sx The Long Format
663subsection for more information.
664.It Ev CLICOLOR
665Use
666.Tn ANSI
667color sequences to distinguish file types.
668See
669.Ev LSCOLORS
670below.
671In addition to the file types mentioned in the
672.Fl F
673option some extra attributes (setuid bit set, etc.) are also displayed.
674The colorization is dependent on a terminal type with the proper
675.Xr termcap 5
676capabilities.
677The default
678.Dq Li cons25
679console has the proper capabilities,
680but to display the colors in an
681.Xr xterm 1 ,
682for example,
683the
684.Ev TERM
685variable must be set to
686.Dq Li xterm-color .
687Other terminal types may require similar adjustments.
688Colorization
689is silently disabled if the output is not directed to a terminal
690unless the
691.Ev CLICOLOR_FORCE
692variable is defined or
693.Fl -color
694is set to
695.Dq always .
696.It Ev CLICOLOR_FORCE
697Color sequences are normally disabled if the output is not directed to
698a terminal.
699This can be overridden by setting this variable.
700The
701.Ev TERM
702variable still needs to reference a color capable terminal however
703otherwise it is not possible to determine which color sequences to
704use.
705.It Ev COLORTERM
706See description for
707.Ev CLICOLOR
708above.
709.It Ev COLUMNS
710If this variable contains a string representing a
711decimal integer, it is used as the
712column position width for displaying
713multiple-text-column output.
714The
715.Nm
716utility calculates how
717many pathname text columns to display
718based on the width provided.
719(See
720.Fl C
721and
722.Fl x . )
723.It Ev LANG
724The locale to use when determining the order of day and month in the long
725.Fl l
726format output.
727See
728.Xr environ 7
729for more information.
730.It Ev LSCOLORS
731The value of this variable describes what color to use for which
732attribute when colors are enabled with
733.Ev CLICOLOR
734or
735.Ev COLORTERM .
736This string is a concatenation of pairs of the format
737.Ar f Ns Ar b ,
738where
739.Ar f
740is the foreground color and
741.Ar b
742is the background color.
743.Pp
744The color designators are as follows:
745.Pp
746.Bl -tag -width 4n -offset indent -compact
747.It Sy a
748black
749.It Sy b
750red
751.It Sy c
752green
753.It Sy d
754brown
755.It Sy e
756blue
757.It Sy f
758magenta
759.It Sy g
760cyan
761.It Sy h
762light grey
763.It Sy A
764bold black, usually shows up as dark grey
765.It Sy B
766bold red
767.It Sy C
768bold green
769.It Sy D
770bold brown, usually shows up as yellow
771.It Sy E
772bold blue
773.It Sy F
774bold magenta
775.It Sy G
776bold cyan
777.It Sy H
778bold light grey; looks like bright white
779.It Sy x
780default foreground or background
781.El
782.Pp
783Note that the above are standard
784.Tn ANSI
785colors.
786The actual display may differ
787depending on the color capabilities of the terminal in use.
788.Pp
789The order of the attributes are as follows:
790.Pp
791.Bl -enum -offset indent -compact
792.It
793directory
794.It
795symbolic link
796.It
797socket
798.It
799pipe
800.It
801executable
802.It
803block special
804.It
805character special
806.It
807executable with setuid bit set
808.It
809executable with setgid bit set
810.It
811directory writable to others, with sticky bit
812.It
813directory writable to others, without sticky bit
814.El
815.Pp
816The default is
817.Qq "exfxcxdxbxegedabagacad" ,
818i.e., blue foreground and
819default background for regular directories, black foreground and red
820background for setuid executables, etc.
821.It Ev LS_COLWIDTHS
822If this variable is set, it is considered to be a
823colon-delimited list of minimum column widths.
824Unreasonable
825and insufficient widths are ignored (thus zero signifies
826a dynamically sized column).
827Not all columns have changeable widths.
828The fields are,
829in order: inode, block count, number of links, user name,
830group name, flags, file size, file name.
831.It Ev LS_SAMESORT
832If this variable is set, the
833.Fl t
834option sorts the names of files with the same modification timestamp in the same
835sense as the time sort.
836See the description of the
837.Fl t
838option for more details.
839.It Ev TERM
840The
841.Ev CLICOLOR
842and
843.Ev COLORTERM
844functionality depends on a terminal type with color capabilities.
845.It Ev TZ
846The timezone to use when displaying dates.
847See
848.Xr environ 7
849for more information.
850.El
851.Sh EXIT STATUS
852.Ex -std
853.Sh EXAMPLES
854List the contents of the current working directory in long format:
855.Pp
856.Dl $ ls -l
857.Pp
858In addition to listing the contents of the current working directory in
859long format, show inode numbers, file flags (see
860.Xr chflags 1 ) ,
861and suffix each filename with a symbol representing its file type:
862.Pp
863.Dl $ ls -lioF
864.Pp
865List the files in
866.Pa /var/log ,
867sorting the output such that the mostly recently modified entries are
868printed first:
869.Pp
870.Dl $ ls -lt /var/log
871.Sh COMPATIBILITY
872The group field is now automatically included in the long listing for
873files in order to be compatible with the
874.St -p1003.2
875specification.
876.Sh SEE ALSO
877.Xr chflags 1 ,
878.Xr chmod 1 ,
879.Xr getfacl 1 ,
880.Xr sort 1 ,
881.Xr xterm 1 ,
882.Xr localeconv 3 ,
883.Xr strftime 3 ,
884.Xr strmode 3 ,
885.Xr termcap 5 ,
886.Xr maclabel 7 ,
887.Xr sticky 7 ,
888.Xr symlink 7 ,
889.Xr getfmac 8
890.Sh STANDARDS
891With the exception of options
892.Fl g , n
893and
894.Fl o ,
895the
896.Nm
897utility conforms to
898.St -p1003.1-2008 .
899The options
900.Fl B , D , G , I , T , U , W , Z , b , h , w , y
901and
902.Fl ,
903are compatible extensions not defined in
904.St -p1003.1-2008 .
905.Pp
906The ACL support is compatible with
907.Tn IEEE
908Std\~1003.2c
909.Pq Dq Tn POSIX Ns .2c
910Draft\~17
911(withdrawn).
912.Sh HISTORY
913An
914.Nm
915command appeared in
916.At v1 .
917.Sh BUGS
918To maintain backward compatibility, the relationships between the many
919options are quite complex.
920.Pp
921The exception mentioned in the
922.Fl s
923option description might be a feature that was
924based on the fact that single-column output
925usually goes to something other than a terminal.
926It is debatable whether this is a design bug.
927.Pp
928.St -p1003.2
929mandates opposite sort orders for files with the same timestamp when
930sorting with the
931.Fl t
932option.
933