1.\" $NetBSD: ls.1,v 1.79 2016/08/10 17:45:12 sevan 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 August 10, 2016 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 1AaBbCcdFfghikLlMmnOoPpqRrSsTtuWwXx 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. 130This option implies 131.Fl a . 132.It Fl g 133The same as 134.Fl l , 135except that the owner is not printed. 136.It Fl h 137Modifies the 138.Fl l 139and 140.Fl s 141options, causing the sizes to be reported in bytes displayed in a human 142readable format. 143Overrides 144.Fl k 145and 146.Fl M . 147.It Fl i 148For each file, print the file's file serial number (inode number). 149.It Fl k 150Modifies the 151.Fl s 152option, causing the sizes to be reported in kilobytes. 153Overrides 154.Fl h . 155.It Fl L 156For each file, if it's a link, evaluate file information and file type 157of the referenced file and not the link itself; however still print 158the link name, unless used with 159.Fl l , 160for example. 161.It Fl l 162(The lowercase letter 163.Dq ell ) . 164List in long format. 165(See below.) 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 187Output only leaf files (not directories), eliding other 188.Nm 189output. 190.It Fl o 191Include the file flags in a long 192.Pq Fl l 193output. 194If no file flags are set, 195.Dq - 196is displayed. 197(See 198.Xr chflags 1 199for a list of possible flags and their meanings.) 200.It Fl P 201Print the full pathname for each file. 202.It Fl p 203Display a slash 204.Pq Sq \&/ 205immediately after each pathname that is a directory. 206.It Fl q 207Force printing of non-printable characters in file names as 208the character 209.Sq \&? ; 210this is the default when output is to a terminal. 211.It Fl R 212Recursively list subdirectories encountered. 213See also 214.Fl d . 215.It Fl r 216Reverse the order of the sort to get reverse 217lexicographical order or the smallest or oldest entries first. 218.It Fl S 219Sort by size, largest file first. 220.It Fl s 221Display the number of file system blocks actually used by each file, in units 222of 512 bytes or 223.Ev BLOCKSIZE 224(see 225.Sx ENVIRONMENT ) 226where partial units are rounded up to the 227next integer value. 228If the output is to a terminal, a total sum for all the file 229sizes is output on a line before the listing. 230.It Fl T 231When used with the 232.Fl l 233(the lowercase letter 234.Dq ell ) 235option, display complete time information for the file, including 236month, day, hour, minute, second, and year. 237.It Fl t 238Sort by time modified (most recently modified 239first) before sorting the operands by lexicographical 240order. 241.It Fl u 242Use time of last access, 243instead of last modification 244of the file for printing 245.Pq Fl l 246or sorting 247.Pq Fl t . 248Overrides 249.Fl c . 250.It Fl W 251Display whiteouts when scanning directories. 252.It Fl w 253Force raw printing of non-printable characters. 254This is the default when output is not to a terminal. 255.It Fl x 256Multi-column output sorted across the page rather than down the page. 257.It Fl X 258Don't cross mount points when recursing. 259.El 260.Pp 261The 262.Fl B , 263.Fl b , 264.Fl q , 265and 266.Fl w 267options all override each other; the last one specified determines 268the format used for non-printable characters. 269.Pp 270The 271.Fl 1 , 272.Fl C , 273.Fl g , 274.Fl l , 275.Fl m , 276and 277.Fl x 278options all override each other; the last one specified determines 279the format used with the exception that if both 280.Fl l 281and 282.Fl g 283are specified, 284.Fl l 285will always override 286.Fl g , 287even if 288.Fl g 289was specified last. 290.Pp 291By default, 292.Nm 293lists one entry per line to standard 294output; the exceptions are to terminals or when the 295.Fl C 296or 297.Fl m 298options are specified. 299.Pp 300File information is displayed with one or more 301.Aq blank 302characters separating the information associated with the 303.Fl i , 304.Fl l , 305and 306.Fl s 307options. 308.Ss The Long Format 309If the 310.Fl l 311option is given, the following information 312is displayed for each file: 313.Bl -item -offset indent -compact 314.It 315file mode 316.It 317number of links 318.It 319owner name 320.It 321group name 322.It 323file flags (if 324.Fl o 325given) 326.It 327number of bytes in the file 328.It 329abbreviated month file was last modified 330.It 331day-of-month file was last modified 332.It 333hour and minute file was last modified 334.It 335pathname 336.El 337.Pp 338In addition, for each directory whose contents are displayed, the total 339number of file system blocks in units of 512 bytes or 340.Ev BLOCKSIZE 341(see 342.Sx ENVIRONMENT ) 343used by the files in the directory is displayed on a line by itself 344immediately before the information for the files in the directory. 345.Pp 346If the owner or group names are not a known owner or group name, 347or the 348.Fl n 349option is given, 350the numeric ID's are displayed. 351.Pp 352If the file is a character special or block special file, 353the major and minor device numbers for the file are displayed 354in the size field. 355If the file is a symbolic link the pathname of the 356linked-to file is preceded by 357.Dq \-\*[Gt] . 358.Pp 359The file mode printed under the 360.Fl l 361option consists of the entry type, owner permissions, group 362permissions, and other permissions. 363The entry type character describes the type of file, as 364follows: 365.Pp 366.Bl -tag -width 4n -offset indent -compact 367.It Sy \- 368Regular file. 369.It Sy a 370Archive state 1. 371.It Sy A 372Archive state 2. 373.It Sy b 374Block special file. 375.It Sy c 376Character special file. 377.It Sy d 378Directory. 379.It Sy l 380Symbolic link. 381.It Sy p 382FIFO. 383.It Sy s 384Socket link. 385.It Sy w 386Whiteout. 387.El 388.Pp 389The next three fields 390are three characters each: 391owner permissions, 392group permissions, and 393other permissions. 394Each field has three character positions: 395.Bl -enum -offset indent 396.It 397If 398.Sy r , 399the file is readable; if 400.Sy \- , 401it is not readable. 402.It 403If 404.Sy w , 405the file is writable; if 406.Sy \- , 407it is not writable. 408.It 409The first of the following that applies: 410.Bl -tag -width 4n -offset indent 411.It Sy S 412If in the owner permissions, the file is not executable and 413set-user-ID mode is set. 414If in the group permissions, the file is not executable 415and set-group-ID mode is set. 416.It Sy s 417If in the owner permissions, the file is executable 418and set-user-ID mode is set. 419If in the group permissions, the file is executable 420and setgroup-ID mode is set. 421.It Sy x 422The file is executable or the directory is 423searchable. 424.It Sy \- 425The file is neither readable, writable, executable, 426nor set-user-ID nor set-group-ID mode, nor sticky. 427(See below.) 428.El 429.Pp 430These next two apply only to the third character in the last group 431(other permissions). 432.Bl -tag -width 4n -offset indent 433.It Sy T 434The sticky bit is set 435(mode 436.Li 1000 ) , 437but not execute or search permission. 438(See 439.Xr chmod 1 440or 441.Xr sticky 7 . ) 442.It Sy t 443The sticky bit is set (mode 444.Li 1000 ) , 445and is searchable or executable. 446(See 447.Xr chmod 1 448or 449.Xr sticky 7 . ) 450.El 451.El 452.Pp 453The number of bytes displayed for a directory is a function of the 454number of 455.Xr dirent 3 456structures in the directory, not all of which may be allocated to 457any existing file. 458.Sh ENVIRONMENT 459The following environment variables affect the execution of 460.Nm : 461.Bl -tag -width BLOCKSIZE 462.It Ev BLOCKSIZE 463If the environment variable 464.Ev BLOCKSIZE 465is set, and the 466.Fl k 467option is not specified, the block counts 468(see 469.Fl l 470and 471.Fl s ) 472will be displayed in units of that size block. 473.It Ev COLUMNS 474If this variable contains a string representing a 475decimal integer, it is used as the 476column position width for displaying 477multiple-text-column output. 478The 479.Nm 480utility calculates how 481many pathname text columns to display 482based on the width provided. 483(See 484.Fl C . ) 485.It Ev TZ 486The timezone to use when displaying dates. 487See 488.Xr environ 7 489for more information. 490.El 491.Sh EXIT STATUS 492.Ex -std 493.Sh COMPATIBILITY 494The group field is now automatically included in the long listing for 495files in order to be compatible with the 496.St -p1003.2 497specification. 498.Sh SEE ALSO 499.Xr chflags 1 , 500.Xr chmod 1 , 501.Xr stat 2 , 502.Xr dirent 3 , 503.Xr getbsize 3 , 504.Xr sticky 7 , 505.Xr symlink 7 506.Sh STANDARDS 507The 508.Nm 509utility is expected to be a superset of the 510.St -p1003.2 511specification. 512.Sh HISTORY 513An 514.Nm 515utility appeared in 516.At v1 . 517