1.\" $NetBSD: ls.1,v 1.69 2011/04/02 08:38:56 mbalmer Exp $ 2.\" 3.\" Copyright (c) 1980, 1990, 1991, 1993, 1994 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" This code is derived from software contributed to Berkeley by 7.\" the Institute of Electrical and Electronics Engineers, Inc. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 3. Neither the name of the University nor the names of its contributors 18.\" may be used to endorse or promote products derived from this software 19.\" without specific prior written permission. 20.\" 21.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 22.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 23.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 24.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 25.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 26.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 27.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 28.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 29.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 30.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 31.\" SUCH DAMAGE. 32.\" 33.\" @(#)ls.1 8.7 (Berkeley) 7/29/94 34.\" 35.Dd April 2, 2011 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 AaBbCcdFfghikLlMmnopqRrSsTtuWwx1 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.Ql \&. 73and 74.Ql \&.. . 75Always set for the super-user. 76.It Fl a 77Include directory entries whose names begin with a 78dot 79.Pq Sq \&. . 80.It Fl B 81Force printing of non-graphic characters in file names as \exxx, where xxx 82is the numeric value of the character in octal. 83.It Fl b 84As 85.Fl B , 86but use C escape codes whenever possible. 87.It Fl C 88Force multi-column output; this is the default when output is to a terminal. 89.It Fl c 90Use time when file status was last changed, 91instead of time of last modification of the file for sorting 92.Pq Fl t 93or printing 94.Pq Fl l . 95.It Fl d 96Directories are listed as plain files (not searched recursively) and 97symbolic links in the argument list are not followed. 98.It Fl F 99Display a slash 100.Pq Sq \&/ 101immediately after each pathname that is a directory, 102an asterisk 103.Pq Sq \&* 104after each that is executable, 105an at sign 106.Pq Sq \&@ 107after each symbolic link, 108a percent sign 109.Pq Sq \&% 110after each whiteout, 111an equal sign 112.Pq Sq \&= 113after each socket, 114and a vertical bar 115.Pq Sq \&| 116after each that is a 117.Tn FIFO . 118.It Fl f 119Output is not sorted. 120.It Fl g 121The same as 122.Fl l , 123except that the owner is not printed. 124.It Fl h 125Modifies the 126.Fl s 127and 128.Fl l 129options, causing the sizes to be reported in bytes displayed in a human 130readable format. 131Overrides 132.Fl k 133and 134.Fl M . 135.It Fl i 136For each file, print the file's file serial number (inode number). 137.It Fl k 138Modifies the 139.Fl s 140option, causing the sizes to be reported in kilobytes. 141The rightmost of the 142.Fl k 143and 144.Fl h 145flags overrides the previous flag. 146See also 147.Fl h 148and 149.Fl M . 150.It Fl L 151For each file, if it's a link, evaluate file information and file type 152of the referenced file and not the link itself; however still print 153the link name, unless used with 154.Fl l , 155for example. 156.It Fl l 157(The lowercase letter 158.Dq ell ) . 159List in long format. 160(See below.) 161A total sum for all the file sizes is output on a line before the long 162listing. 163.It Fl M 164Modifies the 165.Fl l 166and 167.Fl s 168options, causing the sizes or block counts reported to be separated with 169commas (or a locale appropriate separator) resulting in a more readable 170output. 171Overrides 172.Fl h . 173Does not override 174.Fl k . 175.It Fl m 176Stream output format; list files across the page, separated by commas. 177.It Fl n 178The same as 179.Fl l , 180except that 181the owner and group IDs are displayed numerically rather than converting 182to a owner or group name. 183.It Fl o 184Include the file flags in a long 185.Pq Fl l 186output. 187If no file flags are set, 188.Dq - 189is displayed. 190(See 191.Xr chflags 1 192for a list of possible flags and their meanings.) 193.It Fl p 194Display a slash 195.Pq Sq \&/ 196immediately after each pathname that is a directory. 197.It Fl q 198Force printing of non-printable characters in file names as 199the character 200.Sq \&? ; 201this is the default when output is to a terminal. 202.It Fl R 203Recursively list subdirectories encountered. 204.It Fl r 205Reverse the order of the sort to get reverse 206lexicographical order or the smallest or oldest entries first. 207.It Fl S 208Sort by size, largest file first. 209.It Fl s 210Display the number of file system blocks actually used by each file, in units 211of 512 bytes or 212.Ev BLOCKSIZE 213(see 214.Sx ENVIRONMENT ) 215where partial units are rounded up to the 216next integer value. 217If the output is to a terminal, a total sum for all the file 218sizes is output on a line before the listing. 219.It Fl T 220When used with the 221.Fl l 222(the lowercase letter 223.Dq ell ) 224option, display complete time information for the file, including 225month, day, hour, minute, second, and year. 226.It Fl t 227Sort by time modified (most recently modified 228first) before sorting the operands by lexicographical 229order. 230.It Fl u 231Use time of last access, 232instead of last modification 233of the file for sorting 234.Pq Fl t 235or printing 236.Pq Fl l . 237.It Fl W 238Display whiteouts when scanning directories. 239.It Fl w 240Force raw printing of non-printable characters. 241This is the default when output is not to a terminal. 242.It Fl x 243Multi-column output sorted across the page rather than down the page. 244.It Fl \&1 245(The numeric digit 246.Dq one ) . 247Force output to be one entry per line. 248This is the default when output is not to a terminal. 249.El 250.Pp 251The 252.Fl B , 253.Fl b , 254.Fl w , 255and 256.Fl q 257options all override each other; the last one specified determines 258the format used for non-printable characters. 259.Pp 260The 261.Fl 1 , 262.Fl C , 263.Fl g , 264.Fl l , 265.Fl m , 266and 267.Fl x 268options all override each other; the last one specified determines 269the format used with the exception that if both 270.Fl l 271and 272.Fl g 273are specified, 274.Fl l 275will always override 276.Fl g , 277even if 278.Fl g 279was specified last. 280.Pp 281The 282.Fl c 283and 284.Fl u 285options override each other; the last one specified determines 286the file time used. 287.Pp 288By default, 289.Nm 290lists one entry per line to standard 291output; the exceptions are to terminals or when the 292.Fl C 293or 294.Fl m 295options are specified. 296.Pp 297File information is displayed with one or more 298.Aq blank 299separating the information associated with the 300.Fl i , 301.Fl s , 302and 303.Fl l 304options. 305.Ss The Long Format 306If the 307.Fl l 308option is given, the following information 309is displayed for each file: 310.Bl -item -offset indent -compact 311.It 312file mode 313.It 314number of links 315.It 316owner name 317.It 318group name 319.It 320file flags (if 321.Fl o 322given) 323.It 324number of bytes in the file 325.It 326abbreviated month file was last modified 327.It 328day-of-month file was last modified 329.It 330hour and minute file was last modified 331.It 332pathname 333.El 334.Pp 335In addition, for each directory whose contents are displayed, the total 336number of 512-byte blocks used by the files in the directory is displayed 337on a line by itself immediately before the information for the files in the 338directory. 339.Pp 340If the owner or group names are not a known owner or group name, 341or the 342.Fl n 343option is given, 344the numeric ID's are displayed. 345.Pp 346If the file is a character special or block special file, 347the major and minor device numbers for the file are displayed 348in the size field. 349If the file is a symbolic link the pathname of the 350linked-to file is preceded by 351.Dq \-\*[Gt] . 352.Pp 353The file mode printed under the 354.Fl l 355option consists of the entry type, owner permissions, group 356permissions, and other permissions. 357The entry type character describes the type of file, as 358follows: 359.Pp 360.Bl -tag -width 4n -offset indent -compact 361.It Sy a 362Archive state 1. 363.It Sy A 364Archive state 2. 365.It Sy b 366Block special file. 367.It Sy c 368Character special file. 369.It Sy d 370Directory. 371.It Sy l 372Symbolic link. 373.It Sy s 374Socket link. 375.It Sy p 376FIFO. 377.It Sy w 378Whiteout. 379.It Sy \- 380Regular file. 381.El 382.Pp 383The next three fields 384are three characters each: 385owner permissions, 386group permissions, and 387other permissions. 388Each field has three character positions: 389.Bl -enum -offset indent 390.It 391If 392.Sy r , 393the file is readable; if 394.Sy \- , 395it is not readable. 396.It 397If 398.Sy w , 399the file is writable; if 400.Sy \- , 401it is not writable. 402.It 403The first of the following that applies: 404.Bl -tag -width 4n -offset indent 405.It Sy S 406If in the owner permissions, the file is not executable and 407set-user-ID mode is set. 408If in the group permissions, the file is not executable 409and set-group-ID mode is set. 410.It Sy s 411If in the owner permissions, the file is executable 412and set-user-ID mode is set. 413If in the group permissions, the file is executable 414and setgroup-ID mode is set. 415.It Sy x 416The file is executable or the directory is 417searchable. 418.It Sy \- 419The file is neither readable, writable, executable, 420nor set-user-ID nor set-group-ID mode, nor sticky. 421(See below.) 422.El 423.Pp 424These next two apply only to the third character in the last group 425(other permissions). 426.Bl -tag -width 4n -offset indent 427.It Sy T 428The sticky bit is set 429(mode 430.Li 1000 ) , 431but not execute or search permission. 432(See 433.Xr chmod 1 434or 435.Xr sticky 7 . ) 436.It Sy t 437The sticky bit is set (mode 438.Li 1000 ) , 439and is searchable or executable. 440(See 441.Xr chmod 1 442or 443.Xr sticky 7 . ) 444.El 445.El 446.Pp 447The number of bytes displayed for a directory is a function of the 448number of 449.Xr dirent 3 450structures in the directory, not all of which may be allocated to 451any existing file. 452.Sh ENVIRONMENT 453The following environment variables affect the execution of 454.Nm : 455.Bl -tag -width BLOCKSIZE 456.It Ev BLOCKSIZE 457If the environment variable 458.Ev BLOCKSIZE 459is set, and the 460.Fl h 461and 462.Fl k 463options are not specified, the block counts 464(see 465.Fl s ) 466will be displayed in units of that size block. 467.It Ev COLUMNS 468If this variable contains a string representing a 469decimal integer, it is used as the 470column position width for displaying 471multiple-text-column output. 472The 473.Nm 474utility calculates how 475many pathname text columns to display 476based on the width provided. 477(See 478.Fl C . ) 479.It Ev TZ 480The timezone to use when displaying dates. 481See 482.Xr environ 7 483for more information. 484.El 485.Sh EXIT STATUS 486.Ex -std 487.Sh COMPATIBILITY 488The group field is now automatically included in the long listing for 489files in order to be compatible with the 490.St -p1003.2 491specification. 492.Sh SEE ALSO 493.Xr chflags 1 , 494.Xr chmod 1 , 495.Xr stat 2 , 496.Xr dirent 3 , 497.Xr getbsize 3 , 498.Xr sticky 7 , 499.Xr symlink 7 500.Sh STANDARDS 501The 502.Nm 503utility is expected to be a superset of the 504.St -p1003.2 505specification. 506.Sh HISTORY 507An 508.Nm 509utility appeared in 510.At v5 . 511