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