1.\" Copyright 1980, 1990, 1991 The Regents of the University of California. 2.\" All rights reserved. 3.\" 4.\" %sccs.include.redist.roff% 5.\" 6.\" @(#)ls.1 6.17 (Berkeley) 04/26/91 7.\" 8.Dd 9.Dt LS 1 10.Os 11.Sh NAME 12.Nm ls 13.Nd list directory contents 14.Sh SYNOPSIS 15.Nm ls 16.Op Fl CFRacdilqrstu1 17.Op Ar file ... 18.Sh DESCRIPTION 19For each operand that names a 20.Ar file 21of a type other than 22directory, 23.Nm ls 24displays its name as well as any requested, 25associated information. 26For each operand that names a 27.Ar file 28of type directory, 29.Nm ls 30displays the names of files contained 31within that directory, as well as any requested, associated 32information. 33.Pp 34If no operands are given, the contents of the current 35directory are displayed. 36If more than one operand is given, 37non-directory operands are displayed first; directory 38and non-directory operands are sorted separately and in 39lexicographical order. 40.Pp 41The following options are available: 42.Bl -tag -width indent 43.It Fl A 44List all entries except for 45.Ql \&. 46and 47.Ql \&.. . 48Always set for the super-user. 49.It Fl C 50Force multi-column output; this is the default when output is to a terminal. 51.It Fl F 52Display a slash (/) immediately after each pathname 53that is a directory, an asterisk (*) after each that is 54executable, 55and an at sign (@) after each symbolic link. 56.\"and a vertical bar (|) after 57.\"each that is a 58.\".Tn FIFO . 59.It Fl L 60If argument is a symbolic link, list the file or directory the link references 61rather than the link itself. 62.It Fl R 63Recursively list subdirectories encountered. 64.It Fl T 65Display complete time information for the file, including 66month, day, hour, minute, second, and year. 67.It Fl a 68Include directory entries whose names begin with a 69dot (.). 70.It Fl c 71Use time when file status was last changed for sorting or printing. 72.It Fl d 73Directories are listed as plain files (not searched recursively). 74.It Fl f 75Output is not sorted. 76.It Fl g 77Include the group ownership of the file in a long 78.Pq Fl l 79output 80.Pq Fl lg . 81If the group is not a known group name, the numeric ID 82is printed. 83.It Fl i 84For each file, print the file's file serial number (inode number). 85.It Fl k 86Modifies the 87.Fl s 88option, causing the sizes to be reported in kilobytes. 89.It Fl l 90(The lowercase letter ``ell.'') List in long format. (See below.) 91If the output is to a terminal, a total sum for all the file 92sizes is output on a line before the long listing. 93.It Fl q 94Force printing of non-graphic characters in file names as 95the character `?'; this is the default when output is to a terminal. 96.It Fl r 97Reverse the order of the sort to get reverse 98lexicographical order or the oldest entries first. 99.It Fl s 100Display the number of file system bytes actually 101used by each file, in units of 512, where partial 102units are rounded up to the next integer value. 103If the output is to a terminal, a total sum for all the file 104sizes is output on a line before the listing. 105.It Fl t 106Sort by time modified (most recently modified 107first) before sorting the operands by lexicographical 108order. 109.It Fl u 110Use time of last access, 111instead of last modification 112of the file for sorting 113.Pq Fl t 114or printing 115.Pq Fl l . 116.It Fl \&1 117(The numeric digit ``one.'') Force output to be 118one entry per line. 119This is the default when 120output is not to a terminal. 121.El 122.Pp 123The 124.Fl 1 , 125.Fl C , 126and 127.Fl l 128options all override each other; the last one specified determines 129the format used. 130.Pp 131The 132.Fl c , 133and 134.Fl u 135options override each other; the last one specified determines 136the file time used. 137.Pp 138By default, 139.Nm ls 140lists one entry per line to standard 141output; the exceptions are to terminals or when the 142.Fl C 143option is specified. 144.Pp 145File information is displayed with one or more 146<blank>s separating the information associated with the 147.Fl i , 148.Fl s , 149and 150.Fl l 151options. 152.Ss The Long Format 153If the 154.Fl l 155option is given, the following information 156is be displayed: 157file mode, 158number of links, owner name, 159.\" group name, 160number of bytes in the file, abbreviated 161month, day-of-month file was last modified, 162hour file last modified, minute file last 163modified, and the pathname. 164.Pp 165If the owner name is not a known user name 166the numeric ID is displayed. 167.Pp 168If the file is a character special or block special file, 169the major and minor device numbers for the file are displayed 170in the size field. If the file is a symbolic link the pathname of the 171linked-to file is preceded by 172.Dq \-> . 173.Pp 174The file mode printed under the -l option consists of the 175the entry type, owner permissions, and group permissions. 176The entry type character describes the type of file, as 177follows: 178.Pp 179.Bl -tag -width 4n -offset indent -compact 180.It Sy b 181Block special file. 182.It Sy c 183Character special file. 184.It Sy d 185Directory. 186.It Sy l 187Symbolic link. 188.It Sy s 189Socket link. 190.\" .It Sy p 191.\" .Tn FIFO . 192.It Sy \- 193Regular file. 194.El 195.Pp 196The next three fields 197are three characters each: 198owner permissions, 199group permissions, and 200other permissions. 201Each field has three character positions: 202.Bl -enum -offset indent 203.It 204If 205.Sy r , 206the file is readable; if 207.Sy \- , 208it is not readable. 209.It 210If 211.Sy w , 212the file is writable; if 213.Sy \- , 214it is not writable. 215.It 216The first of the following that applies: 217.Bl -tag -width 4n -offset indent 218.It Sy S 219If in the owner permissions, the file is not executable and 220set-user-ID mode is set. 221If in the group permissions, the file is not executable 222and set-group-ID mode is set. 223.It Sy s 224If in the owner permissions, the file is executable 225and set-user-ID mode is set. 226If in the group permissions, the file is executable 227and setgroup-ID mode is set. 228.It Sy x 229The file is executable or the directory is 230searchable. 231.It Sy \- 232The file is neither readable, writeable, exectutable, 233or set-user-ID or set-group-ID mode nor sticky. (See below.) 234.El 235.Pp 236These next two apply only to the third character in the last group 237(other permissions). 238.Bl -tag -width 4n -offset indent 239.It Sy T 240The sticky bit is set 241(mode 242.Li 1000 ) , 243but not execute or search permission. (See 244.Xr chmod 1 245or 246.Xr sticky 8 . ) 247.It Sy t 248The sticky bit is set (mode 249.Li 1000 ) , 250and is searcheable or executable. 251(See 252.Xr chmod 1 253or 254.Xr sticky 8 . ) 255.El 256.El 257.Pp 258The 259.Nm ls 260utility exits 0 on success, and >0 if an error occurs. 261.Sh ENVIRONMENT 262The following environment variables affect the execution of 263.Nm ls : 264.Bl -tag -width COLUMNS 265.It COLUMNS 266If this variable contains a string representing a 267decimal integer, it is used as the 268column position width for displaying 269multiple-text-column output. 270The 271.Nm ls 272utility calculates how 273many pathname text columns to display 274based on the width provided. 275(See 276.Fl C . ) 277.El 278.Sh SEE ALSO 279.Xr chmod 1 , 280.Xr sticky 8 281.Sh HISTORY 282A 283.Nm ls 284command appeared in 285.At v6 . 286.\" .Sh STANDARDS 287.\" .The 288.\" .Nm ls 289.\" function is expected to be 290.\" .Tn POSIX 291.\" 1003.2 compatible. 292