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.\" 4. 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 12, 2006 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 ABCFGHILPRSTUWZabcdfghiklmnopqrstuwx1 44.Op Ar 45.Sh DESCRIPTION 46For each operand that names a 47.Ar file 48of a type other than 49directory, 50.Nm 51displays its name as well as any requested, 52associated information. 53For each operand that names a 54.Ar file 55of type directory, 56.Nm 57displays the names of files contained 58within that directory, as well as any requested, associated 59information. 60.Pp 61If no operands are given, the contents of the current 62directory are displayed. 63If more than one operand is given, 64non-directory operands are displayed first; directory 65and non-directory operands are sorted separately and in 66lexicographical order. 67.Pp 68The following options are available: 69.Bl -tag -width indent 70.It Fl A 71Include directory entries whose names begin with a 72dot 73.Pq Sq Pa \&. 74except for 75.Pa \&. 76and 77.Pa .. . 78Automatically set for the super-user unless 79.Fl I 80is specified. 81.It Fl B 82Force printing of non-printable characters (as defined by 83.Xr ctype 3 84and current locale settings) in file names as 85.Li \e Ns Va xxx , 86where 87.Va xxx 88is the numeric value of the character in octal. 89.It Fl C 90Force multi-column output; this is the default when output is to a terminal. 91.It Fl F 92Display a slash 93.Pq Ql / 94immediately after each pathname that is a directory, 95an asterisk 96.Pq Ql * 97after each that is executable, 98an at sign 99.Pq Ql @ 100after each symbolic link, 101an equals sign 102.Pq Ql = 103after each socket, 104a percent sign 105.Pq Ql % 106after each whiteout, 107and a vertical bar 108.Pq Ql \&| 109after each that is a 110.Tn FIFO . 111.It Fl G 112Enable colorized output. 113This option is equivalent to defining 114.Ev CLICOLOR 115in the environment. 116(See below.) 117.It Fl H 118Symbolic links on the command line are followed. 119This option is assumed if 120none of the 121.Fl F , d , 122or 123.Fl l 124options are specified. 125.It Fl I 126Prevent 127.Fl A 128from being automatically set for the super-user. 129.It Fl L 130If argument is a symbolic link, list the file or directory the link references 131rather than the link itself. 132This option cancels the 133.Fl P 134option. 135.It Fl P 136If argument is a symbolic link, list the link itself rather than the 137object the link references. 138This option cancels the 139.Fl H 140and 141.Fl L 142options. 143.It Fl R 144Recursively list subdirectories encountered. 145.It Fl S 146Sort by size (largest file first) before sorting the operands in 147lexicographical order. 148.It Fl T 149When used with the 150.Fl l 151(lowercase letter 152.Dq ell ) 153option, display complete time information for the file, including 154month, day, hour, minute, second, and year. 155.It Fl U 156Use time when file was created for sorting or printing. 157.It Fl W 158Display whiteouts when scanning directories. 159.It Fl Z 160Display each file's MAC label; see 161.Xr maclabel 7 . 162.It Fl a 163Include directory entries whose names begin with a 164dot 165.Pq Sq Pa \&. . 166.It Fl b 167As 168.Fl B , 169but use 170.Tn C 171escape codes whenever possible. 172.It Fl c 173Use time when file status was last changed for sorting or printing. 174.It Fl d 175Directories are listed as plain files (not searched recursively). 176.It Fl f 177Output is not sorted. 178.It Fl g 179This option is deprecated and is only available for compatibility 180with 181.Bx 4.3 ; 182it was used to display the group name in the long 183.Pq Fl l 184format output. 185.It Fl h 186When used with the 187.Fl l 188option, use unit suffixes: Byte, Kilobyte, Megabyte, Gigabyte, Terabyte 189and Petabyte in order to reduce the number of digits to four or fewer 190using base 2 for sizes. 191.It Fl i 192For each file, print the file's file serial number (inode number). 193.It Fl k 194This has the same effect as setting environment variable 195.Ev BLOCKSIZE 196to 1024, except that it also nullifies any 197.Fl h 198options to its left. 199.It Fl l 200(The lowercase letter 201.Dq ell . ) 202List files in the long format, as described in the 203.Sx The Long Format 204subsection below. 205.It Fl m 206Stream output format; list files across the page, separated by commas. 207.It Fl n 208Display user and group IDs numerically rather than converting to a user 209or group name in a long 210.Pq Fl l 211output. 212.It Fl o 213Include the file flags in a long 214.Pq Fl l 215output. 216.It Fl p 217Write a slash 218.Pq Ql / 219after each filename if that file is a directory. 220.It Fl q 221Force printing of non-graphic characters in file names as 222the character 223.Ql \&? ; 224this is the default when output is to a terminal. 225.It Fl r 226Reverse the order of the sort. 227.It Fl s 228Display the number of blocks used in the file system by each file. 229Block sizes and directory totals are handled as described in 230.Sx The Long Format 231subsection below, except (if the long format is not also requested) 232the directory totals are not output when the output is in a 233single column, even if multi-column output is requested. 234.It Fl t 235Sort by time modified (most recently modified 236first) before sorting the operands in lexicographical 237order. 238.It Fl u 239Use time of last access, 240instead of last modification 241of the file for sorting 242.Pq Fl t 243or printing 244.Pq Fl l . 245.It Fl w 246Force raw printing of non-printable characters. 247This is the default 248when output is not to a terminal. 249.It Fl x 250The same as 251.Fl C , 252except that the multi-column output is produced with entries sorted 253across, rather than down, the columns. 254.It Fl 1 255(The numeric digit 256.Dq one . ) 257Force output to be 258one entry per line. 259This is the default when 260output is not to a terminal. 261.El 262.Pp 263The 264.Fl 1 , C , x , 265and 266.Fl l 267options all override each other; the last one specified determines 268the format used. 269.Pp 270The 271.Fl c , u , 272and 273.Fl U 274options all override each other; the last one specified determines 275the file time used. 276.Pp 277The 278.Fl S 279and 280.Fl t 281options override each other; the last one specified determines 282the sort order used. 283.Pp 284The 285.Fl B , b , w , 286and 287.Fl q 288options all override each other; the last one specified determines 289the format used for non-printable characters. 290.Pp 291The 292.Fl H , L 293and 294.Fl P 295options all override each other (either partially or fully); they 296are applied in the order specified. 297.Pp 298By default, 299.Nm 300lists one entry per line to standard 301output; the exceptions are to terminals or when the 302.Fl C 303or 304.Fl x 305options are specified. 306.Pp 307File information is displayed with one or more 308.Ao blank Ac Ns s 309separating the information associated with the 310.Fl i , s , 311and 312.Fl l 313options. 314.Ss The Long Format 315If the 316.Fl l 317option is given, the following information 318is displayed for each file: 319file mode, 320number of links, owner name, group name, 321MAC label, 322number of bytes in the file, abbreviated 323month, day-of-month file was last modified, 324hour file last modified, minute file last 325modified, and the pathname. 326.Pp 327If the modification time of the file is more than 6 months 328in the past or future, then the year of the last modification 329is displayed in place of the hour and minute fields. 330.Pp 331If the owner or group names are not a known user or group name, 332or the 333.Fl n 334option is given, 335the numeric ID's are displayed. 336.Pp 337If the file is a character special or block special file, 338the major and minor device numbers for the file are displayed 339in the size field. 340If the file is a symbolic link the pathname of the 341linked-to file is preceded by 342.Dq Li -> . 343.Pp 344The listing of a directory's contents is preceded 345by a labeled total number of blocks used in the file system by the files 346which are listed as the directory's contents 347(which may or may not include 348.Pa \&. 349and 350.Pa .. 351and other files which start with a dot, depending on other options). 352.Pp 353The default block size is 512 bytes. 354The block size may be set with option 355.Fl k 356or environment variable 357.Ev BLOCKSIZE . 358Numbers of blocks in the output will have been rounded up so the 359numbers of bytes is at least as many as used by the corresponding 360file system blocks (which might have a different size). 361.Pp 362The file mode printed under the 363.Fl l 364option consists of the 365entry type and the permissions. 366The entry type character describes the type of file, as 367follows: 368.Pp 369.Bl -tag -width 4n -offset indent -compact 370.It Sy \- 371Regular file. 372.It Sy b 373Block special file. 374.It Sy c 375Character special file. 376.It Sy d 377Directory. 378.It Sy l 379Symbolic link. 380.It Sy p 381.Tn FIFO . 382.It Sy s 383Socket. 384.It Sy w 385Whiteout. 386.El 387.Pp 388The next three fields 389are three characters each: 390owner permissions, 391group permissions, and 392other permissions. 393Each field has three character positions: 394.Bl -enum -offset indent 395.It 396If 397.Sy r , 398the file is readable; if 399.Sy \- , 400it is not readable. 401.It 402If 403.Sy w , 404the file is writable; if 405.Sy \- , 406it is not writable. 407.It 408The first of the following that applies: 409.Bl -tag -width 4n -offset indent 410.It Sy S 411If in the owner permissions, the file is not executable and 412set-user-ID mode is set. 413If in the group permissions, the file is not executable 414and set-group-ID mode is set. 415.It Sy s 416If in the owner permissions, the file is executable 417and set-user-ID mode is set. 418If in the group permissions, the file is executable 419and setgroup-ID mode is set. 420.It Sy x 421The file is executable or the directory is 422searchable. 423.It Sy \- 424The file is neither readable, writable, executable, 425nor set-user-ID nor set-group-ID mode, nor sticky. 426(See below.) 427.El 428.Pp 429These next two apply only to the third character in the last group 430(other permissions). 431.Bl -tag -width 4n -offset indent 432.It Sy T 433The sticky bit is set 434(mode 435.Li 1000 ) , 436but not execute or search permission. 437(See 438.Xr chmod 1 439or 440.Xr sticky 8 . ) 441.It Sy t 442The sticky bit is set (mode 443.Li 1000 ) , 444and is searchable or executable. 445(See 446.Xr chmod 1 447or 448.Xr sticky 8 . ) 449.El 450.El 451.Pp 452The next field contains a 453plus 454.Pq Ql + 455character if the file has an ACL, or a 456space 457.Pq Ql " " 458if it does not. 459The 460.Nm 461utility does not show the actual ACL; 462use 463.Xr getfacl 1 464to do this. 465.Sh ENVIRONMENT 466The following environment variables affect the execution of 467.Nm : 468.Bl -tag -width ".Ev CLICOLOR_FORCE" 469.It Ev BLOCKSIZE 470If this is set, its value, rounded up to 512 or down to a 471multiple of 512, will be used as the block size in bytes by the 472.Fl l 473and 474.Fl s 475options. 476See 477.Sx The Long Format 478subsection for more information. 479.It Ev CLICOLOR 480Use 481.Tn ANSI 482color sequences to distinguish file types. 483See 484.Ev LSCOLORS 485below. 486In addition to the file types mentioned in the 487.Fl F 488option some extra attributes (setuid bit set, etc.) are also displayed. 489The colorization is dependent on a terminal type with the proper 490.Xr termcap 5 491capabilities. 492The default 493.Dq Li cons25 494console has the proper capabilities, 495but to display the colors in an 496.Xr xterm 1 , 497for example, 498the 499.Ev TERM 500variable must be set to 501.Dq Li xterm-color . 502Other terminal types may require similar adjustments. 503Colorization 504is silently disabled if the output is not directed to a terminal 505unless the 506.Ev CLICOLOR_FORCE 507variable is defined. 508.It Ev CLICOLOR_FORCE 509Color sequences are normally disabled if the output is not directed to 510a terminal. 511This can be overridden by setting this flag. 512The 513.Ev TERM 514variable still needs to reference a color capable terminal however 515otherwise it is not possible to determine which color sequences to 516use. 517.It Ev COLUMNS 518If this variable contains a string representing a 519decimal integer, it is used as the 520column position width for displaying 521multiple-text-column output. 522The 523.Nm 524utility calculates how 525many pathname text columns to display 526based on the width provided. 527(See 528.Fl C 529and 530.Fl x . ) 531.It Ev LANG 532The locale to use when determining the order of day and month in the long 533.Fl l 534format output. 535See 536.Xr environ 7 537for more information. 538.It Ev LSCOLORS 539The value of this variable describes what color to use for which 540attribute when colors are enabled with 541.Ev CLICOLOR . 542This string is a concatenation of pairs of the format 543.Ar f Ns Ar b , 544where 545.Ar f 546is the foreground color and 547.Ar b 548is the background color. 549.Pp 550The color designators are as follows: 551.Pp 552.Bl -tag -width 4n -offset indent -compact 553.It Sy a 554black 555.It Sy b 556red 557.It Sy c 558green 559.It Sy d 560brown 561.It Sy e 562blue 563.It Sy f 564magenta 565.It Sy g 566cyan 567.It Sy h 568light grey 569.It Sy A 570bold black, usually shows up as dark grey 571.It Sy B 572bold red 573.It Sy C 574bold green 575.It Sy D 576bold brown, usually shows up as yellow 577.It Sy E 578bold blue 579.It Sy F 580bold magenta 581.It Sy G 582bold cyan 583.It Sy H 584bold light grey; looks like bright white 585.It Sy x 586default foreground or background 587.El 588.Pp 589Note that the above are standard 590.Tn ANSI 591colors. 592The actual display may differ 593depending on the color capabilities of the terminal in use. 594.Pp 595The order of the attributes are as follows: 596.Pp 597.Bl -enum -offset indent -compact 598.It 599directory 600.It 601symbolic link 602.It 603socket 604.It 605pipe 606.It 607executable 608.It 609block special 610.It 611character special 612.It 613executable with setuid bit set 614.It 615executable with setgid bit set 616.It 617directory writable to others, with sticky bit 618.It 619directory writable to others, without sticky bit 620.El 621.Pp 622The default is 623.Qq "exfxcxdxbxegedabagacad" , 624i.e., blue foreground and 625default background for regular directories, black foreground and red 626background for setuid executables, etc. 627.It Ev LS_COLWIDTHS 628If this variable is set, it is considered to be a 629colon-delimited list of minimum column widths. 630Unreasonable 631and insufficient widths are ignored (thus zero signifies 632a dynamically sized column). 633Not all columns have changeable widths. 634The fields are, 635in order: inode, block count, number of links, user name, 636group name, flags, file size, file name. 637.It Ev TERM 638The 639.Ev CLICOLOR 640functionality depends on a terminal type with color capabilities. 641.It Ev TZ 642The timezone to use when displaying dates. 643See 644.Xr environ 7 645for more information. 646.El 647.Sh EXIT STATUS 648.Ex -std 649.Sh COMPATIBILITY 650The group field is now automatically included in the long listing for 651files in order to be compatible with the 652.St -p1003.2 653specification. 654.Sh SEE ALSO 655.Xr chflags 1 , 656.Xr chmod 1 , 657.Xr getfacl 1 , 658.Xr sort 1 , 659.Xr xterm 1 , 660.Xr termcap 5 , 661.Xr maclabel 7 , 662.Xr symlink 7 , 663.Xr getfmac 8 , 664.Xr sticky 8 665.Sh STANDARDS 666With the exception of options 667.Fl I , g , n 668and 669.Fl o , 670the 671.Nm 672utility conforms to 673.St -p1003.1-2001 . 674.Pp 675The ACL support is compatible with 676.Tn IEEE 677Std\~1003.2c 678.Pq Dq Tn POSIX Ns .2c 679Draft\~17 680(withdrawn). 681.Sh HISTORY 682An 683.Nm 684command appeared in 685.At v1 . 686.Sh BUGS 687To maintain backward compatibility, the relationships between the many 688options are quite complex. 689.Pp 690The exception mentioned in the 691.Fl s 692option description might be a feature that was 693based on the fact that single-column output 694usually goes to something other than a terminal. 695It is debatable whether this is a design bug. 696