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 .\" 3. 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 .\"
  34 .Dd December 28, 2020
  35 .Dt LS 1
  36 .Os
  37 .Sh NAME
  38 .Nm ls
  39 .Nd list directory contents
  40 .Sh SYNOPSIS
  41 .Nm
  42 .Op Fl 1ABCFGHILPRSTW_abcdfghiklmnopqrstuwxy
  43 .Op Fl D Ar format
  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, including dot files, except for dot and dot-dot.
  72 Always set for the super-user, but may be turned
  73 off with
  74 .Fl I .
  75 .It Fl B
  76 Force printing of non-printable characters (as defined by
  77 .Xr ctype 3
  78 and current locale settings) in file names as
  79 .Li \e Ns Va xxx ,
  80 where
  81 .Va xxx
  82 is the numeric value of the character in octal.
  83 .It Fl C
  84 Force multi-column output; this is the default when output is to a terminal.
  85 .It Fl D Ar format
  86 When printing in the long
  87 .Pq Fl l
  88 format, use
  89 .Ar format
  90 to format the date and time output.
  91 The argument
  92 .Ar format
  93 is a string used by
  94 .Xr strftime 3 .
  95 Depending on the choice of format string, this may result in a
  96 different number of columns in the output.
  97 This option overrides the
  98 .Fl T
  99 option.
 100 .It Fl F
 101 Display a slash
 102 .Pq Ql /
 103 immediately after each pathname that is a directory,
 104 an asterisk
 105 .Pq Ql *
 106 after each that is executable,
 107 an at sign
 108 .Pq Ql @
 109 after each symbolic link,
 110 an equals sign
 111 .Pq Ql =
 112 after each socket,
 113 a percent sign
 114 .Pq Ql %
 115 after each whiteout,
 116 and a vertical bar
 117 .Pq Ql \&|
 118 after each that is a
 119 .Tn FIFO .
 120 .It Fl G
 121 Enable colorized output.
 122 This option is equivalent to defining
 123 .Ev CLICOLOR
 124 in the environment.
 125 (See below.)
 126 This functionality can be compiled out by removing the definition of
 127 .Ev COLORLS .
 128 .It Fl H
 129 Symbolic links on the command line are followed.
 130 This option is assumed if
 131 none of the
 132 .Fl F , d ,
 133 or
 134 .Fl l
 135 options are specified.
 136 .It Fl I
 137 This turns off the listing of dot files.
 138 Dot files are listed by default when
 139 .Nm
 140 is run as root.
 141 Note that the
 142 .Fl I
 143 and
 144 .Fl A
 145 options will override each other.
 146 .It Fl L
 147 If argument is a symbolic link, list the file or directory the link references
 148 rather than the link itself.
 149 This option cancels the
 150 .Fl P
 151 option.
 152 .It Fl P
 153 If argument is a symbolic link, list the link itself rather than the
 154 object the link references.
 155 This option cancels the
 156 .Fl H
 157 and
 158 .Fl L
 159 options.
 160 .It Fl R
 161 Recursively list subdirectories encountered.
 162 .It Fl S
 163 Sort by size (largest file first) before sorting the operands in
 164 lexicographical order.
 165 .It Fl T
 166 When used with the
 167 .Fl l
 168 (lowercase letter
 169 .Dq ell )
 170 option, display complete time information for the file, including
 171 month, day, hour, minute, second, and year (named locales use the
 172 ISO 8601 extended format).
 173 .It Fl W
 174 Display whiteouts when scanning directories.
 175 .It Fl a
 176 Include directory entries whose names begin with a
 177 dot
 178 .Pq Pa \&. .
 179 .It Fl b
 180 As
 181 .Fl B ,
 182 but use
 183 .Tn C
 184 escape codes whenever possible.
 185 .It Fl c
 186 Use time when file status was last changed for sorting or printing.
 187 .It Fl d
 188 Directories are listed as plain files (not searched recursively).
 189 .It Fl f
 190 Output is not sorted.
 191 This option implies
 192 .Fl a .
 193 .It Fl g
 194 This option is deprecated and is only available for compatibility
 195 with
 196 .Bx 4.3 ;
 197 it was used to display the group name in the long
 198 .Pq Fl l
 199 format output.
 200 .It Fl h
 201 When used with the
 202 .Fl l
 203 option, use unit suffixes: Byte, Kilobyte, Megabyte, Gigabyte, Terabyte
 204 and Petabyte in order to reduce the number of digits to four or fewer
 205 using base 2 for sizes.
 206 .It Fl i
 207 For each file, print the file's file serial number (inode number).
 208 .It Fl k
 209 If the
 210 .Fl s
 211 option is specified, print the file size allocation in kilobytes,
 212 not blocks.
 213 This option overrides the environment variable
 214 .Ev BLOCKSIZE .
 215 Note that
 216 .Fl k
 217 is mutually exclusive to
 218 .Fl h ,
 219 and later
 220 .Fl k
 221 will nullify earlier
 222 .Fl h .
 223 .It Fl l
 224 (The lowercase letter
 225 .Dq ell . )
 226 List in long format.
 227 (See below.)
 228 A total sum (in blocks, see the
 229 .Fl s
 230 option for the block size unit) for all the file
 231 sizes is output on a line before the long listing.
 232 .It Fl m
 233 Stream output format; list files across the page, separated by commas.
 234 .It Fl n
 235 Display user and group IDs numerically rather than converting to a user
 236 or group name in a long
 237 .Pq Fl l
 238 output.
 239 .It Fl o
 240 Include the file flags in a long
 241 .Pq Fl l
 242 output.
 243 .It Fl p
 244 Write a slash
 245 .Pq Ql /
 246 after each filename if that file is a directory.
 247 .It Fl q
 248 Force printing of non-graphic characters in file names as
 249 the character
 250 .Ql \&? ;
 251 this is the default when output is to a terminal.
 252 .It Fl r
 253 Reverse the order of the sort to get reverse
 254 lexicographical order or the oldest entries first.
 255 .It Fl s
 256 Display the number of file system blocks actually used by each file, in units
 257 of 512 bytes, where partial units are rounded up to the next integer value.
 258 A total sum for all the file
 259 sizes is output on a line before the listing.
 260 The environment variable
 261 .Ev BLOCKSIZE
 262 overrides the unit size of 512 bytes.
 263 .It Fl t
 264 Sort by time modified (most recently modified
 265 first) before sorting the operands by lexicographical
 266 order.
 267 .It Fl u
 268 Use time of last access,
 269 instead of last modification
 270 of the file for sorting
 271 .Pq Fl t
 272 or printing
 273 .Pq Fl l .
 274 .It Fl w
 275 Force raw printing of non-printable characters.
 276 This is the default
 277 when output is not to a terminal.
 278 .It Fl x
 279 The same as
 280 .Fl C ,
 281 except that the multi-column output is produced with entries sorted
 282 across, rather than down, the columns.
 283 .It Fl 1
 284 (The numeric digit
 285 .Dq one . )
 286 Force output to be
 287 one entry per line.
 288 This is the default when
 289 output is not to a terminal.
 290 .It Fl _
 291 (underscore) When printing in the long
 292 .Pq Fl l
 293 format, use GMT based date and time output with nanotime timestamp.
 294 .El
 295 .Pp
 296 The
 297 .Fl 1 , C , x ,
 298 and
 299 .Fl l
 300 options all override each other; the last one specified determines
 301 the format used.
 302 .Pp
 303 The
 304 .Fl c
 305 and
 306 .Fl u
 307 options override each other; the last one specified determines
 308 the file time used.
 309 .Pp
 310 The
 311 .Fl S
 312 and
 313 .Fl t
 314 options override each other; the last one specified determines
 315 the sort order used.
 316 .Pp
 317 The
 318 .Fl B , b , w ,
 319 and
 320 .Fl q
 321 options all override each other; the last one specified determines
 322 the format used for non-printable characters.
 323 .Pp
 324 The
 325 .Fl H , L
 326 and
 327 .Fl P
 328 options all override each other (either partially or fully); they
 329 are applied in the order specified.
 330 .Pp
 331 By default,
 332 .Nm
 333 lists one entry per line to standard
 334 output; the exceptions are to terminals or when the
 335 .Fl C
 336 or
 337 .Fl x
 338 options are specified.
 339 .Pp
 340 File information is displayed with one or more
 341 .Ao blank Ac Ns s
 342 separating the information associated with the
 343 .Fl i , s ,
 344 and
 345 .Fl l
 346 options.
 347 .Ss The Long Format
 348 If the
 349 .Fl l
 350 option is given, the following information
 351 is displayed for each file:
 352 file mode,
 353 number of links, owner name, group name,
 354 number of bytes in the file,
 355 last modified time in either per POSIX requirements or
 356 using the format DD-MMM-YYYY hh:ss, and the pathname.
 357 In addition, for each directory whose contents are displayed, the total
 358 number of 512-byte blocks used by the files in the directory is displayed
 359 on a line by itself immediately before the information for the files in the
 360 directory.
 361 .Pp
 362 In the POSIX locale, If the modification time of the file is in the future,
 363 or more than 6 months in the past, then the year of the last modification
 364 is displayed in place of the hour and minute fields.
 365 .Pp
 366 If the owner or group names are not a known user or group name,
 367 or the
 368 .Fl n
 369 option is given,
 370 the numeric ID's are displayed.
 371 .Pp
 372 If the file is a character special or block special file,
 373 the major and minor device numbers for the file are displayed
 374 in the size field.
 375 If the file is a symbolic link the pathname of the
 376 linked-to file is preceded by
 377 .Dq Li -> .
 378 .Pp
 379 The file mode printed under the
 380 .Fl l
 381 option consists of the
 382 entry type and the permissions.
 383 The entry type character describes the type of file, as
 384 follows:
 385 .Pp
 386 .Bl -tag -width 4n -offset indent -compact
 387 .It Sy b
 388 Block special file.
 389 .It Sy c
 390 Character special file.
 391 .It Sy d
 392 Directory.
 393 .It Sy l
 394 Symbolic link.
 395 .It Sy s
 396 Socket link.
 397 .It Sy p
 398 .Tn FIFO .
 399 .It Sy \-
 400 Regular file.
 401 .El
 402 .Pp
 403 The next three fields
 404 are three characters each:
 405 owner permissions,
 406 group permissions, and
 407 other permissions.
 408 Each field has three character positions:
 409 .Bl -enum -offset indent
 410 .It
 411 If
 412 .Sy r ,
 413 the file is readable; if
 414 .Sy \- ,
 415 it is not readable.
 416 .It
 417 If
 418 .Sy w ,
 419 the file is writable; if
 420 .Sy \- ,
 421 it is not writable.
 422 .It
 423 The first of the following that applies:
 424 .Bl -tag -width 4n -offset indent
 425 .It Sy S
 426 If in the owner permissions, the file is not executable and
 427 set-user-ID mode is set.
 428 If in the group permissions, the file is not executable
 429 and set-group-ID mode is set.
 430 .It Sy s
 431 If in the owner permissions, the file is executable
 432 and set-user-ID mode is set.
 433 If in the group permissions, the file is executable
 434 and setgroup-ID mode is set.
 435 .It Sy x
 436 The file is executable or the directory is
 437 searchable.
 438 .It Sy \-
 439 The file is neither readable, writable, executable,
 440 nor set-user-ID nor set-group-ID mode, nor sticky.
 441 (See below.)
 442 .El
 443 .Pp
 444 These next two apply only to the third character in the last group
 445 (other permissions).
 446 .Bl -tag -width 4n -offset indent
 447 .It Sy T
 448 The sticky bit is set
 449 (mode
 450 .Li 1000 ) ,
 451 but not execute or search permission.
 452 (See
 453 .Xr chmod 1
 454 or
 455 .Xr sticky 8 . )
 456 .It Sy t
 457 The sticky bit is set (mode
 458 .Li 1000 ) ,
 459 and is searchable or executable.
 460 (See
 461 .Xr chmod 1
 462 or
 463 .Xr sticky 8 . )
 464 .El
 465 .El
 466 .Sh ENVIRONMENT
 467 The following environment variables affect the execution of
 468 .Nm :
 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 .Tn ANSI
 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 is not 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 is not directed to
 508 a terminal.
 509 This can be overridden by setting this variable.
 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
 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 .Tn ANSI
 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 SEE ALSO
 651 .Xr chflags 1 ,
 652 .Xr chmod 1 ,
 653 .Xr sort 1 ,
 654 .Xr xterm 1 Pq Pa x11/xterm ,
 655 .Xr strftime 3 ,
 656 .Xr termcap 5 ,
 657 .Xr symlink 7 ,
 658 .Xr sticky 8
 659 .Sh STANDARDS
 660 With the exception of options
 661 .Fl g ,
 662 .Fl n
 663 and
 664 .Fl o ,
 665 the
 666 .Nm
 667 utility conforms to
 668 .St -p1003.1-2001 .
 669 The options
 670 .Fl B , D , G , I , T , W , b , h , w , y
 671 and
 672 .Fl _
 673 are compatible extensions not defined in
 674 .St -p1003.1-2001 .
 675 .Sh HISTORY
 676 An
 677 .Nm
 678 command appeared in
 679 .At v1 .
 680 .Sh BUGS
 681 To maintain backward compatibility, the relationships between the many
 682 options are quite complex.