1.\" Copyright (c) 1980, 1990, 1991, 1993, 1994 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" This code is derived from software contributed to Berkeley by 5.\" the Institute of Electrical and Electronics Engineers, Inc. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 3. All advertising materials mentioning features or use of this software 16.\" must display the following acknowledgment: 17.\" This product includes software developed by the University of 18.\" California, Berkeley and its contributors. 19.\" 4. Neither the name of the University nor the names of its contributors 20.\" may be used to endorse or promote products derived from this software 21.\" without specific prior written permission. 22.\" 23.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 24.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 25.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 26.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 27.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 28.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 29.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 30.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 31.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 32.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 33.\" SUCH DAMAGE. 34.\" 35.\" @(#)ls.1 8.7 (Berkeley) 7/29/94 36.\" $FreeBSD$ 37.\" 38.Dd May 19, 2002 39.Dt LS 1 40.Os 41.Sh NAME 42.Nm ls 43.Nd list directory contents 44.Sh SYNOPSIS 45.Nm 46.Op Fl ABCFGHLPRTWZabcdfghiklmnopqrstuwx1 47.Op Ar 48.Sh DESCRIPTION 49For each operand that names a 50.Ar file 51of a type other than 52directory, 53.Nm 54displays its name as well as any requested, 55associated information. 56For each operand that names a 57.Ar file 58of type directory, 59.Nm 60displays the names of files contained 61within that directory, as well as any requested, associated 62information. 63.Pp 64If no operands are given, the contents of the current 65directory are displayed. 66If more than one operand is given, 67non-directory operands are displayed first; directory 68and non-directory operands are sorted separately and in 69lexicographical order. 70.Pp 71The following options are available: 72.Bl -tag -width indent 73.It Fl A 74List all entries except for 75.Pa \&. 76and 77.Pa .. . 78Always set for the super-user. 79.It Fl B 80Force printing of non-printable characters (as defined by 81.Xr ctype 3 82and current locale settings) in file names as 83.Li \e Ns Va xxx , 84where 85.Va xxx 86is the numeric value of the character in octal. 87.It Fl C 88Force multi-column output; this is the default when output is to a terminal. 89.It Fl F 90Display a slash 91.Pq Ql / 92immediately after each pathname that is a directory, 93an asterisk 94.Pq Ql * 95after each that is executable, 96an at sign 97.Pq Ql @ 98after each symbolic link, 99an equals sign 100.Pq Ql = 101after each socket, 102a percent sign 103.Pq Ql % 104after each whiteout, 105and a vertical bar 106.Pq Ql \&| 107after each that is a 108.Tn FIFO . 109.It Fl G 110Enable colorized output. 111This option is equivalent to defining 112.Ev CLICOLOR 113in the environment. 114(See below.) 115.It Fl H 116Symbolic links on the command line are followed. 117This option is assumed if 118none of the 119.Fl F , d , 120or 121.Fl l 122options are specified. 123.It Fl L 124If argument is a symbolic link, list the file or directory the link references 125rather than the link itself. 126This option cancels the 127.Fl P 128option. 129.It Fl P 130If argument is a symbolic link, list the link itself rather than the 131object the link references. 132This option cancels the 133.Fl H 134and 135.Fl L 136options. 137.It Fl R 138Recursively list subdirectories encountered. 139.It Fl T 140When used with the 141.Fl l 142(lowercase letter 143.Dq ell ) 144option, display complete time information for the file, including 145month, day, hour, minute, second, and year. 146.It Fl W 147Display whiteouts when scanning directories. 148.It Fl Z 149Display each file's MAC label. 150.It Fl a 151Include directory entries whose names begin with a 152dot 153.Pq Pa \&. . 154.It Fl b 155As 156.Fl B , 157but use 158.Tn C 159escape codes whenever possible. 160.It Fl c 161Use time when file status was last changed for sorting or printing. 162.It Fl d 163Directories are listed as plain files (not searched recursively). 164.It Fl f 165Output is not sorted. 166.It Fl g 167This option is deprecated and is only available for compatibility 168with 169.Bx 4.3 ; 170it was used to display the group name in the long 171.Pq Fl l 172format output. 173.It Fl h 174When used with the 175.Fl l 176option, use unit suffixes: Byte, Kilobyte, Megabyte, Gigabyte, Terabyte 177and Petabyte in order to reduce the number of digits to three or less 178using base 2 for sizes. 179.It Fl i 180For each file, print the file's file serial number (inode number). 181.It Fl k 182If the 183.Fl s 184option is specified, print the file size allocation in kilobytes, 185not blocks. 186This option overrides the environment variable 187.Ev BLOCKSIZE . 188.It Fl l 189(The lowercase letter 190.Dq ell . ) 191List in long format. 192(See below.) 193If the output is to a terminal, a total sum for all the file 194sizes is output on a line before the long listing. 195.It Fl m 196Stream output format; list files across the page, separated by commas. 197.It Fl n 198Display user and group IDs numerically rather than converting to a user 199or group name in a long 200.Pq Fl l 201output. 202.It Fl o 203Include the file flags in a long 204.Pq Fl l 205output. 206.It Fl p 207Write a slash 208.Pq Ql / 209after each filename if that file is a directory. 210.It Fl q 211Force printing of non-graphic characters in file names as 212the character 213.Ql \&? ; 214this is the default when output is to a terminal. 215.It Fl r 216Reverse the order of the sort to get reverse 217lexicographical order or the oldest entries first. 218.It Fl s 219Display the number of file system blocks actually used by each file, in units 220of 512 bytes, where partial units are rounded up to the next integer value. 221If the output is to a terminal, a total sum for all the file 222sizes is output on a line before the listing. 223The environment variable 224.Ev BLOCKSIZE 225overrides the unit size of 512 bytes. 226.It Fl t 227Sort by time modified (most recently modified 228first) before sorting the operands by lexicographical 229order. 230.It Fl u 231Use time of last access, 232instead of last modification 233of the file for sorting 234.Pq Fl t 235or printing 236.Pq Fl l . 237.It Fl w 238Force raw printing of non-printable characters. 239This is the default 240when output is not to a terminal. 241.It Fl x 242The same as 243.Fl C , 244except that the multi-column output is produced with entries sorted 245across, rather than down, the columns. 246.It Fl 1 247(The numeric digit 248.Dq one . ) 249Force output to be 250one entry per line. 251This is the default when 252output is not to a terminal. 253.El 254.Pp 255The 256.Fl 1 , C , x , 257and 258.Fl l 259options all override each other; the last one specified determines 260the format used. 261.Pp 262The 263.Fl c 264and 265.Fl u 266options override each other; the last one specified determines 267the file time used. 268.Pp 269The 270.Fl B , b , w , 271and 272.Fl q 273options all override each other; the last one specified determines 274the format used for non-printable characters. 275.Pp 276The 277.Fl H , L 278and 279.Fl P 280options all override each other (either partially or fully); they 281are applied in the order specified. 282.Pp 283By default, 284.Nm 285lists one entry per line to standard 286output; the exceptions are to terminals or when the 287.Fl C 288or 289.Fl x 290options are specified. 291.Pp 292File information is displayed with one or more 293.Ao blank Ac Ns s 294separating the information associated with the 295.Fl i , s , 296and 297.Fl l 298options. 299.Ss The Long Format 300If the 301.Fl l 302option is given, the following information 303is displayed for each file: 304file mode, 305number of links, owner name, group name, 306MAC label, 307number of bytes in the file, abbreviated 308month, day-of-month file was last modified, 309hour file last modified, minute file last 310modified, and the pathname. 311In addition, for each directory whose contents are displayed, the total 312number of 512-byte blocks used by the files in the directory is displayed 313on a line by itself immediately before the information for the files in the 314directory. 315.Pp 316If the modification time of the file is more than 6 months 317in the past or future, then the year of the last modification 318is displayed in place of the hour and minute fields. 319.Pp 320If the owner or group names are not a known user or group name, 321or the 322.Fl n 323option is given, 324the numeric ID's are displayed. 325.Pp 326If the file is a character special or block special file, 327the major and minor device numbers for the file are displayed 328in the size field. 329If the file is a symbolic link the pathname of the 330linked-to file is preceded by 331.Dq Li -> . 332.Pp 333The file mode printed under the 334.Fl l 335option consists of the 336entry type, owner permissions, and group permissions. 337The entry type character describes the type of file, as 338follows: 339.Pp 340.Bl -tag -width 4n -offset indent -compact 341.It Sy b 342Block special file. 343.It Sy c 344Character special file. 345.It Sy d 346Directory. 347.It Sy l 348Symbolic link. 349.It Sy s 350Socket link. 351.It Sy p 352.Tn FIFO . 353.It Sy \- 354Regular file. 355.El 356.Pp 357The next three fields 358are three characters each: 359owner permissions, 360group permissions, and 361other permissions. 362Each field has three character positions: 363.Bl -enum -offset indent 364.It 365If 366.Sy r , 367the file is readable; if 368.Sy \- , 369it is not readable. 370.It 371If 372.Sy w , 373the file is writable; if 374.Sy \- , 375it is not writable. 376.It 377The first of the following that applies: 378.Bl -tag -width 4n -offset indent 379.It Sy S 380If in the owner permissions, the file is not executable and 381set-user-ID mode is set. 382If in the group permissions, the file is not executable 383and set-group-ID mode is set. 384.It Sy s 385If in the owner permissions, the file is executable 386and set-user-ID mode is set. 387If in the group permissions, the file is executable 388and setgroup-ID mode is set. 389.It Sy x 390The file is executable or the directory is 391searchable. 392.It Sy \- 393The file is neither readable, writable, executable, 394nor set-user-ID nor set-group-ID mode, nor sticky. 395(See below.) 396.El 397.Pp 398These next two apply only to the third character in the last group 399(other permissions). 400.Bl -tag -width 4n -offset indent 401.It Sy T 402The sticky bit is set 403(mode 404.Li 1000 ) , 405but not execute or search permission. 406(See 407.Xr chmod 1 408or 409.Xr sticky 8 . ) 410.It Sy t 411The sticky bit is set (mode 412.Li 1000 ) , 413and is searchable or executable. 414(See 415.Xr chmod 1 416or 417.Xr sticky 8 . ) 418.El 419.El 420.Sh EXAMPLES 421The following is how to do an 422.Nm 423listing sorted by size (and shows why 424.Nm 425does not need a separate option for this): 426.Pp 427.Dl "ls -l | sort -n +4" 428.Pp 429Additionally, the 430.Fl r 431flag to 432.Xr sort 1 433may be used 434to get the results sorted from largest to smallest (a reverse sort). 435.Sh DIAGNOSTICS 436.Ex -std 437.Sh ENVIRONMENT 438The following environment variables affect the execution of 439.Nm : 440.Bl -tag -width ".Ev CLICOLOR_FORCE" 441.It Ev BLOCKSIZE 442If the environment variable 443.Ev BLOCKSIZE 444is set, the block counts 445(see 446.Fl s ) 447will be displayed in units of that size block. 448.It Ev CLICOLOR 449Use 450\*[Ai] 451color sequences to distinguish file types. 452See 453.Ev LSCOLORS 454below. 455In addition to the file types mentioned in the 456.Fl F 457option some extra attributes (setuid bit set, etc.) are also displayed. 458The colorization is dependent on a terminal type with the proper 459.Xr termcap 5 460capabilities. 461The default 462.Dq Li cons25 463console has the proper capabilities, 464but to display the colors in an 465.Xr xterm 1 , 466for example, 467the 468.Ev TERM 469variable must be set to 470.Dq Li xterm-color . 471Other terminal types may require similar adjustments. 472Colorization 473is silently disabled if the output isn't directed to a terminal 474unless the 475.Ev CLICOLOR_FORCE 476variable is defined. 477.It Ev CLICOLOR_FORCE 478Color sequences are normally disabled if the output isn't directed to 479a terminal. 480This can be overridden by setting this flag. 481The 482.Ev TERM 483variable still needs to reference a color capable terminal however 484otherwise it is not possible to determine which color sequences to 485use. 486.It Ev COLUMNS 487If this variable contains a string representing a 488decimal integer, it is used as the 489column position width for displaying 490multiple-text-column output. 491The 492.Nm 493utility calculates how 494many pathname text columns to display 495based on the width provided. 496(See 497.Fl C 498and 499.Fl x . ) 500.It Ev LANG 501The locale to use when determining the order of day and month in the long 502.Fl l 503format output. 504See 505.Xr environ 7 506for more information. 507.It Ev LSCOLORS 508The value of this variable describes what color to use for which 509attribute when colors are enabled with 510.Ev CLICOLOR . 511This string is a concatenation of pairs of the format 512.Ar f Ns Ar b , 513where 514.Ar f 515is the foreground color and 516.Ar b 517is the background color. 518.Pp 519The color designators are as follows: 520.Pp 521.Bl -tag -width 4n -offset indent -compact 522.It Sy a 523black 524.It Sy b 525red 526.It Sy c 527green 528.It Sy d 529brown 530.It Sy e 531blue 532.It Sy f 533magenta 534.It Sy g 535cyan 536.It Sy h 537light grey 538.It Sy A 539bold black, usually shows up as dark grey 540.It Sy B 541bold red 542.It Sy C 543bold green 544.It Sy D 545bold brown, usually shows up as yellow 546.It Sy E 547bold blue 548.It Sy F 549bold magenta 550.It Sy G 551bold cyan 552.It Sy H 553bold light grey; looks like bright white 554.It Sy x 555default foreground or background 556.El 557.Pp 558Note that the above are standard 559\*[Ai] 560colors. 561The actual display may differ 562depending on the color capabilities of the terminal in use. 563.Pp 564The order of the attributes are as follows: 565.Pp 566.Bl -enum -offset indent -compact 567.It 568directory 569.It 570symbolic link 571.It 572socket 573.It 574pipe 575.It 576executable 577.It 578block special 579.It 580character special 581.It 582executable with setuid bit set 583.It 584executable with setgid bit set 585.It 586directory writable to others, with sticky bit 587.It 588directory writable to others, without sticky bit 589.El 590.Pp 591The default is 592.Qq "exfxcxdxbxegedabagacad" , 593i.e. blue foreground and 594default background for regular directories, black foreground and red 595background for setuid executables, etc. 596.It Ev LS_COLWIDTHS 597If this variable is set, it is considered to be a 598colon-delimited list of minimum column widths. 599Unreasonable 600and insufficient widths are ignored (thus zero signifies 601a dynamically sized column). 602Not all columns have changeable widths. 603The fields are, 604in order: inode, block count, number of links, user name, 605group name, flags, file size, file name. 606.It Ev TERM 607The 608.Ev CLICOLOR 609functionality depends on a terminal type with color capabilities. 610.It Ev TZ 611The timezone to use when displaying dates. 612See 613.Xr environ 7 614for more information. 615.El 616.Sh COMPATIBILITY 617The group field is now automatically included in the long listing for 618files in order to be compatible with the 619.St -p1003.2 620specification. 621KLD 622.El 623.Sh SEE ALSO 624.Xr chflags 1 , 625.Xr chmod 1 , 626.Xr sort 1 , 627.Xr xterm 1 , 628.Xr termcap 5 , 629.Xr symlink 7 , 630.Xr sticky 8 631.Sh STANDARDS 632The 633.Nm 634utility conforms to 635.St -p1003.1-2001 . 636.Sh HISTORY 637An 638.Nm 639command appeared in 640.At v1 . 641.Sh BUGS 642To maintain backward compatibility, the relationships between the many 643options are quite complex. 644