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