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