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