1.\" $NetBSD: ls.1,v 1.72 2012/11/20 12:37:29 abs 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 November 20, 2012 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 1AaBbCcdFfghikLlMmnopqRrSsTtuWwx 44.Op Ar 45.Sh DESCRIPTION 46For each 47.Ar file 48operand that names a file of a type other than 49directory, 50.Nm 51displays its name as well as any requested, 52associated information. 53For each 54.Ar file 55operand that names a file of 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 \&1 71(The numeric digit 72.Dq one ) . 73Force output to be one entry per line. 74This is the default when output is not to a terminal. 75.It Fl A 76List all entries except for 77.Ql \&. 78and 79.Ql \&.. . 80Always set for the super-user. 81.It Fl a 82Include directory entries whose names begin with a 83dot 84.Pq Sq \&. . 85.It Fl B 86Force printing of non-graphic characters in file names as \exxx, where xxx 87is the numeric value of the character in octal. 88.It Fl b 89As 90.Fl B , 91but use C escape codes whenever possible. 92.It Fl C 93Force multi-column output; this is the default when output is to a terminal. 94.It Fl c 95Use time when file status was last changed, 96instead of time of last modification of the file for printing 97.Pq Fl l 98or sorting 99.Pq Fl t . 100Overrides 101.Fl u . 102.It Fl d 103Directories are listed as plain files (not searched recursively) and 104symbolic links in the argument list are not followed. 105Turns off 106.Fl R 107if also given. 108.It Fl F 109Display a slash 110.Pq Sq \&/ 111immediately after each pathname that is a directory, 112an asterisk 113.Pq Sq \&* 114after each that is executable, 115an at sign 116.Pq Sq \&@ 117after each symbolic link, 118a percent sign 119.Pq Sq \&% 120after each whiteout, 121an equal sign 122.Pq Sq \&= 123after each socket, 124and a vertical bar 125.Pq Sq \&| 126after each that is a 127.Tn FIFO . 128.It Fl f 129Output is not sorted. 130.It Fl g 131The same as 132.Fl l , 133except that the owner is not printed. 134.It Fl h 135Modifies the 136.Fl l 137and 138.Fl s 139options, causing the sizes to be reported in bytes displayed in a human 140readable format. 141Overrides 142.Fl k 143and 144.Fl M . 145.It Fl i 146For each file, print the file's file serial number (inode number). 147.It Fl k 148Modifies the 149.Fl s 150option, causing the sizes to be reported in kilobytes. 151Overrides 152.Fl h . 153.It Fl L 154For each file, if it's a link, evaluate file information and file type 155of the referenced file and not the link itself; however still print 156the link name, unless used with 157.Fl l , 158for example. 159.It Fl l 160(The lowercase letter 161.Dq ell ) . 162List in long format. 163(See below.) 164A total sum for all the file sizes is output on a line before the long 165listing. 166.It Fl M 167Modifies the 168.Fl l 169and 170.Fl s 171options, causing the sizes or block counts reported to be separated with 172commas (or a locale appropriate separator) resulting in a more readable 173output. 174Overrides 175.Fl h ; 176does not override 177.Fl k . 178.It Fl m 179Stream output format; list files across the page, separated by commas. 180.It Fl n 181The same as 182.Fl l , 183except that 184the owner and group IDs are displayed numerically rather than converting 185to a owner or group name. 186.It Fl o 187Include the file flags in a long 188.Pq Fl l 189output. 190If no file flags are set, 191.Dq - 192is displayed. 193(See 194.Xr chflags 1 195for a list of possible flags and their meanings.) 196.It Fl p 197Display a slash 198.Pq Sq \&/ 199immediately after each pathname that is a directory. 200.It Fl q 201Force printing of non-printable characters in file names as 202the character 203.Sq \&? ; 204this is the default when output is to a terminal. 205.It Fl R 206Recursively list subdirectories encountered. 207See also 208.Fl d . 209.It Fl r 210Reverse the order of the sort to get reverse 211lexicographical order or the smallest or oldest entries first. 212.It Fl S 213Sort by size, largest file first. 214.It Fl s 215Display the number of file system blocks actually used by each file, in units 216of 512 bytes or 217.Ev BLOCKSIZE 218(see 219.Sx ENVIRONMENT ) 220where partial units are rounded up to the 221next integer value. 222If the output is to a terminal, a total sum for all the file 223sizes is output on a line before the listing. 224.It Fl T 225When used with the 226.Fl l 227(the lowercase letter 228.Dq ell ) 229option, display complete time information for the file, including 230month, day, hour, minute, second, and year. 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 printing 239.Pq Fl l 240or sorting 241.Pq Fl t . 242Overrides 243.Fl c . 244.It Fl W 245Display whiteouts when scanning directories. 246.It Fl w 247Force raw printing of non-printable characters. 248This is the default when output is not to a terminal. 249.It Fl x 250Multi-column output sorted across the page rather than down the page. 251.El 252.Pp 253The 254.Fl B , 255.Fl b , 256.Fl q , 257and 258.Fl w 259options all override each other; the last one specified determines 260the format used for non-printable characters. 261.Pp 262The 263.Fl 1 , 264.Fl C , 265.Fl g , 266.Fl l , 267.Fl m , 268and 269.Fl x 270options all override each other; the last one specified determines 271the format used with the exception that if both 272.Fl l 273and 274.Fl g 275are specified, 276.Fl l 277will always override 278.Fl g , 279even if 280.Fl g 281was specified last. 282.Pp 283By default, 284.Nm 285lists one entry per line to standard 286output; the exceptions are to terminals or when the 287.Fl C 288or 289.Fl m 290options are specified. 291.Pp 292File information is displayed with one or more 293.Aq blank 294characters separating the information associated with the 295.Fl i , 296.Fl l , 297and 298.Fl s 299options. 300.Ss The Long Format 301If the 302.Fl l 303option is given, the following information 304is displayed for each file: 305.Bl -item -offset indent -compact 306.It 307file mode 308.It 309number of links 310.It 311owner name 312.It 313group name 314.It 315file flags (if 316.Fl o 317given) 318.It 319number of bytes in the file 320.It 321abbreviated month file was last modified 322.It 323day-of-month file was last modified 324.It 325hour and minute file was last modified 326.It 327pathname 328.El 329.Pp 330In addition, for each directory whose contents are displayed, the total 331number of file system blocks in units of 512 bytes or 332.Ev BLOCKSIZE 333(see 334.Sx ENVIRONMENT ) 335used by the files in the directory is displayed on a line by itself 336immediately before the information for the files in the directory. 337.Pp 338If the owner or group names are not a known owner or group name, 339or the 340.Fl n 341option is given, 342the numeric ID's are displayed. 343.Pp 344If the file is a character special or block special file, 345the major and minor device numbers for the file are displayed 346in the size field. 347If the file is a symbolic link the pathname of the 348linked-to file is preceded by 349.Dq \-\*[Gt] . 350.Pp 351The file mode printed under the 352.Fl l 353option consists of the entry type, owner permissions, group 354permissions, and other permissions. 355The entry type character describes the type of file, as 356follows: 357.Pp 358.Bl -tag -width 4n -offset indent -compact 359.It Sy \- 360Regular file. 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 p 374FIFO. 375.It Sy s 376Socket link. 377.It Sy w 378Whiteout. 379.El 380.Pp 381The next three fields 382are three characters each: 383owner permissions, 384group permissions, and 385other permissions. 386Each field has three character positions: 387.Bl -enum -offset indent 388.It 389If 390.Sy r , 391the file is readable; if 392.Sy \- , 393it is not readable. 394.It 395If 396.Sy w , 397the file is writable; if 398.Sy \- , 399it is not writable. 400.It 401The first of the following that applies: 402.Bl -tag -width 4n -offset indent 403.It Sy S 404If in the owner permissions, the file is not executable and 405set-user-ID mode is set. 406If in the group permissions, the file is not executable 407and set-group-ID mode is set. 408.It Sy s 409If in the owner permissions, the file is executable 410and set-user-ID mode is set. 411If in the group permissions, the file is executable 412and setgroup-ID mode is set. 413.It Sy x 414The file is executable or the directory is 415searchable. 416.It Sy \- 417The file is neither readable, writable, executable, 418nor set-user-ID nor set-group-ID mode, nor sticky. 419(See below.) 420.El 421.Pp 422These next two apply only to the third character in the last group 423(other permissions). 424.Bl -tag -width 4n -offset indent 425.It Sy T 426The sticky bit is set 427(mode 428.Li 1000 ) , 429but not execute or search permission. 430(See 431.Xr chmod 1 432or 433.Xr sticky 7 . ) 434.It Sy t 435The sticky bit is set (mode 436.Li 1000 ) , 437and is searchable or executable. 438(See 439.Xr chmod 1 440or 441.Xr sticky 7 . ) 442.El 443.El 444.Pp 445The number of bytes displayed for a directory is a function of the 446number of 447.Xr dirent 3 448structures in the directory, not all of which may be allocated to 449any existing file. 450.Sh ENVIRONMENT 451The following environment variables affect the execution of 452.Nm : 453.Bl -tag -width BLOCKSIZE 454.It Ev BLOCKSIZE 455If the environment variable 456.Ev BLOCKSIZE 457is set, and the 458.Fl k 459option is not specified, the block counts 460(see 461.Fl l 462and 463.Fl s ) 464will be displayed in units of that size block. 465.It Ev COLUMNS 466If this variable contains a string representing a 467decimal integer, it is used as the 468column position width for displaying 469multiple-text-column output. 470The 471.Nm 472utility calculates how 473many pathname text columns to display 474based on the width provided. 475(See 476.Fl C . ) 477.It Ev TZ 478The timezone to use when displaying dates. 479See 480.Xr environ 7 481for more information. 482.El 483.Sh EXIT STATUS 484.Ex -std 485.Sh COMPATIBILITY 486The group field is now automatically included in the long listing for 487files in order to be compatible with the 488.St -p1003.2 489specification. 490.Sh SEE ALSO 491.Xr chflags 1 , 492.Xr chmod 1 , 493.Xr stat 2 , 494.Xr dirent 3 , 495.Xr getbsize 3 , 496.Xr sticky 7 , 497.Xr symlink 7 498.Sh STANDARDS 499The 500.Nm 501utility is expected to be a superset of the 502.St -p1003.2 503specification. 504.Sh HISTORY 505An 506.Nm 507utility appeared in 508.At v5 . 509