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