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.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 3. All advertising materials mentioning features or use of this software 16.\" must display the following acknowledgement: 17.\" This product includes software developed by the University of 18.\" California, Berkeley and its contributors. 19.\" 4. Neither the name of the University nor the names of its contributors 20.\" may be used to endorse or promote products derived from this software 21.\" without specific prior written permission. 22.\" 23.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 24.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 25.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 26.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 27.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 28.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 29.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 30.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 31.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 32.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 33.\" SUCH DAMAGE. 34.\" 35.\" @(#)ls.1 8.7 (Berkeley) 7/29/94 36.\" $Id: ls.1,v 1.5 1996/08/29 18:05:56 wosch Exp $ 37.\" 38.Dd July 29, 1994 39.Dt LS 1 40.Os 41.Sh NAME 42.Nm ls 43.Nd list directory contents 44.Sh SYNOPSIS 45.Nm ls 46.Op Fl ACFLRTWacdfiloqrstu1 47.Op Ar file ... 48.Sh DESCRIPTION 49For each operand that names a 50.Ar file 51of a type other than 52directory, 53.Nm ls 54displays its name as well as any requested, 55associated information. 56For each operand that names a 57.Ar file 58of type directory, 59.Nm ls 60displays the names of files contained 61within that directory, as well as any requested, associated 62information. 63.Pp 64If no operands are given, the contents of the current 65directory are displayed. 66If more than one operand is given, 67non-directory operands are displayed first; directory 68and non-directory operands are sorted separately and in 69lexicographical order. 70.Pp 71The following options are available: 72.Bl -tag -width indent 73.It Fl A 74List all entries except for 75.Ql \&. 76and 77.Ql \&.. . 78Always set for the super-user. 79.It Fl C 80Force multi-column output; this is the default when output is to a terminal. 81.It Fl F 82Display a slash (/) immediately after each pathname 83that is a directory, an asterisk (*) after each that is 84executable, 85an at sign (@) after each symbolic link, 86an equals sign (=) after each socket, 87a percent sign (%) after each whiteout, 88and a vertical bar (|) after each that is a 89.Tn FIFO . 90.It Fl L 91If argument is a symbolic link, list the file or directory the link references 92rather than the link itself. 93.It Fl R 94Recursively list subdirectories encountered. 95.It Fl T 96Display complete time information for the file, including 97month, day, hour, minute, second, and year. 98.It Fl W 99Display whiteouts when scanning directories. (UNIMPLEMENTED) 100.It Fl a 101Include directory entries whose names begin with a 102dot (.). 103.It Fl c 104Use time when file status was last changed for sorting or printing. 105.It Fl d 106Directories are listed as plain files (not searched recursively) and 107symbolic links in the argument list are not indirected through. 108.It Fl f 109Output is not sorted. 110.It Fl i 111For each file, print the file's file serial number (inode number). 112.It Fl k 113If the 's' option is specified, print the file size allocation in kilobytes, 114not blocks. 115.It Fl l 116(The lowercase letter ``ell.'') List in long format. (See below.) 117If the output is to a terminal, a total sum for all the file 118sizes is output on a line before the long listing. 119.It Fl o 120Include the file flags in a long 121.Pq Fl l 122output 123.It Fl q 124Force printing of non-graphic characters in file names as 125the character `?'; this is the default when output is to a terminal. 126.It Fl r 127Reverse the order of the sort to get reverse 128lexicographical order or the oldest entries first. 129.It Fl s 130Display the number of file system blocks actually used by each file, in units 131of 512 bytes, where partial units are rounded up to the next integer value. 132If the output is to a terminal, a total sum for all the file 133sizes is output on a line before the listing. 134.It Fl t 135Sort by time modified (most recently modified 136first) before sorting the operands by lexicographical 137order. 138.It Fl u 139Use time of last access, 140instead of last modification 141of the file for sorting 142.Pq Fl t 143or printing 144.Pq Fl l . 145.It Fl \&1 146(The numeric digit ``one.'') Force output to be 147one entry per line. 148This is the default when 149output is not to a terminal. 150.El 151.Pp 152The 153.Fl 1 , 154.Fl C , 155and 156.Fl l 157options all override each other; the last one specified determines 158the format used. 159.Pp 160The 161.Fl c , 162and 163.Fl u 164options override each other; the last one specified determines 165the file time used. 166.Pp 167By default, 168.Nm ls 169lists one entry per line to standard 170output; the exceptions are to terminals or when the 171.Fl C 172option is specified. 173.Pp 174File information is displayed with one or more 175<blank>s separating the information associated with the 176.Fl i , 177.Fl s , 178and 179.Fl l 180options. 181.Ss The Long Format 182If the 183.Fl l 184option is given, the following information 185is displayed for each file: 186file mode, 187number of links, owner name, group name, 188number of bytes in the file, abbreviated 189month, day-of-month file was last modified, 190hour file last modified, minute file last 191modified, and the pathname. 192In addition, for each directory whose contents are displayed, the total 193number of 512-byte blocks used by the files in the directory is displayed 194on a line by itself immediately before the information for the files in the 195directory. 196.Pp 197If the owner or group names are not a known user or group name 198the numeric ID's are displayed. 199.Pp 200If the file is a character special or block special file, 201the major and minor device numbers for the file are displayed 202in the size field. If the file is a symbolic link the pathname of the 203linked-to file is preceded by 204.Dq \-> . 205.Pp 206The file mode printed under the -l option consists of the 207entry type, owner permissions, and group permissions. 208The entry type character describes the type of file, as 209follows: 210.Pp 211.Bl -tag -width 4n -offset indent -compact 212.It Sy b 213Block special file. 214.It Sy c 215Character special file. 216.It Sy d 217Directory. 218.It Sy l 219Symbolic link. 220.It Sy s 221Socket link. 222.It Sy p 223.Tn FIFO . 224.It Sy \- 225Regular file. 226.El 227.Pp 228The next three fields 229are three characters each: 230owner permissions, 231group permissions, and 232other permissions. 233Each field has three character positions: 234.Bl -enum -offset indent 235.It 236If 237.Sy r , 238the file is readable; if 239.Sy \- , 240it is not readable. 241.It 242If 243.Sy w , 244the file is writable; if 245.Sy \- , 246it is not writable. 247.It 248The first of the following that applies: 249.Bl -tag -width 4n -offset indent 250.It Sy S 251If in the owner permissions, the file is not executable and 252set-user-ID mode is set. 253If in the group permissions, the file is not executable 254and set-group-ID mode is set. 255.It Sy s 256If in the owner permissions, the file is executable 257and set-user-ID mode is set. 258If in the group permissions, the file is executable 259and setgroup-ID mode is set. 260.It Sy x 261The file is executable or the directory is 262searchable. 263.It Sy \- 264The file is neither readable, writeable, executable, 265nor set-user-ID nor set-group-ID mode, nor sticky. (See below.) 266.El 267.Pp 268These next two apply only to the third character in the last group 269(other permissions). 270.Bl -tag -width 4n -offset indent 271.It Sy T 272The sticky bit is set 273(mode 274.Li 1000 ) , 275but not execute or search permission. (See 276.Xr chmod 1 277or 278.Xr sticky 8 . ) 279.It Sy t 280The sticky bit is set (mode 281.Li 1000 ) , 282and is searchable or executable. 283(See 284.Xr chmod 1 285or 286.Xr sticky 8 . ) 287.El 288.El 289.Pp 290The 291.Nm ls 292utility exits 0 on success, and >0 if an error occurs. 293.Sh ENVIRONMENTAL VARIABLES 294The following environment variables affect the execution of 295.Nm ls : 296.Bl -tag -width BLOCKSIZE 297.It Ev BLOCKSIZE 298If the environmental variable 299.Ev BLOCKSIZE 300is set, the block counts 301(see 302.Fl s ) 303will be displayed in units of that size block. 304.It COLUMNS 305If this variable contains a string representing a 306decimal integer, it is used as the 307column position width for displaying 308multiple-text-column output. 309The 310.Nm ls 311utility calculates how 312many pathname text columns to display 313based on the width provided. 314(See 315.Fl C . ) 316.It Ev TZ 317The timezone to use when displaying dates. 318See 319.Xr environ 7 320for more information. 321.El 322.Sh COMPATIBILITY 323The group field is now automatically included in the long listing for 324files in order to be compatible with the 325.St -p1003.2 326specification. 327.Sh SEE ALSO 328.Xr chmod 1 , 329.Xr symlink 7 , 330.Xr sticky 8 331.Sh HISTORY 332An 333.Nm ls 334command appeared in 335.At v1 . 336.Sh STANDARDS 337The 338.Nm ls 339function is expected to be a superset of the 340.St -p1003.2 341specification. 342