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 If the output is to a terminal, 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 .El
 282 .Pp
 283 The
 284 .Fl 1 , C , x ,
 285 and
 286 .Fl l
 287 options all override each other;
 288 the last one specified determines the format used.
 289 .Pp
 290 The
 291 .Fl c
 292 and
 293 .Fl u
 294 options override each other; the last one specified determines
 295 the file time used.
 296 .Pp
 297 The
 298 .Fl B , b , w ,
 299 and
 300 .Fl q
 301 options all override each other;
 302 the last one specified determines the format used
 303 for non-printable characters.
 304 .Pp
 305 The
 306 .Fl H , L
 307 and
 308 .Fl P
 309 options all override each other (either partially or fully); they
 310 are applied in the order specified.
 311 .Pp
 312 By default,
 313 .Nm ls
 314 lists one entry per line to standard
 315 output; the exceptions are to terminals or when the
 316 .Fl C
 317 or
 318 .Fl x
 319 options are specified.
 320 .Pp
 321 File information is displayed with one or more
 322 .Ao blank Ac Ns s
 323 separating the information associated with the
 324 .Fl i , s ,
 325 and
 326 .Fl l
 327 options.
 328 .Ss The Long Format
 329 If the
 330 .Fl l
 331 option is given, the following information
 332 is displayed for each file:
 333 file mode,
 334 number of links, owner name, group name,
 335 number of bytes in the file, abbreviated
 336 month, day-of-month file was last modified,
 337 hour file last modified, minute file last
 338 modified, and the pathname.
 339 In addition, for each directory whose contents are displayed,
 340 the total number of 512-byte blocks used by the files in the directory
 341 is displayed on a line by itself,
 342 immediately before the information for the files in the directory.
 343 If the file or directory has extended attributes,
 344 the permissions field printed by the
 345 .Fl l
 346 option is followed by a '@' character.
 347 Otherwise, if the file or directory has extended security information
 348 (such as an access control list),
 349 the permissions field printed by the
 350 .Fl l
 351 option is followed by a '+' character.
 352 .Pp
 353 If the modification time of the file
 354 is more than 6 months in the past or future,
 355 then the year of the last modification
 356 is displayed in place of the hour and minute fields.
 357 .Pp
 358 If the owner or group names are not a known user or group name,
 359 or the
 360 .Fl n
 361 option is given,
 362 the numeric ID's are displayed.
 363 .Pp
 364 If the file is a character special or block special file,
 365 the major and minor device numbers for the file are displayed
 366 in the size field.
 367 If the file is a symbolic link,
 368 the pathname of the linked-to file is preceded by
 369 .Dq Li -> .
 370 .Pp
 371 The file mode printed under the
 372 .Fl l
 373 option consists of the
 374 entry type, owner permissions, and group permissions.
 375 The entry type character describes the type of file,
 376 as follows:
 377 .Pp
 378 .Bl -tag -width 4n -offset indent -compact
 379 .It Sy b
 380 Block special file.
 381 .It Sy c
 382 Character special file.
 383 .It Sy d
 384 Directory.
 385 .It Sy l
 386 Symbolic link.
 387 .It Sy s
 388 Socket link.
 389 .It Sy p
 390 .Tn FIFO .
 391 .It Sy \-
 392 Regular file.
 393 .El
 394 .Pp
 395 The next three fields
 396 are three characters each:
 397 owner permissions,
 398 group permissions, and
 399 other permissions.
 400 Each field has three character positions:
 401 .Bl -enum -offset indent
 402 .It
 403 If
 404 .Sy r ,
 405 the file is readable; if
 406 .Sy \- ,
 407 it is not readable.
 408 .It
 409 If
 410 .Sy w ,
 411 the file is writable; if
 412 .Sy \- ,
 413 it is not writable.
 414 .It
 415 The first of the following that applies:
 416 .Bl -tag -width 4n -offset indent
 417 .It Sy S
 418 If in the owner permissions, the file is not executable and
 419 set-user-ID mode is set.
 420 If in the group permissions, the file is not executable
 421 and set-group-ID mode is set.
 422 .It Sy s
 423 If in the owner permissions, the file is executable
 424 and set-user-ID mode is set.
 425 If in the group permissions, the file is executable
 426 and setgroup-ID mode is set.
 427 .It Sy x
 428 The file is executable or the directory is
 429 searchable.
 430 .It Sy \-
 431 The file is neither readable, writable, executable,
 432 nor set-user-ID nor set-group-ID mode, nor sticky.
 433 (See below.)
 434 .El
 435 .Pp
 436 These next two apply only to the third character in the last group
 437 (other permissions).
 438 .Bl -tag -width 4n -offset indent
 439 .It Sy T
 440 The sticky bit is set
 441 (mode
 442 .Li 1000 ) ,
 443 but not execute or search permission.
 444 (See
 445 .Xr chmod 1
 446 or
 447 .Xr sticky 8 . )
 448 .It Sy t
 449 The sticky bit is set (mode
 450 .Li 1000 ) ,
 451 and is searchable or executable.
 452 (See
 453 .Xr chmod 1
 454 or
 455 .Xr sticky 8 . )
 456 .El
 457 .El
 458 .Sh EXAMPLES
 459 The following is how to do an
 460 .Nm ls
 461 listing sorted by increasing size
 462 .Pp
 463 .Dl "ls -lrS"
 464 .Sh DIAGNOSTICS
 465 .Ex -std
 466 .Sh ENVIRONMENT
 467 The following environment variables affect the execution of
 468 .Nm ls :
 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 \*[Ai]
 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 isn't 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 isn't directed to
 508 a terminal.
 509 This can be overridden by setting this flag.
 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 ls
 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 \*[Ai]
 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 LEGACY DESCRIPTION
 651 In legacy mode, the
 652 .Fl f
 653 option does not turn on the
 654 .Fl a
 655 option and the
 656 .Fl g ,
 657 .Fl n ,
 658 and
 659 .Fl o
 660 options do not turn on the
 661 .Fl l
 662 option.
 663 .Pp
 664 Also, the
 665 .Fl o
 666 option causes the file flags to be included in a long (-l) output;
 667 there is no
 668 .Fl O
 669 option.
 670 .Pp
 671 When
 672 .Fl H
 673 is specified (and not overridden by
 674 .Fl L
 675 or
 676 .Fl P )
 677 and a file argument is a symlink
 678 that resolves to a non-directory file,
 679 the output will reflect the nature of the link,
 680 rather than that of the file.
 681 In legacy operation, the output will describe the file.
 682 .Pp
 683 For more information about legacy mode, see
 684 .Xr compat 5 .
 685 .Sh SEE ALSO
 686 .Xr chflags 1 ,
 687 .Xr chmod 1 ,
 688 .Xr sort 1 ,
 689 .Xr xterm 1 ,
 690 .Xr compat 5 ,
 691 .Xr termcap 5 ,
 692 .Xr symlink 7 ,
 693 .Xr sticky 8
 694 .Sh STANDARDS
 695 The
 696 .Nm ls
 697 utility conforms to
 698 .St -p1003.1-2001 .
 699 .Sh HISTORY
 700 An
 701 .Nm ls
 702 command appeared in
 703 .At v1 .
 704 .Sh BUGS
 705 To maintain backward compatibility, the relationships between the many
 706 options are quite complex.