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