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 acknowledgment: 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.\" $FreeBSD$ 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 ABCFHLPRTWabcdfgiklnoqrstu1 47.Op Ar file ... 48.Sh DESCRIPTION 49For each operand that names a 50.Ar file 51of a type other than 52directory, 53.Nm 54displays its name as well as any requested, 55associated information. 56For each operand that names a 57.Ar file 58of type directory, 59.Nm 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 B 80Force printing of non-graphic characters in file names as \\xxx, 81where xxx is the numeric value of the character in octal. 82.It Fl C 83Force multi-column output; this is the default when output is to a terminal. 84.It Fl F 85Display a slash (/) immediately after each pathname 86that is a directory, an asterisk (*) after each that is 87executable, 88an at sign (@) after each symbolic link, 89an equals sign (=) after each socket, 90a percent sign (%) after each whiteout, 91and a vertical bar (|) after each that is a 92.Tn FIFO . 93.It Fl H 94Symbolic links on the command line are followed. This option is assumed if 95none of the 96.Fl F , 97.Fl d , 98or 99.Fl l 100options are specified. 101.It Fl L 102If argument is a symbolic link, list the file or directory the link references 103rather than the link itself. This option cancels the 104.Fl P 105option. 106.It Fl P 107If argument is a symbolic link, list the link itself rather than the 108object the link references. This option cancels the 109.Fl H 110and 111.Fl L 112options. 113.It Fl R 114Recursively list subdirectories encountered. 115.It Fl T 116Display complete time information for the file, including 117month, day, hour, minute, second, and year. 118.It Fl W 119Display whiteouts when scanning directories. 120.It Fl a 121Include directory entries whose names begin with a 122dot (.). 123.It Fl b 124As 125.Fl B , 126but use C escape codes whenever possible. 127.It Fl c 128Use time when file status was last changed for sorting or printing. 129.It Fl d 130Directories are listed as plain files (not searched recursively). 131.It Fl f 132Output is not sorted. 133.It Fl g 134This option is deprecated and is only available for compatibility 135with 136.Bx 4.3 ; 137it was used to display the group name in the long 138.Pq Fl l 139format output. 140.It Fl i 141For each file, print the file's file serial number (inode number). 142.It Fl k 143If the 144.Fl s 145option is specified, print the file size allocation in kilobytes, 146not blocks. This option overrides the environment variable BLOCKSIZE. 147.It Fl l 148(The lowercase letter ``ell.'') List in long format. (See below.) 149If the output is to a terminal, a total sum for all the file 150sizes is output on a line before the long listing. 151.It Fl n 152Display user and group IDs numerically rather than converting to a user 153or group name in a long 154.Pq Fl l 155output. 156.It Fl o 157Include the file flags in a long 158.Pq Fl l 159output. 160.It Fl q 161Force printing of non-graphic characters in file names as 162the character `?'; this is the default when output is to a terminal. 163.It Fl r 164Reverse the order of the sort to get reverse 165lexicographical order or the oldest entries first. 166.It Fl s 167Display the number of file system blocks actually used by each file, in units 168of 512 bytes, where partial units are rounded up to the next integer value. 169If the output is to a terminal, a total sum for all the file 170sizes is output on a line before the listing. The environment variable 171BLOCKSIZE overrides the unit size of 512 bytes. 172.It Fl t 173Sort by time modified (most recently modified 174first) before sorting the operands by lexicographical 175order. 176.It Fl u 177Use time of last access, 178instead of last modification 179of the file for sorting 180.Pq Fl t 181or printing 182.Pq Fl l . 183.It Fl \&1 184(The numeric digit ``one.'') Force output to be 185one entry per line. 186This is the default when 187output is not to a terminal. 188.El 189.Pp 190The 191.Fl 1 , 192.Fl C , 193and 194.Fl l 195options all override each other; the last one specified determines 196the format used. 197.Pp 198The 199.Fl c 200and 201.Fl u 202options override each other; the last one specified determines 203the file time used. 204.Pp 205The 206.Fl B , 207.Fl b 208and 209.Fl q 210options all override each other; the last one specified determines 211the format used for non-printable characters. 212.Pp 213The 214.Fl H, 215.Fl L 216and 217.Fl P 218options all override each other (either partially or fully); they 219are applied in the order specified. 220.Pp 221By default, 222.Nm 223lists one entry per line to standard 224output; the exceptions are to terminals or when the 225.Fl C 226option is specified. 227.Pp 228File information is displayed with one or more 229<blank>s separating the information associated with the 230.Fl i , 231.Fl s , 232and 233.Fl l 234options. 235.Ss The Long Format 236If the 237.Fl l 238option is given, the following information 239is displayed for each file: 240file mode, 241number of links, owner name, group name, 242number of bytes in the file, abbreviated 243month, day-of-month file was last modified, 244hour file last modified, minute file last 245modified, and the pathname. 246In addition, for each directory whose contents are displayed, the total 247number of 512-byte blocks used by the files in the directory is displayed 248on a line by itself immediately before the information for the files in the 249directory. 250.Pp 251If the modification time of the file is more than 6 months 252in the past or future, then the year of the last modification 253is displayed in place of the hour and minute fields. 254.Pp 255If the owner or group names are not a known user or group name, 256or the 257.Fl n 258option is given, 259the numeric ID's are displayed. 260.Pp 261If the file is a character special or block special file, 262the major and minor device numbers for the file are displayed 263in the size field. If the file is a symbolic link the pathname of the 264linked-to file is preceded by 265.Dq \-> . 266.Pp 267The file mode printed under the 268.Fl l 269option consists of the 270entry type, owner permissions, and group permissions. 271The entry type character describes the type of file, as 272follows: 273.Pp 274.Bl -tag -width 4n -offset indent -compact 275.It Sy b 276Block special file. 277.It Sy c 278Character special file. 279.It Sy d 280Directory. 281.It Sy l 282Symbolic link. 283.It Sy s 284Socket link. 285.It Sy p 286.Tn FIFO . 287.It Sy \- 288Regular file. 289.El 290.Pp 291The next three fields 292are three characters each: 293owner permissions, 294group permissions, and 295other permissions. 296Each field has three character positions: 297.Bl -enum -offset indent 298.It 299If 300.Sy r , 301the file is readable; if 302.Sy \- , 303it is not readable. 304.It 305If 306.Sy w , 307the file is writable; if 308.Sy \- , 309it is not writable. 310.It 311The first of the following that applies: 312.Bl -tag -width 4n -offset indent 313.It Sy S 314If in the owner permissions, the file is not executable and 315set-user-ID mode is set. 316If in the group permissions, the file is not executable 317and set-group-ID mode is set. 318.It Sy s 319If in the owner permissions, the file is executable 320and set-user-ID mode is set. 321If in the group permissions, the file is executable 322and setgroup-ID mode is set. 323.It Sy x 324The file is executable or the directory is 325searchable. 326.It Sy \- 327The file is neither readable, writable, executable, 328nor set-user-ID nor set-group-ID mode, nor sticky. (See below.) 329.El 330.Pp 331These next two apply only to the third character in the last group 332(other permissions). 333.Bl -tag -width 4n -offset indent 334.It Sy T 335The sticky bit is set 336(mode 337.Li 1000 ) , 338but not execute or search permission. (See 339.Xr chmod 1 340or 341.Xr sticky 8 . ) 342.It Sy t 343The sticky bit is set (mode 344.Li 1000 ) , 345and is searchable or executable. 346(See 347.Xr chmod 1 348or 349.Xr sticky 8 . ) 350.El 351.El 352.Sh DIAGNOSTICS 353The 354.Nm 355utility exits 0 on success, and >0 if an error occurs. 356.Sh ENVIRONMENT 357The following environment variables affect the execution of 358.Nm Ns : 359.Bl -tag -width BLOCKSIZE 360.It Ev BLOCKSIZE 361If the environment variable 362.Ev BLOCKSIZE 363is set, the block counts 364(see 365.Fl s ) 366will be displayed in units of that size block. 367.It COLUMNS 368If this variable contains a string representing a 369decimal integer, it is used as the 370column position width for displaying 371multiple-text-column output. 372The 373.Nm 374utility calculates how 375many pathname text columns to display 376based on the width provided. 377(See 378.Fl C . ) 379.It Ev TZ 380The timezone to use when displaying dates. 381See 382.Xr environ 7 383for more information. 384.It Ev LS_COLWIDTHS 385If this variable is set, it is considered to be a 386colon-delimited list of minimum column widths. Unreasonable 387and insufficient widths are ignored (thus zero signifies 388a dynamically sized column). Not all 389columns have changeable widths. The fields are, 390in order: inode, block count, number of links, user name, 391group name, flags, file size, file name. 392.El 393.Sh COMPATIBILITY 394The group field is now automatically included in the long listing for 395files in order to be compatible with the 396.St -p1003.2 397specification. 398.Sh SEE ALSO 399.Xr chflags 1 , 400.Xr chmod 1 , 401.Xr symlink 7 , 402.Xr sticky 8 403.Sh HISTORY 404An 405.Nm 406command appeared in 407.At v1 . 408.Sh STANDARDS 409The 410.Nm 411function is expected to be a superset of the 412.St -p1003.2 413specification. 414.Sh BUGS 415To maintain backward compatibility, the relationships between the many 416options is quite complex. 417