1.\" $NetBSD: ls.1,v 1.33 2002/04/29 19:47:01 kleink 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 file ... 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 98Display complete time information for the file, including 99month, day, hour, minute, second, and year. 100.It Fl W 101Display whiteouts when scanning directories. 102.It Fl a 103Include directory entries whose names begin with a 104dot (.). 105.It Fl c 106Use time when file status was last changed for sorting or printing. 107.It Fl d 108Directories are listed as plain files (not searched recursively) and 109symbolic links in the argument list are not indirected through. 110.It Fl f 111Output is not sorted. 112.It Fl g 113Does nothing; kept for compatibility with older versions of 114.Xr ls 1 . 115.It Fl i 116For each file, print the file's file serial number (inode number). 117.It Fl k 118Modifies the 119.Fl s 120option, causing the sizes to be reported in kilobytes. 121.It Fl l 122(The lowercase letter ``ell.'') List in long format. (See below.) 123If the output is to a terminal, a total sum for all the file 124sizes is output on a line before the long listing. 125.It Fl m 126Stream output format; list files across the page, separated by commas. 127.It Fl n 128Display the user and group IDs numerically rather than converting 129to a user or group name in a long 130.Pq Fl l 131output. 132.It Fl o 133Include the file flags in a long 134.Pq Fl l 135output. 136If no file flags are set, 137.Dq - 138is displayed. 139(See 140.Xr chflags 1 141for a list of possible flags and their meanings.) 142.It Fl p 143Display a slash (/) immediately after each pathname that is a directory. 144.It Fl q 145Force printing of non-graphic characters in file names as 146the character `?'; this is the default when output is to a terminal. 147.It Fl r 148Reverse the order of the sort to get reverse 149lexicographical order or the smallest or oldest entries first. 150.It Fl s 151Display the number of file system blocks actually used by each file, in units 152of 512 bytes, where partial units are rounded up to the next integer value. 153If the output is to a terminal, a total sum for all the file 154sizes is output on a line before the listing. 155.It Fl t 156Sort by time modified (most recently modified 157first) before sorting the operands by lexicographical 158order. 159.It Fl u 160Use time of last access, 161instead of last modification 162of the file for sorting 163.Pq Fl t 164or printing 165.Pq Fl l . 166.It Fl x 167Multi-column output sorted across the page rather than down the page. 168.It Fl \&1 169(The numeric digit ``one.'') Force output to be 170one entry per line. 171This is the default when 172output is not to a terminal. 173.El 174.Pp 175The 176.Fl 1 , 177.Fl C , 178.Fl l , 179.Fl m , 180and 181.Fl x 182options all override each other; the last one specified determines 183the format used. 184.Pp 185The 186.Fl c , 187and 188.Fl u 189options override each other; the last one specified determines 190the file time used. 191.Pp 192By default, 193.Nm 194lists one entry per line to standard 195output; the exceptions are to terminals or when the 196.Fl C 197or 198.Fl m 199options are specified. 200.Pp 201File information is displayed with one or more 202\*[Lt]blank\*[Gt]s separating the information associated with the 203.Fl i , 204.Fl s , 205and 206.Fl l 207options. 208.Ss The Long Format 209If the 210.Fl l 211option is given, the following information 212is displayed for each file: 213.Bl -item -offset indent -compact 214.It 215file mode 216.It 217number of links 218.It 219owner name 220.It 221group name 222.It 223file flags (if 224.Fl o 225given) 226.It 227number of bytes in the file 228.It 229abbreviated month file was last modified 230.It 231day-of-month file was last modified 232.It 233hour and minute file was last modified 234.It 235pathname 236.El 237.Pp 238In addition, for each directory whose contents are displayed, the total 239number of 512-byte blocks used by the files in the directory is displayed 240on a line by itself immediately before the information for the files in the 241directory. 242.Pp 243If the owner or group names are not a known user or group name, 244or the 245.Fl n 246option is given, 247the numeric ID's are displayed. 248.Pp 249If the file is a character special or block special file, 250the major and minor device numbers for the file are displayed 251in the size field. 252If the file is a symbolic link the pathname of the 253linked-to file is preceded by 254.Dq \-\*[Gt] . 255.Pp 256The file mode printed under the 257.Fl l 258option consists of the 259entry type, owner permissions, and group permissions. 260The entry type character describes the type of file, as 261follows: 262.Pp 263.Bl -tag -width 4n -offset indent -compact 264.It Sy b 265Block special file. 266.It Sy c 267Character special file. 268.It Sy d 269Directory. 270.It Sy l 271Symbolic link. 272.It Sy s 273Socket link. 274.It Sy p 275FIFO. 276.It Sy w 277Whiteout. 278.It Sy \- 279Regular file. 280.El 281.Pp 282The next three fields 283are three characters each: 284owner permissions, 285group permissions, and 286other permissions. 287Each field has three character positions: 288.Bl -enum -offset indent 289.It 290If 291.Sy r , 292the file is readable; if 293.Sy \- , 294it is not readable. 295.It 296If 297.Sy w , 298the file is writable; if 299.Sy \- , 300it is not writable. 301.It 302The first of the following that applies: 303.Bl -tag -width 4n -offset indent 304.It Sy S 305If in the owner permissions, the file is not executable and 306set-user-ID mode is set. 307If in the group permissions, the file is not executable 308and set-group-ID mode is set. 309.It Sy s 310If in the owner permissions, the file is executable 311and set-user-ID mode is set. 312If in the group permissions, the file is executable 313and setgroup-ID mode is set. 314.It Sy x 315The file is executable or the directory is 316searchable. 317.It Sy \- 318The file is neither readable, writable, executable, 319nor set-user-ID nor set-group-ID mode, nor sticky. (See below.) 320.El 321.Pp 322These next two apply only to the third character in the last group 323(other permissions). 324.Bl -tag -width 4n -offset indent 325.It Sy T 326The sticky bit is set 327(mode 328.Li 1000 ) , 329but not execute or search permission. (See 330.Xr chmod 1 331or 332.Xr sticky 8 . ) 333.It Sy t 334The sticky bit is set (mode 335.Li 1000 ) , 336and is searchable or executable. 337(See 338.Xr chmod 1 339or 340.Xr sticky 8 . ) 341.El 342.El 343.Pp 344The number of bytes displayed for a directory is a function of the 345number of 346.Xr dirent 5 347structures in the directory, not all of which may be allocated to 348any existing file. 349.Sh EXIT STATUS 350The 351.Nm 352utility exits 0 on success, and \*[Gt]0 if an error occurs. 353.Sh ENVIRONMENT 354The following environment variables affect the execution of 355.Nm "" : 356.Bl -tag -width BLOCKSIZE 357.It Ev BLOCKSIZE 358If the environment variable 359.Ev BLOCKSIZE 360is set, and the 361.Fl k 362option is not specified, the block counts 363(see 364.Fl s ) 365will be displayed in units of that size block. 366.It Ev COLUMNS 367If this variable contains a string representing a 368decimal integer, it is used as the 369column position width for displaying 370multiple-text-column output. 371The 372.Nm 373utility calculates how 374many pathname text columns to display 375based on the width provided. 376(See 377.Fl C . ) 378.It Ev TZ 379The timezone to use when displaying dates. 380See 381.Xr environ 7 382for more information. 383.El 384.Sh COMPATIBILITY 385The group field is now automatically included in the long listing for 386files in order to be compatible with the 387.St -p1003.2 388specification. 389.Sh SEE ALSO 390.Xr chflags 1 , 391.Xr chmod 1 , 392.Xr stat 2 , 393.Xr getbsize 3 , 394.Xr dir 5 , 395.Xr symlink 7 , 396.Xr sticky 8 397.Sh STANDARDS 398The 399.Nm 400utility is expected to be a superset of the 401.St -p1003.2 402specification. 403.Sh HISTORY 404An 405.Nm 406utility appeared in 407.At v5 . 408