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