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