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