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