1.\"- 2.\" Copyright (c) 1980, 1990, 1991, 1993, 1994 3.\" The Regents of the University of California. All rights reserved. 4.\" 5.\" This code is derived from software contributed to Berkeley by 6.\" the Institute of Electrical and Electronics Engineers, Inc. 7.\" 8.\" Redistribution and use in source and binary forms, with or without 9.\" modification, are permitted provided that the following conditions 10.\" are met: 11.\" 1. Redistributions of source code must retain the above copyright 12.\" notice, this list of conditions and the following disclaimer. 13.\" 2. Redistributions in binary form must reproduce the above copyright 14.\" notice, this list of conditions and the following disclaimer in the 15.\" documentation and/or other materials provided with the distribution. 16.\" 3. Neither the name of the University nor the names of its contributors 17.\" may be used to endorse or promote products derived from this software 18.\" without specific prior written permission. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 30.\" SUCH DAMAGE. 31.\" 32.\" @(#)ls.1 8.7 (Berkeley) 7/29/94 33.\" $FreeBSD$ 34.\" 35.Dd August 16, 2018 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 ABCFGHILPRSTUWZabcdfghiklmnopqrstuwxy1, 44.Op Fl -color Ns = Ns Ar when 45.Op Fl D Ar format 46.Op Ar 47.Sh DESCRIPTION 48For each operand that names a 49.Ar file 50of a type other than 51directory, 52.Nm 53displays its name as well as any requested, 54associated information. 55For each operand that names a 56.Ar file 57of type directory, 58.Nm 59displays the names of files contained 60within that directory, as well as any requested, associated 61information. 62.Pp 63If no operands are given, the contents of the current 64directory are displayed. 65If more than one operand is given, 66non-directory operands are displayed first; directory 67and non-directory operands are sorted separately and in 68lexicographical order. 69.Pp 70The following options are available: 71.Bl -tag -width indent 72.It Fl A 73Include directory entries whose names begin with a 74dot 75.Pq Sq Pa \&. 76except for 77.Pa \&. 78and 79.Pa .. . 80Automatically set for the super-user unless 81.Fl I 82is specified. 83.It Fl B 84Force printing of non-printable characters (as defined by 85.Xr ctype 3 86and current locale settings) in file names as 87.Li \e Ns Va xxx , 88where 89.Va xxx 90is the numeric value of the character in octal. 91This option is not defined in 92.St -p1003.1-2001 . 93.It Fl C 94Force multi-column output; this is the default when output is to a terminal. 95.It Fl D Ar format 96When printing in the long 97.Pq Fl l 98format, use 99.Ar format 100to format the date and time output. 101The argument 102.Ar format 103is a string used by 104.Xr strftime 3 . 105Depending on the choice of format string, this may result in a 106different number of columns in the output. 107This option overrides the 108.Fl T 109option. 110This option is not defined in 111.St -p1003.1-2001 . 112.It Fl F 113Display a slash 114.Pq Ql / 115immediately after each pathname that is a directory, 116an asterisk 117.Pq Ql * 118after each that is executable, 119an at sign 120.Pq Ql @ 121after each symbolic link, 122an equals sign 123.Pq Ql = 124after each socket, 125a percent sign 126.Pq Ql % 127after each whiteout, 128and a vertical bar 129.Pq Ql \&| 130after each that is a 131.Tn FIFO . 132.It Fl G 133Enable colorized output. 134This option is equivalent to defining 135.Ev CLICOLOR 136or 137.Ev COLORTERM 138in the environment. 139(See below.) 140This functionality can be compiled out by removing the definition of 141.Ev COLORLS . 142This option is not defined in 143.St -p1003.1-2001 . 144.It Fl H 145Symbolic links on the command line are followed. 146This option is assumed if 147none of the 148.Fl F , d , 149or 150.Fl l 151options are specified. 152.It Fl I 153Prevent 154.Fl A 155from being automatically set for the super-user. 156This option is not defined in 157.St -p1003.1-2001 . 158.It Fl L 159If argument is a symbolic link, list the file or directory the link references 160rather than the link itself. 161This option cancels the 162.Fl P 163option. 164.It Fl P 165If argument is a symbolic link, list the link itself rather than the 166object the link references. 167This option cancels the 168.Fl H 169and 170.Fl L 171options. 172.It Fl R 173Recursively list subdirectories encountered. 174.It Fl S 175Sort by size (largest file first) before sorting the operands in 176lexicographical order. 177.It Fl T 178When printing in the long 179.Pq Fl l 180format, display complete time information for the file, including 181month, day, hour, minute, second, and year. 182The 183.Fl D 184option gives even more control over the output format. 185This option is not defined in 186.St -p1003.1-2001 . 187.It Fl U 188Use time when file was created for sorting or printing. 189This option is not defined in 190.St -p1003.1-2001 . 191.It Fl W 192Display whiteouts when scanning directories. 193This option is not defined in 194.St -p1003.1-2001 . 195.It Fl Z 196Display each file's MAC label; see 197.Xr maclabel 7 . 198This option is not defined in 199.St -p1003.1-2001 . 200.It Fl a 201Include directory entries whose names begin with a 202dot 203.Pq Sq Pa \&. . 204.It Fl b 205As 206.Fl B , 207but use 208.Tn C 209escape codes whenever possible. 210This option is not defined in 211.St -p1003.1-2001 . 212.It Fl c 213Use time when file status was last changed for sorting or printing. 214.It Fl -color Ns = Ns Ar when 215Output colored escape sequences based on 216.Ar when , 217which may be set to either 218.Cm always , 219.Cm auto 220(default), or 221.Cm never . 222.Pp 223.Cm always 224will make 225.Nm 226always output color. 227If 228.Ev TERM 229is unset or set to an invalid terminal, then 230.Nm 231will fall back to explicit 232.Tn ANSI 233escape sequences without the help of 234.Xr termcap 5 . 235.Cm always 236is the default if 237.Fl -color 238is specified without an argument. 239.Pp 240.Cm auto 241will make 242.Nm 243output escape sequences based on 244.Xr termcap 5 , 245but only if 246.Dv stdout 247is a tty and either the 248.Fl G 249flag is specified or the 250.Ev COLORTERM 251environment variable is set and not empty. 252.Pp 253.Cm never 254will disable color regardless of environment variables. 255.It Fl d 256Directories are listed as plain files (not searched recursively). 257.It Fl f 258Output is not sorted. 259This option turns on 260.Fl a . 261It also negates the effect of the 262.Fl r , 263.Fl S 264and 265.Fl t 266options. 267As allowed by 268.St -p1003.1-2001 , 269this option has no effect on the 270.Fl d , 271.Fl l , 272.Fl R 273and 274.Fl s 275options. 276.It Fl g 277This option has no effect. 278It is only available for compatibility with 279.Bx 4.3 , 280where it was used to display the group name in the long 281.Pq Fl l 282format output. 283This option is incompatible with 284.St -p1003.1-2001 . 285.It Fl h 286When used with the 287.Fl l 288option, use unit suffixes: Byte, Kilobyte, Megabyte, Gigabyte, Terabyte 289and Petabyte in order to reduce the number of digits to four or fewer 290using base 2 for sizes. 291This option is not defined in 292.St -p1003.1-2001 . 293.It Fl i 294For each file, print the file's file serial number (inode number). 295.It Fl k 296This has the same effect as setting environment variable 297.Ev BLOCKSIZE 298to 1024, except that it also nullifies any 299.Fl h 300options to its left. 301.It Fl l 302(The lowercase letter 303.Dq ell . ) 304List files in the long format, as described in the 305.Sx The Long Format 306subsection below. 307.It Fl m 308Stream output format; list files across the page, separated by commas. 309.It Fl n 310Display user and group IDs numerically rather than converting to a user 311or group name in a long 312.Pq Fl l 313output. 314.It Fl o 315Include the file flags in a long 316.Pq Fl l 317output. 318This option is incompatible with 319.St -p1003.1-2001 . 320See 321.Xr chflags 1 322for a list of file flags and their meanings. 323.It Fl p 324Write a slash 325.Pq Ql / 326after each filename if that file is a directory. 327.It Fl q 328Force printing of non-graphic characters in file names as 329the character 330.Ql \&? ; 331this is the default when output is to a terminal. 332.It Fl r 333Reverse the order of the sort. 334.It Fl s 335Display the number of blocks used in the file system by each file. 336Block sizes and directory totals are handled as described in 337.Sx The Long Format 338subsection below, except (if the long format is not also requested) 339the directory totals are not output when the output is in a 340single column, even if multi-column output is requested. 341.It Fl t 342Sort by descending time modified (most recently modified first). 343If two files have the same modification timestamp, sort their names 344in ascending lexicographical order. 345The 346.Fl r 347option reverses both of these sort orders. 348.Pp 349Note that these sort orders are contradictory: the time sequence is in 350descending order, the lexicographical sort is in ascending order. 351This behavior is mandated by 352.St -p1003.2 . 353This feature can cause problems listing files stored with sequential names on 354FAT file systems, such as from digital cameras, where it is possible to have 355more than one image with the same timestamp. 356In such a case, the photos cannot be listed in the sequence in which 357they were taken. 358To ensure the same sort order for time and for lexicographical sorting, set the 359environment variable 360.Ev LS_SAMESORT 361or use the 362.Fl y 363option. 364This causes 365.Nm 366to reverse the lexicographical sort order when sorting files with the 367same modification timestamp. 368.It Fl u 369Use time of last access, 370instead of time of last modification 371of the file for sorting 372.Pq Fl t 373or printing 374.Pq Fl l . 375.It Fl w 376Force raw printing of non-printable characters. 377This is the default 378when output is not to a terminal. 379This option is not defined in 380.St -p1003.1-2001 . 381.It Fl x 382The same as 383.Fl C , 384except that the multi-column output is produced with entries sorted 385across, rather than down, the columns. 386.It Fl y 387When the 388.Fl t 389option is set, sort the alphabetical output in the same order as the time output. 390This has the same effect as setting 391.Ev LS_SAMESORT . 392See the description of the 393.Fl t 394option for more details. 395This option is not defined in 396.St -p1003.1-2001 . 397.It Fl 1 398(The numeric digit 399.Dq one . ) 400Force output to be 401one entry per line. 402This is the default when 403output is not to a terminal. 404.It Fl , 405(Comma) When the 406.Fl l 407option is set, print file sizes grouped and separated by thousands using the 408non-monetary separator returned by 409.Xr localeconv 3 , 410typically a comma or period. 411If no locale is set, or the locale does not have a non-monetary separator, this 412option has no effect. 413This option is not defined in 414.St -p1003.1-2001 . 415.El 416.Pp 417The 418.Fl 1 , C , x , 419and 420.Fl l 421options all override each other; the last one specified determines 422the format used. 423.Pp 424The 425.Fl c , u , 426and 427.Fl U 428options all override each other; the last one specified determines 429the file time used. 430.Pp 431The 432.Fl S 433and 434.Fl t 435options override each other; the last one specified determines 436the sort order used. 437.Pp 438The 439.Fl B , b , w , 440and 441.Fl q 442options all override each other; the last one specified determines 443the format used for non-printable characters. 444.Pp 445The 446.Fl H , L 447and 448.Fl P 449options all override each other (either partially or fully); they 450are applied in the order specified. 451.Pp 452By default, 453.Nm 454lists one entry per line to standard 455output; the exceptions are to terminals or when the 456.Fl C 457or 458.Fl x 459options are specified. 460.Pp 461File information is displayed with one or more 462.Ao blank Ac Ns s 463separating the information associated with the 464.Fl i , s , 465and 466.Fl l 467options. 468.Ss The Long Format 469If the 470.Fl l 471option is given, the following information 472is displayed for each file: 473file mode, 474number of links, owner name, group name, 475MAC label, 476number of bytes in the file, abbreviated 477month, day-of-month file was last modified, 478hour file last modified, minute file last 479modified, and the pathname. 480.Pp 481If the modification time of the file is more than 6 months 482in the past or future, and the 483.Fl D 484or 485.Fl T 486are not specified, 487then the year of the last modification 488is displayed in place of the hour and minute fields. 489.Pp 490If the owner or group names are not a known user or group name, 491or the 492.Fl n 493option is given, 494the numeric ID's are displayed. 495.Pp 496If the file is a character special or block special file, 497the device number for the file is displayed in the size field. 498If the file is a symbolic link the pathname of the 499linked-to file is preceded by 500.Dq Li -> . 501.Pp 502The listing of a directory's contents is preceded 503by a labeled total number of blocks used in the file system by the files 504which are listed as the directory's contents 505(which may or may not include 506.Pa \&. 507and 508.Pa .. 509and other files which start with a dot, depending on other options). 510.Pp 511The default block size is 512 bytes. 512The block size may be set with option 513.Fl k 514or environment variable 515.Ev BLOCKSIZE . 516Numbers of blocks in the output will have been rounded up so the 517numbers of bytes is at least as many as used by the corresponding 518file system blocks (which might have a different size). 519.Pp 520The file mode printed under the 521.Fl l 522option consists of the 523entry type and the permissions. 524The entry type character describes the type of file, as 525follows: 526.Pp 527.Bl -tag -width 4n -offset indent -compact 528.It Sy \- 529Regular file. 530.It Sy b 531Block special file. 532.It Sy c 533Character special file. 534.It Sy d 535Directory. 536.It Sy l 537Symbolic link. 538.It Sy p 539.Tn FIFO . 540.It Sy s 541Socket. 542.It Sy w 543Whiteout. 544.El 545.Pp 546The next three fields 547are three characters each: 548owner permissions, 549group permissions, and 550other permissions. 551Each field has three character positions: 552.Bl -enum -offset indent 553.It 554If 555.Sy r , 556the file is readable; if 557.Sy \- , 558it is not readable. 559.It 560If 561.Sy w , 562the file is writable; if 563.Sy \- , 564it is not writable. 565.It 566The first of the following that applies: 567.Bl -tag -width 4n -offset indent 568.It Sy S 569If in the owner permissions, the file is not executable and 570set-user-ID mode is set. 571If in the group permissions, the file is not executable 572and set-group-ID mode is set. 573.It Sy s 574If in the owner permissions, the file is executable 575and set-user-ID mode is set. 576If in the group permissions, the file is executable 577and setgroup-ID mode is set. 578.It Sy x 579The file is executable or the directory is 580searchable. 581.It Sy \- 582The file is neither readable, writable, executable, 583nor set-user-ID nor set-group-ID mode, nor sticky. 584(See below.) 585.El 586.Pp 587These next two apply only to the third character in the last group 588(other permissions). 589.Bl -tag -width 4n -offset indent 590.It Sy T 591The sticky bit is set 592(mode 593.Li 1000 ) , 594but not execute or search permission. 595(See 596.Xr chmod 1 597or 598.Xr sticky 7 . ) 599.It Sy t 600The sticky bit is set (mode 601.Li 1000 ) , 602and is searchable or executable. 603(See 604.Xr chmod 1 605or 606.Xr sticky 7 . ) 607.El 608.El 609.Pp 610The next field contains a 611plus 612.Pq Ql + 613character if the file has an ACL, or a 614space 615.Pq Ql " " 616if it does not. 617The 618.Nm 619utility does not show the actual ACL; 620use 621.Xr getfacl 1 622to do this. 623.Sh ENVIRONMENT 624The following environment variables affect the execution of 625.Nm : 626.Bl -tag -width ".Ev CLICOLOR_FORCE" 627.It Ev BLOCKSIZE 628If this is set, its value, rounded up to 512 or down to a 629multiple of 512, will be used as the block size in bytes by the 630.Fl l 631and 632.Fl s 633options. 634See 635.Sx The Long Format 636subsection for more information. 637.It Ev CLICOLOR 638Use 639.Tn ANSI 640color sequences to distinguish file types. 641See 642.Ev LSCOLORS 643below. 644In addition to the file types mentioned in the 645.Fl F 646option some extra attributes (setuid bit set, etc.) are also displayed. 647The colorization is dependent on a terminal type with the proper 648.Xr termcap 5 649capabilities. 650The default 651.Dq Li cons25 652console has the proper capabilities, 653but to display the colors in an 654.Xr xterm 1 , 655for example, 656the 657.Ev TERM 658variable must be set to 659.Dq Li xterm-color . 660Other terminal types may require similar adjustments. 661Colorization 662is silently disabled if the output is not directed to a terminal 663unless the 664.Ev CLICOLOR_FORCE 665variable is defined or 666.Fl -color 667is set to 668.Dq always . 669.It Ev CLICOLOR_FORCE 670Color sequences are normally disabled if the output is not directed to 671a terminal. 672This can be overridden by setting this variable. 673The 674.Ev TERM 675variable still needs to reference a color capable terminal however 676otherwise it is not possible to determine which color sequences to 677use. 678.It Ev COLORTERM 679See description for 680.Ev CLICOLOR 681above. 682.It Ev COLUMNS 683If this variable contains a string representing a 684decimal integer, it is used as the 685column position width for displaying 686multiple-text-column output. 687The 688.Nm 689utility calculates how 690many pathname text columns to display 691based on the width provided. 692(See 693.Fl C 694and 695.Fl x . ) 696.It Ev LANG 697The locale to use when determining the order of day and month in the long 698.Fl l 699format output. 700See 701.Xr environ 7 702for more information. 703.It Ev LSCOLORS 704The value of this variable describes what color to use for which 705attribute when colors are enabled with 706.Ev CLICOLOR 707or 708.Ev COLORTERM . 709This string is a concatenation of pairs of the format 710.Ar f Ns Ar b , 711where 712.Ar f 713is the foreground color and 714.Ar b 715is the background color. 716.Pp 717The color designators are as follows: 718.Pp 719.Bl -tag -width 4n -offset indent -compact 720.It Sy a 721black 722.It Sy b 723red 724.It Sy c 725green 726.It Sy d 727brown 728.It Sy e 729blue 730.It Sy f 731magenta 732.It Sy g 733cyan 734.It Sy h 735light grey 736.It Sy A 737bold black, usually shows up as dark grey 738.It Sy B 739bold red 740.It Sy C 741bold green 742.It Sy D 743bold brown, usually shows up as yellow 744.It Sy E 745bold blue 746.It Sy F 747bold magenta 748.It Sy G 749bold cyan 750.It Sy H 751bold light grey; looks like bright white 752.It Sy x 753default foreground or background 754.El 755.Pp 756Note that the above are standard 757.Tn ANSI 758colors. 759The actual display may differ 760depending on the color capabilities of the terminal in use. 761.Pp 762The order of the attributes are as follows: 763.Pp 764.Bl -enum -offset indent -compact 765.It 766directory 767.It 768symbolic link 769.It 770socket 771.It 772pipe 773.It 774executable 775.It 776block special 777.It 778character special 779.It 780executable with setuid bit set 781.It 782executable with setgid bit set 783.It 784directory writable to others, with sticky bit 785.It 786directory writable to others, without sticky bit 787.El 788.Pp 789The default is 790.Qq "exfxcxdxbxegedabagacad" , 791i.e., blue foreground and 792default background for regular directories, black foreground and red 793background for setuid executables, etc. 794.It Ev LS_COLWIDTHS 795If this variable is set, it is considered to be a 796colon-delimited list of minimum column widths. 797Unreasonable 798and insufficient widths are ignored (thus zero signifies 799a dynamically sized column). 800Not all columns have changeable widths. 801The fields are, 802in order: inode, block count, number of links, user name, 803group name, flags, file size, file name. 804.It Ev LS_SAMESORT 805If this variable is set, the 806.Fl t 807option sorts the names of files with the same modification timestamp in the same 808sense as the time sort. 809See the description of the 810.Fl t 811option for more details. 812.It Ev TERM 813The 814.Ev CLICOLOR 815and 816.Ev COLORTERM 817functionality depends on a terminal type with color capabilities. 818.It Ev TZ 819The timezone to use when displaying dates. 820See 821.Xr environ 7 822for more information. 823.El 824.Sh EXIT STATUS 825.Ex -std 826.Sh EXAMPLES 827List the contents of the current working directory in long format: 828.Pp 829.Dl $ ls -l 830.Pp 831In addition to listing the contents of the current working directory in 832long format, show inode numbers, file flags (see 833.Xr chflags 1 ) , 834and suffix each filename with a symbol representing its file type: 835.Pp 836.Dl $ ls -lioF 837.Pp 838List the files in 839.Pa /var/log , 840sorting the output such that the mostly recently modified entries are 841printed first: 842.Pp 843.Dl $ ls -lt /var/log 844.Sh COMPATIBILITY 845The group field is now automatically included in the long listing for 846files in order to be compatible with the 847.St -p1003.2 848specification. 849.Sh SEE ALSO 850.Xr chflags 1 , 851.Xr chmod 1 , 852.Xr getfacl 1 , 853.Xr sort 1 , 854.Xr xterm 1 , 855.Xr localeconv 3 , 856.Xr strftime 3 , 857.Xr strmode 3 , 858.Xr termcap 5 , 859.Xr maclabel 7 , 860.Xr sticky 7 , 861.Xr symlink 7 , 862.Xr getfmac 8 863.Sh STANDARDS 864With the exception of options 865.Fl g , n 866and 867.Fl o , 868the 869.Nm 870utility conforms to 871.St -p1003.1-2001 . 872The options 873.Fl B , D , G , I , T , U , W , Z , b , h , w , y 874and 875.Fl , 876are compatible extensions not defined in 877.St -p1003.1-2001 . 878.Pp 879The ACL support is compatible with 880.Tn IEEE 881Std\~1003.2c 882.Pq Dq Tn POSIX Ns .2c 883Draft\~17 884(withdrawn). 885.Sh HISTORY 886An 887.Nm 888command appeared in 889.At v1 . 890.Sh BUGS 891To maintain backward compatibility, the relationships between the many 892options are quite complex. 893.Pp 894The exception mentioned in the 895.Fl s 896option description might be a feature that was 897based on the fact that single-column output 898usually goes to something other than a terminal. 899It is debatable whether this is a design bug. 900.Pp 901.St -p1003.2 902mandates opposite sort orders for files with the same timestamp when 903sorting with the 904.Fl t 905option. 906