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