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