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