1.\" $OpenBSD: ls.1,v 1.31 2001/05/01 17:58:01 aaron Exp $ 2.\" $NetBSD: ls.1,v 1.14 1995/12/05 02:44:01 jtc Exp $ 3.\" 4.\" Copyright (c) 1980, 1990, 1991, 1993, 1994 5.\" The Regents of the University of California. All rights reserved. 6.\" 7.\" This code is derived from software contributed to Berkeley by 8.\" the Institute of Electrical and Electronics Engineers, Inc. 9.\" 10.\" Redistribution and use in source and binary forms, with or without 11.\" modification, are permitted provided that the following conditions 12.\" are met: 13.\" 1. Redistributions of source code must retain the above copyright 14.\" notice, this list of conditions and the following disclaimer. 15.\" 2. Redistributions in binary form must reproduce the above copyright 16.\" notice, this list of conditions and the following disclaimer in the 17.\" documentation and/or other materials provided with the distribution. 18.\" 3. All advertising materials mentioning features or use of this software 19.\" must display the following acknowledgement: 20.\" This product includes software developed by the University of 21.\" California, Berkeley and its contributors. 22.\" 4. Neither the name of the University nor the names of its contributors 23.\" may be used to endorse or promote products derived from this software 24.\" without specific prior written permission. 25.\" 26.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 27.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 28.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 29.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 30.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 31.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 32.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 33.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 34.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 35.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 36.\" SUCH DAMAGE. 37.\" 38.\" @(#)ls.1 8.7 (Berkeley) 7/29/94 39.\" 40.Dd July 29, 1994 41.Dt LS 1 42.Os 43.Sh NAME 44.Nm ls 45.Nd list directory contents 46.Sh SYNOPSIS 47.Nm ls 48.Op Fl 1ACFLRSTWacdfgiklmnopqrstux 49.Op Ar file ... 50.Sh DESCRIPTION 51For each operand that names a 52.Ar file 53of a type other than directory, 54.Nm 55displays its name as well as any requested, 56associated information. 57For each named directory, 58.Nm 59displays the names of files contained 60within that directory, as well as any requested, associated 61information. 62.Pp 63If no operands are given, the contents of the current 64directory are displayed. 65If more than one operand is given, 66non-directory operands are displayed first; directory 67and non-directory operands are sorted separately and in 68lexicographical order. 69.Pp 70The options are as follows: 71.Bl -tag -width Ds 72.It Fl A 73List all entries except for 74.Dq \&. 75and 76.Dq \&.. . 77Always set for the superuser. 78.It Fl C 79Force multi-column output; this is the default when output is to a terminal. 80.It Fl F 81Display a slash 82.Pq Sq / 83immediately after each pathname that is a directory, 84an asterisk 85.Pq Sq \&* 86after each that is executable, 87an at sign 88.Pq Sq @ 89after each symbolic link, 90a percent sign 91.Pq Sq % 92after each whiteout, 93an equal sign 94.Pq Sq = 95after each socket, 96and a vertical bar 97.Pq Sq \&| 98after each that is a FIFO. 99.It Fl L 100If argument is a symbolic link, list the file or directory the link references 101rather than the link itself. 102.It Fl R 103Recursively list subdirectories encountered. 104.It Fl S 105Sort by size, largest file first. 106.It Fl T 107Display complete time information for the file, including 108month, day, hour, minute, second, and year. 109This option has no effect unless one of the long format 110.Pq Fl l , Fl n 111options is also specified. 112.It Fl W 113Display whiteouts when scanning directories. 114.It Fl a 115Include directory entries whose names begin with a 116dot 117.Pq Sq \&. . 118.It Fl c 119Use time file's status was last changed instead of last modification 120time for sorting 121.Pq Fl t 122or printing 123.Pq Fl l , Fl n . 124.It Fl d 125Directories are listed as plain files (not searched recursively) and 126symbolic links in the argument list are not indirected through. 127.It Fl f 128Output is not sorted. 129.It Fl g 130Does nothing; kept for compatibility with older versions of 131.Xr ls 1 . 132.It Fl i 133For each file, print its inode number. 134.It Fl k 135Modifies the 136.Fl s 137option, causing the sizes to be reported in kilobytes. 138Overrides any value specified by the 139.Ev BLOCKSIZE 140environment variable. 141.It Fl l 142(The lowercase letter 143.Dq ell. Ns ) 144List in long format (see below). 145If the output is to a terminal, a total sum of all file 146sizes is output on a line before the long listing. 147.It Fl m 148Stream output format; list files across the page, separated by commas. 149.It Fl n 150List in long format as in 151.Fl l , 152but retain user and group IDs in a numeric format. 153.It Fl o 154Include the file flags in a long format 155.Pq Fl l , Fl n 156output. 157.It Fl p 158Display a slash 159.Pq Sq \&/ 160immediately after each pathname that is a directory. 161.It Fl q 162Force printing of non-graphic characters in file names as 163the character 164.Dq ? ; 165this is the default when output is to a terminal. 166.It Fl r 167Reverse the order of the sort to get reverse 168lexicographical order or the smallest or oldest entries first. 169.It Fl s 170Display the number of file system blocks actually used by each file, 171where partial units are rounded up to the next integer value. 172Blocks are 512 bytes unless overridden by the 173.Fl k 174flag or 175.Ev BLOCKSIZE 176environment variable. 177.It Fl t 178Sort by time modified (most recently modified 179first) before sorting the operands in lexicographical 180order. 181.It Fl u 182Use file's last access time 183instead of last modification time 184for sorting 185.Pq Fl t 186or printing 187.Pq Fl l , Fl n . 188.It Fl x 189Multi-column output sorted across the page rather than down the page. 190.It Fl \&1 191(The numeric digit 192.Dq one. Ns ) 193Force output to be one 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 , 201.Fl l , 202and 203.Fl n 204options all override each other; the last one specified determines 205the format used. 206.Pp 207The 208.Fl c 209and 210.Fl u 211options override each other; the last one specified determines 212the file time used. 213The 214.Fl f 215option overrides any occurrence of either. 216.Pp 217By default, 218.Nm 219lists one entry per line to standard 220output; the exceptions are to terminals or when the 221.Fl C 222or 223.Fl m 224options are specified. 225.Pp 226File information is displayed with one or more 227<blank>s separating the information associated with the 228.Fl i , 229.Fl s , 230.Fl l , 231and 232.Fl n 233options. 234.Ss The Long Format 235If the 236.Fl l 237or 238.Fl n 239options are given, the following information 240is displayed for each file: 241mode, 242number of links, 243owner, 244group, 245size in bytes, 246time of last modification 247.Pq Dq mmm dd HH:MM , 248and the pathname. 249In addition, for each directory whose contents are displayed, the first 250line displayed is the total number of blocks used by the files in the 251directory. 252Blocks are 512 bytes unless overridden by the 253.Fl k 254option or 255.Ev BLOCKSIZE 256environment variable. 257.Pp 258If the owner or group name is not a known user or group name, respectively, 259or the 260.Fl n 261option is given, the numeric ID is displayed. 262.Pp 263If the file is a character special or block special file, 264the major and minor device numbers for the file are displayed 265in the size field. 266.Pp 267If the 268.Fl T 269option is given, the time of last modification is displayed using the 270format 271.Dq mmm dd HH:MM:SS CCYY . 272.Pp 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 279or 280.Fl n 281options consists of the entry type, owner permissions, and group 282permissions. 283The entry type character describes the type of file, as follows: 284.Pp 285.Bl -tag -width 4n -offset indent -compact 286.It Sy b 287block special file 288.It Sy c 289character special file 290.It Sy d 291directory 292.It Sy l 293symbolic link 294.It Sy s 295socket link 296.It Sy p 297.Tn FIFO 298.It Sy w 299whiteout 300.It Sy \- 301regular file 302.El 303.Pp 304The next three fields 305are three characters each: 306owner permissions, 307group permissions, and 308other permissions. 309Each field has three character positions: 310.Pp 311.Bl -enum -offset indent -compact 312.It 313If 314.Sy r , 315the file is readable; if 316.Sy \- , 317it is not readable. 318.It 319If 320.Sy w , 321the file is writable; if 322.Sy \- , 323it is not writable. 324.It 325The first of the following that applies: 326.Bl -tag -width 4n -offset indent 327.It Sy S 328If in the owner permissions, the file is not executable and 329set-user-ID mode is set. 330If in the group permissions, the file is not executable 331and set-group-ID mode is set. 332.It Sy s 333If in the owner permissions, the file is executable 334and set-user-ID mode is set. 335If in the group permissions, the file is executable 336and setgroup-ID mode is set. 337.It Sy x 338The file is executable or the directory is 339searchable. 340.It Sy \- 341The file is neither readable, writable, executable, 342nor set-user-ID, nor set-group-ID, nor sticky (see below). 343.El 344.Pp 345These next two apply only to the third character in the last group 346(other permissions): 347.Bl -tag -width 4n -offset indent 348.It Sy T 349The sticky bit is set 350(mode 351.Li 1000 ) , 352but neither executable nor searchable (see 353.Xr chmod 1 354or 355.Xr sticky 8 ) . 356.It Sy t 357The sticky bit is set (mode 358.Li 1000 ) , 359and is searchable or executable 360(see 361.Xr chmod 1 362or 363.Xr sticky 8 ) . 364.El 365.El 366.Pp 367In addition, if the 368.Fl o 369option is specified, the file flags (see 370.Xr chflags 1 ) 371are displayed as comma-separated strings in front of the file size, 372abbreviated as follows: 373.Pp 374.Bl -tag -width 8n -offset indent -compact 375.It \&- 376no flags 377.It uappnd 378user append-only 379.It uchg 380user immutable 381.It nodump 382do not dump 383.It opaque 384opaque file 385.It sappnd 386system append-only 387.It arch 388archived 389.It schg 390system immutable 391.El 392.Pp 393The 394.Nm 395utility exits 0 on success or >0 if an error occurred. 396.Sh EXAMPLES 397.Cm ls -l 398.Pp 399List the contents of the current working directory in long format. 400.Pp 401.Cm ls -lioF 402.Pp 403In addition to listing the contents of the current working directory in 404long format, show inode numbers, file flags (see 405.Xr chflags 1 ) , 406and suffix each filename with a symbol representing its file type. 407.Pp 408.Cm ls -lt /var/log 409.Pp 410List the files in 411.Pa /var/log , 412sorting the output such that the mostly recently modified entries are 413printed first. 414.Sh ENVIRONMENT 415.Bl -tag -width BLOCKSIZE 416.It Ev BLOCKSIZE 417If the environment variable 418.Ev BLOCKSIZE 419is set, and the 420.Fl k 421option is not specified, the block counts 422(see 423.Fl s ) 424will be displayed in units of that size block. 425.It COLUMNS 426If this variable contains a string representing a 427decimal integer, it is used as the 428column position width for displaying 429multiple-text-column output. 430The 431.Nm 432utility calculates how 433many pathname text columns to display 434based on the width provided 435(see 436.Fl C ) . 437.It Ev TZ 438The timezone to use when displaying dates. 439See 440.Xr environ 7 441for more information. 442.El 443.Sh COMPATIBILITY 444The group field is now automatically included in the long listing for 445files in order to be compatible with the 446.St -p1003.2 447specification. 448.Sh SEE ALSO 449.Xr chflags 1 , 450.Xr chmod 1 , 451.Xr symlink 7 , 452.Xr sticky 8 453.Sh STANDARDS 454The 455.Nm 456utility is expected to be a superset of the 457.St -p1003.2 458specification. 459.Sh HISTORY 460An 461.Nm 462utility appeared in 463.At v5 . 464