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 31, 2020 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-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 w 403Force raw printing of non-printable characters. 404This is the default 405when output is not to a terminal. 406This option is not defined in 407.St -p1003.1-2001 . 408.It Fl x 409The same as 410.Fl C , 411except that the multi-column output is produced with entries sorted 412across, rather than down, the columns. 413.It Fl y 414When the 415.Fl t 416option is set, sort the alphabetical output in the same order as the time output. 417This has the same effect as setting 418.Ev LS_SAMESORT . 419See the description of the 420.Fl t 421option for more details. 422This option is not defined in 423.St -p1003.1-2001 . 424.It Fl 1 425(The numeric digit 426.Dq one . ) 427Force output to be 428one entry per line. 429This is the default when 430output is not to a terminal. 431.It Fl , 432(Comma) When the 433.Fl l 434option is set, print file sizes grouped and separated by thousands using the 435non-monetary separator returned by 436.Xr localeconv 3 , 437typically a comma or period. 438If no locale is set, or the locale does not have a non-monetary separator, this 439option has no effect. 440This option is not defined in 441.St -p1003.1-2001 . 442.El 443.Pp 444The 445.Fl 1 , C , x , 446and 447.Fl l 448options all override each other; the last one specified determines 449the format used. 450.Pp 451The 452.Fl c , u , 453and 454.Fl U 455options all override each other; the last one specified determines 456the file time used. 457.Pp 458The 459.Fl S 460and 461.Fl t 462options override each other; the last one specified determines 463the sort order used. 464.Pp 465The 466.Fl B , b , w , 467and 468.Fl q 469options all override each other; the last one specified determines 470the format used for non-printable characters. 471.Pp 472The 473.Fl H , L 474and 475.Fl P 476options all override each other (either partially or fully); they 477are applied in the order specified. 478.Pp 479By default, 480.Nm 481lists one entry per line to standard 482output; the exceptions are to terminals or when the 483.Fl C 484or 485.Fl x 486options are specified. 487.Pp 488File information is displayed with one or more 489.Ao blank Ac Ns s 490separating the information associated with the 491.Fl i , s , 492and 493.Fl l 494options. 495.Ss The Long Format 496If the 497.Fl l 498option is given, the following information 499is displayed for each file: 500file mode, 501number of links, owner name, group name, 502MAC label, 503number of bytes in the file, abbreviated 504month, day-of-month file was last modified, 505hour file last modified, minute file last 506modified, and the pathname. 507.Pp 508If the modification time of the file is more than 6 months 509in the past or future, and the 510.Fl D 511or 512.Fl T 513are not specified, 514then the year of the last modification 515is displayed in place of the hour and minute fields. 516.Pp 517If the owner or group names are not a known user or group name, 518or the 519.Fl n 520option is given, 521the numeric ID's are displayed. 522.Pp 523If the file is a character special or block special file, 524the device number for the file is displayed in the size field. 525If the file is a symbolic link the pathname of the 526linked-to file is preceded by 527.Dq Li -> . 528.Pp 529The listing of a directory's contents is preceded 530by a labeled total number of blocks used in the file system by the files 531which are listed as the directory's contents 532(which may or may not include 533.Pa \&. 534and 535.Pa .. 536and other files which start with a dot, depending on other options). 537.Pp 538The default block size is 512 bytes. 539The block size may be set with option 540.Fl k 541or environment variable 542.Ev BLOCKSIZE . 543Numbers of blocks in the output will have been rounded up so the 544numbers of bytes is at least as many as used by the corresponding 545file system blocks (which might have a different size). 546.Pp 547The file mode printed under the 548.Fl l 549option consists of the 550entry type and the permissions. 551The entry type character describes the type of file, as 552follows: 553.Pp 554.Bl -tag -width 4n -offset indent -compact 555.It Sy \- 556Regular file. 557.It Sy b 558Block special file. 559.It Sy c 560Character special file. 561.It Sy d 562Directory. 563.It Sy l 564Symbolic link. 565.It Sy p 566.Tn FIFO . 567.It Sy s 568Socket. 569.It Sy w 570Whiteout. 571.El 572.Pp 573The next three fields 574are three characters each: 575owner permissions, 576group permissions, and 577other permissions. 578Each field has three character positions: 579.Bl -enum -offset indent 580.It 581If 582.Sy r , 583the file is readable; if 584.Sy \- , 585it is not readable. 586.It 587If 588.Sy w , 589the file is writable; if 590.Sy \- , 591it is not writable. 592.It 593The first of the following that applies: 594.Bl -tag -width 4n -offset indent 595.It Sy S 596If in the owner permissions, the file is not executable and 597set-user-ID mode is set. 598If in the group permissions, the file is not executable 599and set-group-ID mode is set. 600.It Sy s 601If in the owner permissions, the file is executable 602and set-user-ID mode is set. 603If in the group permissions, the file is executable 604and setgroup-ID mode is set. 605.It Sy x 606The file is executable or the directory is 607searchable. 608.It Sy \- 609The file is neither readable, writable, executable, 610nor set-user-ID nor set-group-ID mode, nor sticky. 611(See below.) 612.El 613.Pp 614These next two apply only to the third character in the last group 615(other permissions). 616.Bl -tag -width 4n -offset indent 617.It Sy T 618The sticky bit is set 619(mode 620.Li 1000 ) , 621but not execute or search permission. 622(See 623.Xr chmod 1 624or 625.Xr sticky 7 . ) 626.It Sy t 627The sticky bit is set (mode 628.Li 1000 ) , 629and is searchable or executable. 630(See 631.Xr chmod 1 632or 633.Xr sticky 7 . ) 634.El 635.El 636.Pp 637The next field contains a 638plus 639.Pq Ql + 640character if the file has an ACL, or a 641space 642.Pq Ql " " 643if it does not. 644The 645.Nm 646utility does not show the actual ACL; 647use 648.Xr getfacl 1 649to do this. 650.Sh ENVIRONMENT 651The following environment variables affect the execution of 652.Nm : 653.Bl -tag -width ".Ev CLICOLOR_FORCE" 654.It Ev BLOCKSIZE 655If this is set, its value, rounded up to 512 or down to a 656multiple of 512, will be used as the block size in bytes by the 657.Fl l 658and 659.Fl s 660options. 661See 662.Sx The Long Format 663subsection for more information. 664.It Ev CLICOLOR 665Use 666.Tn ANSI 667color sequences to distinguish file types. 668See 669.Ev LSCOLORS 670below. 671In addition to the file types mentioned in the 672.Fl F 673option some extra attributes (setuid bit set, etc.) are also displayed. 674The colorization is dependent on a terminal type with the proper 675.Xr termcap 5 676capabilities. 677The default 678.Dq Li cons25 679console has the proper capabilities, 680but to display the colors in an 681.Xr xterm 1 , 682for example, 683the 684.Ev TERM 685variable must be set to 686.Dq Li xterm-color . 687Other terminal types may require similar adjustments. 688Colorization 689is silently disabled if the output is not directed to a terminal 690unless the 691.Ev CLICOLOR_FORCE 692variable is defined or 693.Fl -color 694is set to 695.Dq always . 696.It Ev CLICOLOR_FORCE 697Color sequences are normally disabled if the output is not directed to 698a terminal. 699This can be overridden by setting this variable. 700The 701.Ev TERM 702variable still needs to reference a color capable terminal however 703otherwise it is not possible to determine which color sequences to 704use. 705.It Ev COLORTERM 706See description for 707.Ev CLICOLOR 708above. 709.It Ev COLUMNS 710If this variable contains a string representing a 711decimal integer, it is used as the 712column position width for displaying 713multiple-text-column output. 714The 715.Nm 716utility calculates how 717many pathname text columns to display 718based on the width provided. 719(See 720.Fl C 721and 722.Fl x . ) 723.It Ev LANG 724The locale to use when determining the order of day and month in the long 725.Fl l 726format output. 727See 728.Xr environ 7 729for more information. 730.It Ev LSCOLORS 731The value of this variable describes what color to use for which 732attribute when colors are enabled with 733.Ev CLICOLOR 734or 735.Ev COLORTERM . 736This string is a concatenation of pairs of the format 737.Ar f Ns Ar b , 738where 739.Ar f 740is the foreground color and 741.Ar b 742is the background color. 743When the background color is capitalized, the text will underlined. 744.Pp 745The color designators are as follows: 746.Pp 747.Bl -tag -width 4n -offset indent -compact 748.It Sy a 749black 750.It Sy b 751red 752.It Sy c 753green 754.It Sy d 755brown 756.It Sy e 757blue 758.It Sy f 759magenta 760.It Sy g 761cyan 762.It Sy h 763light grey 764.It Sy A 765bold or underlined black, usually shows up as dark grey 766.It Sy B 767bold or underlined red 768.It Sy C 769bold or underlined green 770.It Sy D 771bold or underlined brown, usually shows up as yellow 772.It Sy E 773bold or underlined blue 774.It Sy F 775bold or underlined magenta 776.It Sy G 777bold or underlined cyan 778.It Sy H 779bold or underlined light grey; looks like bright white 780.It Sy x 781default foreground or background 782.It Sy X 783default foreground or background, with an underline or bold 784.El 785.Pp 786Note that the above are standard 787.Tn ANSI 788colors. 789The actual display may differ 790depending on the color capabilities of the terminal in use. 791.Pp 792The order of the attributes are as follows: 793.Pp 794.Bl -enum -offset indent -compact 795.It 796directory 797.It 798symbolic link 799.It 800socket 801.It 802pipe 803.It 804executable 805.It 806block special 807.It 808character special 809.It 810executable with setuid bit set 811.It 812executable with setgid bit set 813.It 814directory writable to others, with sticky bit 815.It 816directory writable to others, without sticky bit 817.El 818.Pp 819The default is 820.Qq "exfxcxdxbxegedabagacad" , 821i.e., blue foreground and 822default background for regular directories, black foreground and red 823background for setuid executables, etc. 824.It Ev LS_COLWIDTHS 825If this variable is set, it is considered to be a 826colon-delimited list of minimum column widths. 827Unreasonable 828and insufficient widths are ignored (thus zero signifies 829a dynamically sized column). 830Not all columns have changeable widths. 831The fields are, 832in order: inode, block count, number of links, user name, 833group name, flags, file size, file name. 834.It Ev LS_SAMESORT 835If this variable is set, the 836.Fl t 837option sorts the names of files with the same modification timestamp in the same 838sense as the time sort. 839See the description of the 840.Fl t 841option for more details. 842.It Ev TERM 843The 844.Ev CLICOLOR 845and 846.Ev COLORTERM 847functionality depends on a terminal type with color capabilities. 848.It Ev TZ 849The timezone to use when displaying dates. 850See 851.Xr environ 7 852for more information. 853.El 854.Sh EXIT STATUS 855.Ex -std 856.Sh EXAMPLES 857List the contents of the current working directory in long format: 858.Pp 859.Dl $ ls -l 860.Pp 861In addition to listing the contents of the current working directory in 862long format, show inode numbers, file flags (see 863.Xr chflags 1 ) , 864and suffix each filename with a symbol representing its file type: 865.Pp 866.Dl $ ls -lioF 867.Pp 868List the files in 869.Pa /var/log , 870sorting the output such that the mostly recently modified entries are 871printed first: 872.Pp 873.Dl $ ls -lt /var/log 874.Sh COMPATIBILITY 875The group field is now automatically included in the long listing for 876files in order to be compatible with the 877.St -p1003.2 878specification. 879.Sh SEE ALSO 880.Xr chflags 1 , 881.Xr chmod 1 , 882.Xr getfacl 1 , 883.Xr sort 1 , 884.Xr xterm 1 , 885.Xr localeconv 3 , 886.Xr strftime 3 , 887.Xr strmode 3 , 888.Xr termcap 5 , 889.Xr maclabel 7 , 890.Xr sticky 7 , 891.Xr symlink 7 , 892.Xr getfmac 8 893.Sh STANDARDS 894With the exception of options 895.Fl g , n 896and 897.Fl o , 898the 899.Nm 900utility conforms to 901.St -p1003.1-2001 902and 903.St -p1003.1-2008 . 904The options 905.Fl B , D , G , I , T , U , W , Z , b , h , w , y 906and 907.Fl , 908are non-standard extensions. 909.Pp 910The ACL support is compatible with 911.Tn IEEE 912Std\~1003.2c 913.Pq Dq Tn POSIX Ns .2c 914Draft\~17 915(withdrawn). 916.Sh HISTORY 917An 918.Nm 919command appeared in 920.At v1 . 921.Sh BUGS 922To maintain backward compatibility, the relationships between the many 923options are quite complex. 924.Pp 925The exception mentioned in the 926.Fl s 927option description might be a feature that was 928based on the fact that single-column output 929usually goes to something other than a terminal. 930It is debatable whether this is a design bug. 931.Pp 932.St -p1003.2 933mandates opposite sort orders for files with the same timestamp when 934sorting with the 935.Fl t 936option. 937