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