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