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