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