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