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