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