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