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