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