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: ls.1,v 1.4 1995/09/26 08:48:09 mpp Exp $ 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, 85an at sign (@) after each symbolic link, 86an equals sign (=) after each socket, 87and a vertical bar (|) after each that is a 88.Tn FIFO . 89.It Fl L 90If argument is a symbolic link, list the file or directory the link references 91rather than the link itself. 92.It Fl R 93Recursively list subdirectories encountered. 94.It Fl T 95Display complete time information for the file, including 96month, day, hour, minute, second, and year. 97.It Fl a 98Include directory entries whose names begin with a 99dot (.). 100.It Fl c 101Use time when file status was last changed for sorting or printing. 102.It Fl d 103Directories are listed as plain files (not searched recursively) and 104symbolic links in the argument list are not indirected through. 105.It Fl f 106Output is not sorted. 107.It Fl i 108For each file, print the file's file serial number (inode number). 109.It Fl k 110If the 's' option is specified, print the file size allocation in kilobytes, 111not blocks. 112.It Fl l 113(The lowercase letter ``ell.'') List in long format. (See below.) 114If the output is to a terminal, a total sum for all the file 115sizes is output on a line before the long listing. 116.It Fl o 117Include the file flags in a long 118.Pq Fl l 119output 120.It Fl q 121Force printing of non-graphic characters in file names as 122the character `?'; this is the default when output is to a terminal. 123.It Fl r 124Reverse the order of the sort to get reverse 125lexicographical order or the oldest entries first. 126.It Fl s 127Display the number of file system blocks actually used by each file, in units 128of 512 bytes, where partial units are rounded up to the next integer value. 129If the output is to a terminal, a total sum for all the file 130sizes is output on a line before the listing. 131.It Fl t 132Sort by time modified (most recently modified 133first) before sorting the operands by lexicographical 134order. 135.It Fl u 136Use time of last access, 137instead of last modification 138of the file for sorting 139.Pq Fl t 140or printing 141.Pq Fl l . 142.It Fl \&1 143(The numeric digit ``one.'') Force output to be 144one entry per line. 145This is the default when 146output is not to a terminal. 147.El 148.Pp 149The 150.Fl 1 , 151.Fl C , 152and 153.Fl l 154options all override each other; the last one specified determines 155the format used. 156.Pp 157The 158.Fl c , 159and 160.Fl u 161options override each other; the last one specified determines 162the file time used. 163.Pp 164By default, 165.Nm ls 166lists one entry per line to standard 167output; the exceptions are to terminals or when the 168.Fl C 169option is specified. 170.Pp 171File information is displayed with one or more 172<blank>s separating the information associated with the 173.Fl i , 174.Fl s , 175and 176.Fl l 177options. 178.Ss The Long Format 179If the 180.Fl l 181option is given, the following information 182is displayed for each file: 183file mode, 184number of links, owner name, group name, 185number of bytes in the file, abbreviated 186month, day-of-month file was last modified, 187hour file last modified, minute file last 188modified, and the pathname. 189In addition, for each directory whose contents are displayed, the total 190number of 512-byte blocks used by the files in the directory is displayed 191on a line by itself immediately before the information for the files in the 192directory. 193.Pp 194If the owner or group names are not a known user or group name 195the numeric ID's are displayed. 196.Pp 197If the file is a character special or block special file, 198the major and minor device numbers for the file are displayed 199in the size field. If the file is a symbolic link the pathname of the 200linked-to file is preceded by 201.Dq \-> . 202.Pp 203The file mode printed under the -l option consists of the 204entry type, owner permissions, and group permissions. 205The entry type character describes the type of file, as 206follows: 207.Pp 208.Bl -tag -width 4n -offset indent -compact 209.It Sy b 210Block special file. 211.It Sy c 212Character special file. 213.It Sy d 214Directory. 215.It Sy l 216Symbolic link. 217.It Sy s 218Socket link. 219.It Sy p 220.Tn FIFO . 221.It Sy \- 222Regular file. 223.El 224.Pp 225The next three fields 226are three characters each: 227owner permissions, 228group permissions, and 229other permissions. 230Each field has three character positions: 231.Bl -enum -offset indent 232.It 233If 234.Sy r , 235the file is readable; if 236.Sy \- , 237it is not readable. 238.It 239If 240.Sy w , 241the file is writable; if 242.Sy \- , 243it is not writable. 244.It 245The first of the following that applies: 246.Bl -tag -width 4n -offset indent 247.It Sy S 248If in the owner permissions, the file is not executable and 249set-user-ID mode is set. 250If in the group permissions, the file is not executable 251and set-group-ID mode is set. 252.It Sy s 253If in the owner permissions, the file is executable 254and set-user-ID mode is set. 255If in the group permissions, the file is executable 256and setgroup-ID mode is set. 257.It Sy x 258The file is executable or the directory is 259searchable. 260.It Sy \- 261The file is neither readable, writeable, executable, 262nor set-user-ID nor set-group-ID mode, nor sticky. (See below.) 263.El 264.Pp 265These next two apply only to the third character in the last group 266(other permissions). 267.Bl -tag -width 4n -offset indent 268.It Sy T 269The sticky bit is set 270(mode 271.Li 1000 ) , 272but not execute or search permission. (See 273.Xr chmod 1 274or 275.Xr sticky 8 . ) 276.It Sy t 277The sticky bit is set (mode 278.Li 1000 ) , 279and is searchable or executable. 280(See 281.Xr chmod 1 282or 283.Xr sticky 8 . ) 284.El 285.El 286.Pp 287The 288.Nm ls 289utility exits 0 on success, and >0 if an error occurs. 290.Sh ENVIRONMENTAL VARIABLES 291The following environment variables affect the execution of 292.Nm ls : 293.Bl -tag -width BLOCKSIZE 294.It Ev BLOCKSIZE 295If the environmental variable 296.Ev BLOCKSIZE 297is set, the block counts 298(see 299.Fl s ) 300will be displayed in units of that size block. 301.It COLUMNS 302If this variable contains a string representing a 303decimal integer, it is used as the 304column position width for displaying 305multiple-text-column output. 306The 307.Nm ls 308utility calculates how 309many pathname text columns to display 310based on the width provided. 311(See 312.Fl C . ) 313.It Ev TZ 314The timezone to use when displaying dates. 315See 316.Xr environ 7 317for more information. 318.El 319.Sh COMPATIBILITY 320The group field is now automatically included in the long listing for 321files in order to be compatible with the 322.St -p1003.2 323specification. 324.Sh SEE ALSO 325.Xr chmod 1 , 326.Xr symlink 7 , 327.Xr sticky 8 328.Sh HISTORY 329An 330.Nm ls 331command appeared in 332.At v1 . 333.Sh STANDARDS 334The 335.Nm ls 336function is expected to be a superset of the 337.St -p1003.2 338specification. 339