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