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