bin/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 .\" 4. Neither the name of the University nor the names of its contributors
  16 .\"    may be used to endorse or promote products derived from this software
  17 .\"    without specific prior written permission.
  18 .\"
  19 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  20 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  21 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  22 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  23 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  24 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  25 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  26 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  27 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  28 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  29 .\" SUCH DAMAGE.
  30 .\"
  31 .\"     @(#)ls.1        8.7 (Berkeley) 7/29/94
  32 .\" $FreeBSD: src/bin/ls/ls.1,v 1.86 2005/02/13 22:25:09 ru Exp $
  33 .\" $DragonFly: src/bin/ls/ls.1,v 1.9 2008/09/25 09:09:06 matthias Exp $
  34 .\"
  35 .Dd September 25, 2008
  36 .Dt LS 1
  37 .Os
  38 .Sh NAME
  39 .Nm ls
  40 .Nd list directory contents
  41 .Sh SYNOPSIS
  42 .Nm
  43 .Op Fl ABCFGHLPRTWabcdfghiklmnopqrstuwxy1
  44 .Op Ar
  45 .Sh DESCRIPTION
  46 For each operand that names a
  47 .Ar file
  48 of a type other than
  49 directory,
  50 .Nm
  51 displays its name as well as any requested,
  52 associated information.
  53 For each operand that names a
  54 .Ar file
  55 of type directory,
  56 .Nm
  57 displays the names of files contained
  58 within that directory, as well as any requested, associated
  59 information.
  60 .Pp
  61 If no operands are given, the contents of the current
  62 directory are displayed.
  63 If more than one operand is given,
  64 non-directory operands are displayed first; directory
  65 and non-directory operands are sorted separately and in
  66 lexicographical order.
  67 .Pp
  68 The following options are available:
  69 .Bl -tag -width indent
  70 .It Fl A
  71 List all entries except for
  72 .Pa \&.
  73 and
  74 .Pa .. .
  75 Always set for the super-user.
  76 .It Fl B
  77 Force printing of non-printable characters (as defined by
  78 .Xr ctype 3
  79 and current locale settings) in file names as
  80 .Li \e Ns Va xxx ,
  81 where
  82 .Va xxx
  83 is the numeric value of the character in octal.
  84 .It Fl C
  85 Force multi-column output; this is the default when output is to a terminal.
  86 .It Fl F
  87 Display a slash
  88 .Pq Ql /
  89 immediately after each pathname that is a directory,
  90 an asterisk
  91 .Pq Ql *
  92 after each that is executable,
  93 an at sign
  94 .Pq Ql @
  95 after each symbolic link,
  96 an equals sign
  97 .Pq Ql =
  98 after each socket,
  99 a percent sign
 100 .Pq Ql %
 101 after each whiteout,
 102 and a vertical bar
 103 .Pq Ql \&|
 104 after each that is a
 105 .Tn FIFO .
 106 .It Fl G
 107 Enable colorized output.
 108 This option is equivalent to defining
 109 .Ev CLICOLOR
 110 in the environment.
 111 (See below.)
 112 .It Fl H
 113 Symbolic links on the command line are followed.
 114 This option is assumed if
 115 none of the
 116 .Fl F , d ,
 117 or
 118 .Fl l
 119 options are specified.
 120 .It Fl L
 121 If argument is a symbolic link, list the file or directory the link references
 122 rather than the link itself.
 123 This option cancels the
 124 .Fl P
 125 option.
 126 .It Fl P
 127 If argument is a symbolic link, list the link itself rather than the
 128 object the link references.
 129 This option cancels the
 130 .Fl H
 131 and
 132 .Fl L
 133 options.
 134 .It Fl R
 135 Recursively list subdirectories encountered.
 136 .It Fl S
 137 Use the size of a file for sorting
 138 .Pq Fl t .
 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 four or fewer
 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 Note that
 187 .Fl k
 188 is mutually exclusive to
 189 .Fl h ,
 190 and later
 191 .Fl k
 192 will nullify earlier
 193 .Fl h .
 194 .It Fl l
 195 (The lowercase letter
 196 .Dq ell . )
 197 List in long format.
 198 (See below.)
 199 A total sum (in blocks, see the
 200 .Fl s
 201 option for the block size unit) for all the file
 202 sizes is output on a line before the long listing.
 203 .It Fl m
 204 Stream output format; list files across the page, separated by commas.
 205 .It Fl n
 206 Display user and group IDs numerically rather than converting to a user
 207 or group name in a long
 208 .Pq Fl l
 209 output.
 210 .It Fl o
 211 Include the file flags in a long
 212 .Pq Fl l
 213 output.
 214 .It Fl p
 215 Write a slash
 216 .Pq Ql /
 217 after each filename if that file is a directory.
 218 .It Fl q
 219 Force printing of non-graphic characters in file names as
 220 the character
 221 .Ql \&? ;
 222 this is the default when output is to a terminal.
 223 .It Fl r
 224 Reverse the order of the sort to get reverse
 225 lexicographical order or the oldest entries first.
 226 .It Fl s
 227 Display the number of file system blocks actually used by each file, in units
 228 of 512 bytes, where partial units are rounded up to the next integer value.
 229 A total sum for all the file
 230 sizes is output on a line before the listing.
 231 The environment variable
 232 .Ev BLOCKSIZE
 233 overrides the unit size of 512 bytes.
 234 .It Fl t
 235 Sort by time modified (most recently modified
 236 first) before sorting the operands by lexicographical
 237 order.
 238 .It Fl u
 239 Use time of last access,
 240 instead of last modification
 241 of the file for sorting
 242 .Pq Fl t
 243 or printing
 244 .Pq Fl l .
 245 .It Fl w
 246 Force raw printing of non-printable characters.
 247 This is the default
 248 when output is not to a terminal.
 249 .It Fl x
 250 The same as
 251 .Fl C ,
 252 except that the multi-column output is produced with entries sorted
 253 across, rather than down, the columns.
 254 .It Fl y
 255 Include the FSMID field in a long
 256 .Pq Fl l
 257 output.
 258 .It Fl 1
 259 (The numeric digit
 260 .Dq one . )
 261 Force output to be
 262 one entry per line.
 263 This is the default when
 264 output is not to a terminal.
 265 .El
 266 .Pp
 267 The
 268 .Fl 1 , C , x ,
 269 and
 270 .Fl l
 271 options all override each other; the last one specified determines
 272 the format used.
 273 .Pp
 274 The
 275 .Fl c
 276 and
 277 .Fl u
 278 options override each other; the last one specified determines
 279 the file time used.
 280 .Pp
 281 The
 282 .Fl B , b , w ,
 283 and
 284 .Fl q
 285 options all override each other; the last one specified determines
 286 the format used for non-printable characters.
 287 .Pp
 288 The
 289 .Fl H , L
 290 and
 291 .Fl P
 292 options all override each other (either partially or fully); they
 293 are applied in the order specified.
 294 .Pp
 295 By default,
 296 .Nm
 297 lists one entry per line to standard
 298 output; the exceptions are to terminals or when the
 299 .Fl C
 300 or
 301 .Fl x
 302 options are specified.
 303 .Pp
 304 File information is displayed with one or more
 305 .Ao blank Ac Ns s
 306 separating the information associated with the
 307 .Fl i , s ,
 308 and
 309 .Fl l
 310 options.
 311 .Ss The Long Format
 312 If the
 313 .Fl l
 314 option is given, the following information
 315 is displayed for each file:
 316 file mode,
 317 number of links, owner name, group name,
 318 number of bytes in the file, abbreviated
 319 month, day-of-month file was last modified,
 320 hour file last modified, minute file last
 321 modified, and the pathname.
 322 In addition, for each directory whose contents are displayed, the total
 323 number of 512-byte blocks used by the files in the directory is displayed
 324 on a line by itself immediately before the information for the files in the
 325 directory.
 326 .Pp
 327 If the modification time of the file is more than 6 months
 328 in the past or future, then the year of the last modification
 329 is displayed in place of the hour and minute fields.
 330 .Pp
 331 If the owner or group names are not a known user or group name,
 332 or the
 333 .Fl n
 334 option is given,
 335 the numeric ID's are displayed.
 336 .Pp
 337 If the file is a character special or block special file,
 338 the major and minor device numbers for the file are displayed
 339 in the size field.
 340 If the file is a symbolic link the pathname of the
 341 linked-to file is preceded by
 342 .Dq Li -> .
 343 .Pp
 344 The file mode printed under the
 345 .Fl l
 346 option consists of the
 347 entry type and the permissions.
 348 The entry type character describes the type of file, as
 349 follows:
 350 .Pp
 351 .Bl -tag -width 4n -offset indent -compact
 352 .It Sy b
 353 Block special file.
 354 .It Sy c
 355 Character special file.
 356 .It Sy d
 357 Directory.
 358 .It Sy l
 359 Symbolic link.
 360 .It Sy s
 361 Socket link.
 362 .It Sy p
 363 .Tn FIFO .
 364 .It Sy \-
 365 Regular file.
 366 .El
 367 .Pp
 368 The next three fields
 369 are three characters each:
 370 owner permissions,
 371 group permissions, and
 372 other permissions.
 373 Each field has three character positions:
 374 .Bl -enum -offset indent
 375 .It
 376 If
 377 .Sy r ,
 378 the file is readable; if
 379 .Sy \- ,
 380 it is not readable.
 381 .It
 382 If
 383 .Sy w ,
 384 the file is writable; if
 385 .Sy \- ,
 386 it is not writable.
 387 .It
 388 The first of the following that applies:
 389 .Bl -tag -width 4n -offset indent
 390 .It Sy S
 391 If in the owner permissions, the file is not executable and
 392 set-user-ID mode is set.
 393 If in the group permissions, the file is not executable
 394 and set-group-ID mode is set.
 395 .It Sy s
 396 If in the owner permissions, the file is executable
 397 and set-user-ID mode is set.
 398 If in the group permissions, the file is executable
 399 and setgroup-ID mode is set.
 400 .It Sy x
 401 The file is executable or the directory is
 402 searchable.
 403 .It Sy \-
 404 The file is neither readable, writable, executable,
 405 nor set-user-ID nor set-group-ID mode, nor sticky.
 406 (See below.)
 407 .El
 408 .Pp
 409 These next two apply only to the third character in the last group
 410 (other permissions).
 411 .Bl -tag -width 4n -offset indent
 412 .It Sy T
 413 The sticky bit is set
 414 (mode
 415 .Li 1000 ) ,
 416 but not execute or search permission.
 417 (See
 418 .Xr chmod 1
 419 or
 420 .Xr sticky 8 . )
 421 .It Sy t
 422 The sticky bit is set (mode
 423 .Li 1000 ) ,
 424 and is searchable or executable.
 425 (See
 426 .Xr chmod 1
 427 or
 428 .Xr sticky 8 . )
 429 .El
 430 .El
 431 .Sh ENVIRONMENT
 432 The following environment variables affect the execution of
 433 .Nm :
 434 .Bl -tag -width ".Ev CLICOLOR_FORCE"
 435 .It Ev BLOCKSIZE
 436 If the environment variable
 437 .Ev BLOCKSIZE
 438 is set, the block counts
 439 (see
 440 .Fl s )
 441 will be displayed in units of that size block.
 442 .It Ev CLICOLOR
 443 Use
 444 .Tn ANSI
 445 color sequences to distinguish file types.
 446 See
 447 .Ev LSCOLORS
 448 below.
 449 In addition to the file types mentioned in the
 450 .Fl F
 451 option some extra attributes (setuid bit set, etc.) are also displayed.
 452 The colorization is dependent on a terminal type with the proper
 453 .Xr termcap 5
 454 capabilities.
 455 The default
 456 .Dq Li cons25
 457 console has the proper capabilities,
 458 but to display the colors in an
 459 .Xr xterm 1 ,
 460 for example,
 461 the
 462 .Ev TERM
 463 variable must be set to
 464 .Dq Li xterm-color .
 465 Other terminal types may require similar adjustments.
 466 Colorization
 467 is silently disabled if the output is not directed to a terminal
 468 unless the
 469 .Ev CLICOLOR_FORCE
 470 variable is defined.
 471 .It Ev CLICOLOR_FORCE
 472 Color sequences are normally disabled if the output is not directed to
 473 a terminal.
 474 This can be overridden by setting this flag.
 475 The
 476 .Ev TERM
 477 variable still needs to reference a color capable terminal however
 478 otherwise it is not possible to determine which color sequences to
 479 use.
 480 .It Ev COLUMNS
 481 If this variable contains a string representing a
 482 decimal integer, it is used as the
 483 column position width for displaying
 484 multiple-text-column output.
 485 The
 486 .Nm
 487 utility calculates how
 488 many pathname text columns to display
 489 based on the width provided.
 490 (See
 491 .Fl C
 492 and
 493 .Fl x . )
 494 .It Ev LANG
 495 The locale to use when determining the order of day and month in the long
 496 .Fl l
 497 format output.
 498 See
 499 .Xr environ 7
 500 for more information.
 501 .It Ev LSCOLORS
 502 The value of this variable describes what color to use for which
 503 attribute when colors are enabled with
 504 .Ev CLICOLOR .
 505 This string is a concatenation of pairs of the format
 506 .Ar f Ns Ar b ,
 507 where
 508 .Ar f
 509 is the foreground color and
 510 .Ar b
 511 is the background color.
 512 .Pp
 513 The color designators are as follows:
 514 .Pp
 515 .Bl -tag -width 4n -offset indent -compact
 516 .It Sy a
 517 black
 518 .It Sy b
 519 red
 520 .It Sy c
 521 green
 522 .It Sy d
 523 brown
 524 .It Sy e
 525 blue
 526 .It Sy f
 527 magenta
 528 .It Sy g
 529 cyan
 530 .It Sy h
 531 light grey
 532 .It Sy A
 533 bold black, usually shows up as dark grey
 534 .It Sy B
 535 bold red
 536 .It Sy C
 537 bold green
 538 .It Sy D
 539 bold brown, usually shows up as yellow
 540 .It Sy E
 541 bold blue
 542 .It Sy F
 543 bold magenta
 544 .It Sy G
 545 bold cyan
 546 .It Sy H
 547 bold light grey; looks like bright white
 548 .It Sy x
 549 default foreground or background
 550 .El
 551 .Pp
 552 Note that the above are standard
 553 .Tn ANSI
 554 colors.
 555 The actual display may differ
 556 depending on the color capabilities of the terminal in use.
 557 .Pp
 558 The order of the attributes are as follows:
 559 .Pp
 560 .Bl -enum -offset indent -compact
 561 .It
 562 directory
 563 .It
 564 symbolic link
 565 .It
 566 socket
 567 .It
 568 pipe
 569 .It
 570 executable
 571 .It
 572 block special
 573 .It
 574 character special
 575 .It
 576 executable with setuid bit set
 577 .It
 578 executable with setgid bit set
 579 .It
 580 directory writable to others, with sticky bit
 581 .It
 582 directory writable to others, without sticky bit
 583 .El
 584 .Pp
 585 The default is
 586 .Qq "exfxcxdxbxegedabagacad" ,
 587 i.e., blue foreground and
 588 default background for regular directories, black foreground and red
 589 background for setuid executables, etc.
 590 .It Ev LS_COLWIDTHS
 591 If this variable is set, it is considered to be a
 592 colon-delimited list of minimum column widths.
 593 Unreasonable
 594 and insufficient widths are ignored (thus zero signifies
 595 a dynamically sized column).
 596 Not all columns have changeable widths.
 597 The fields are,
 598 in order: inode, block count, number of links, user name,
 599 group name, flags, file size, file name.
 600 .It Ev TERM
 601 The
 602 .Ev CLICOLOR
 603 functionality depends on a terminal type with color capabilities.
 604 .It Ev TZ
 605 The timezone to use when displaying dates.
 606 See
 607 .Xr environ 7
 608 for more information.
 609 .El
 610 .Sh COMPATIBILITY
 611 The group field is now automatically included in the long listing for
 612 files in order to be compatible with the
 613 .St -p1003.2
 614 specification.
 615 .Sh SEE ALSO
 616 .Xr chflags 1 ,
 617 .Xr chmod 1 ,
 618 .Xr sort 1 ,
 619 .Xr xterm 1 Pq Pa pkgsrc/x11/xterm ,
 620 .Xr termcap 5 ,
 621 .Xr symlink 7 ,
 622 .Xr sticky 8
 623 .Sh STANDARDS
 624 With the exception of options
 625 .Fl g ,
 626 .Fl n
 627 and
 628 .Fl o ,
 629 the
 630 .Nm
 631 utility conforms to
 632 .St -p1003.1-2001 .
 633 .Sh HISTORY
 634 An
 635 .Nm
 636 command appeared in
 637 .At v1 .
 638 .Sh BUGS
 639 To maintain backward compatibility, the relationships between the many
 640 options are quite complex.