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