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