1.\" $OpenBSD: ls.1,v 1.76 2016/03/17 07:18:33 jmc Exp $ 2.\" $NetBSD: ls.1,v 1.14 1995/12/05 02:44:01 jtc Exp $ 3.\" 4.\" Copyright (c) 1980, 1990, 1991, 1993, 1994 5.\" The Regents of the University of California. All rights reserved. 6.\" 7.\" This code is derived from software contributed to Berkeley by 8.\" the Institute of Electrical and Electronics Engineers, Inc. 9.\" 10.\" Redistribution and use in source and binary forms, with or without 11.\" modification, are permitted provided that the following conditions 12.\" are met: 13.\" 1. Redistributions of source code must retain the above copyright 14.\" notice, this list of conditions and the following disclaimer. 15.\" 2. Redistributions in binary form must reproduce the above copyright 16.\" notice, this list of conditions and the following disclaimer in the 17.\" documentation and/or other materials provided with the distribution. 18.\" 3. Neither the name of the University nor the names of its contributors 19.\" may be used to endorse or promote products derived from this software 20.\" without specific prior written permission. 21.\" 22.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 23.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 24.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 25.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 26.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 27.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 28.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 29.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 30.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 31.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 32.\" SUCH DAMAGE. 33.\" 34.\" @(#)ls.1 8.7 (Berkeley) 7/29/94 35.\" 36.Dd $Mdocdate: March 17 2016 $ 37.Dt LS 1 38.Os 39.Sh NAME 40.Nm ls 41.Nd list directory contents 42.Sh SYNOPSIS 43.Nm ls 44.Op Fl 1AaCcdFfgHhikLlmnopqRrSsTtux 45.Op Ar 46.Sh DESCRIPTION 47For each operand that names a 48.Ar file 49of a type other than directory, 50.Nm 51displays its name as well as any requested, 52associated information. 53For each named directory, 54.Nm 55displays the names of files contained 56within that directory, as well as any requested, associated 57information. 58.Pp 59If no operands are given, the contents of the current 60directory are displayed. 61If more than one operand is given, 62non-directory operands are displayed first; directory 63and non-directory operands are sorted separately and in 64lexicographical order. 65By default, 66.Nm 67lists one entry per line to standard 68output; the exceptions are to terminals or when the 69.Fl C , 70.Fl m , 71or 72.Fl x 73options are specified. 74.Pp 75The options are as follows: 76.Bl -tag -width Ds 77.It Fl 1 78(The numeric digit 79.Dq one . ) 80Force output to be one entry per line. 81This is the default when 82output is not to a terminal. 83.It Fl A 84List all entries except for 85.Sq \&. 86and 87.Sq \&.. . 88Always set for the superuser. 89.It Fl a 90Include directory entries whose names begin with a 91dot 92.Pq Sq \&. . 93.It Fl C 94Force multi-column output; this is the default when output is to a terminal. 95.It Fl c 96Use time file's status was last changed instead of last modification 97time for sorting 98.Pq Fl t 99or printing 100.Pf ( Fl g , l , 101or 102.Fl n ) . 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 107Display a slash 108.Pq Sq / 109immediately after each pathname that is a directory, 110an asterisk 111.Pq Sq * 112after each that is executable, 113an at sign 114.Pq Sq @ 115after each symbolic link, 116an equal sign 117.Pq Sq = 118after each socket, 119and a vertical bar 120.Pq Sq \&| 121after each that is a FIFO. 122.It Fl f 123Output is not sorted. 124This option implies 125.Fl a . 126.It Fl g 127List in long format as in 128.Fl l , 129except that the owner is not printed. 130.It Fl H 131Follow symbolic links specified on the command line. 132This is the default behaviour when none of the 133.Fl d , F , 134or 135.Fl l 136options are specified. 137.It Fl h 138When used with a long format 139option, use unit suffixes: Byte, Kilobyte, Megabyte, Gigabyte, Terabyte, 140Petabyte, and Exabyte in order to reduce the number of digits to four or fewer 141using powers of 2 for sizes (K=1024, M=1048576, etc.). 142.It Fl i 143For each file, print its inode number. 144.It Fl k 145Modifies the 146.Fl s 147option, causing the sizes to be reported in kilobytes. 148Overrides any value specified by the 149.Ev BLOCKSIZE 150environment variable. 151.It Fl L 152If argument is a symbolic link, evaluate the file information and file type 153to be those of the file referenced by the link, and not the link itself; 154however, 155.Nm 156writes the name of the link itself and not the file referenced by the link. 157.It Fl l 158(The lowercase letter 159.Dq ell . ) 160List in long format (see below). 161A total sum of all file 162sizes is output on a line before the long listing. 163Output is one entry per line. 164.It Fl m 165Stream output format; list files across the page, separated by commas. 166.It Fl n 167List in long format as in 168.Fl l , 169but retain user and group IDs in a numeric format. 170The output of 171.Fl gn 172and 173.Fl ng 174is identical: 175a long listing with numerical group ID, 176and no numerical user ID. 177The output of 178.Fl ln 179and 180.Fl \&nl 181is identical: 182a long listing with numerical group and user ID. 183.It Fl o 184Include the file flags in a long format 185.Pf ( Fl g , l , 186or 187.Fl n ) 188output. 189.It Fl p 190Display a slash 191.Pq Sq / 192immediately after each pathname that is a directory. 193.It Fl q 194Force printing of non-graphic characters in file names as 195the character 196.Sq \&? ; 197this is the default when output is to a terminal. 198.It Fl R 199Recursively list subdirectories encountered. 200.It Fl r 201Reverse the order of the sort to get reverse 202lexicographical order or the smallest or oldest entries first. 203.It Fl S 204Sort by size, largest file first. 205.It Fl s 206Display the number of file system blocks actually used by each file, 207where partial units are rounded up to the next integer value. 208Blocks are 512 bytes unless overridden by the 209.Fl k 210flag or 211.Ev BLOCKSIZE 212environment variable. 213.It Fl T 214Display complete time information for the file, including 215month, day, hour, minute, second, and year. 216This option has no effect unless one of the long format 217.Pf ( Fl g , l , 218or 219.Fl n ) 220options is also specified. 221.It Fl t 222Sort by time modified (most recently modified 223first) before sorting the operands in lexicographical 224order. 225.It Fl u 226Use file's last access time 227instead of last modification time 228for sorting 229.Pq Fl t 230or printing 231.Pf ( Fl g , l , 232or 233.Fl n ) . 234.It Fl x 235Multi-column output sorted across the page rather than down the page. 236.El 237.Pp 238It is not an error to specify more than one of 239the following mutually exclusive options: 240.Fl 1 , 241.Fl C , 242.Fl g , 243.Fl l , 244.Fl m , 245.Fl n , 246and 247.Fl x ; 248and 249.Fl c , 250.Fl f , 251.Fl S , 252.Fl t , 253and 254.Fl u . 255Where more than one option is specified from the same 256mutually exclusive group, 257the last option given overrides the others, 258except that 259.Fl l 260always overrides 261.Fl g ; 262and 263.Fl f 264always overrides 265.Fl c , 266.Fl S , 267.Fl t , 268and 269.Fl u . 270.Ss The Long Format 271If the 272.Fl g , 273.Fl l , 274or 275.Fl n 276options are given, the following information 277is displayed for each file: 278mode, 279number of links, 280owner (though not for 281.Fl g ) , 282group, 283size in bytes, 284time of last modification 285.Pq Dq mmm dd HH:MM , 286and the pathname. 287In addition, for each directory whose contents are displayed, the first 288line displayed is the total number of blocks used by the files in the 289directory. 290Blocks are 512 bytes unless overridden by the 291.Fl k 292option or 293.Ev BLOCKSIZE 294environment variable. 295.Pp 296If the owner or group name is not a known user or group name, respectively, 297or the 298.Fl n 299option is given, the numeric ID is displayed. 300.Pp 301If the file is a character special or block special file, 302the major and minor device numbers for the file are displayed 303in the size field. 304.Pp 305If the 306.Fl T 307option is given, the time of last modification is displayed using the 308format 309.Dq mmm dd HH:MM:SS ccyy . 310.Pp 311If the file is a symbolic link, the pathname of the 312linked-to file is preceded by 313.Dq \-\*(Gt . 314.Pp 315The file mode printed under the 316.Fl g , 317.Fl l , 318or 319.Fl n 320options consists of the entry type, owner permissions, group permissions, 321and other permissions. 322The entry type character describes the type of file, as follows: 323.Pp 324.Bl -tag -width 4n -offset indent -compact 325.It Sy \- 326regular file 327.It Sy b 328block special file 329.It Sy c 330character special file 331.It Sy d 332directory 333.It Sy l 334symbolic link 335.It Sy p 336FIFO 337.It Sy s 338socket link 339.El 340.Pp 341The next three fields 342are three characters each: 343owner permissions, 344group permissions, and 345other permissions. 346Each field has three character positions: 347.Pp 348.Bl -enum -offset indent -compact 349.It 350If 351.Sy r , 352the file is readable; if 353.Sy \- , 354it is not readable. 355.It 356If 357.Sy w , 358the file is writable; if 359.Sy \- , 360it is not writable. 361.It 362The first of the following that applies: 363.Bl -tag -width 4n -offset indent 364.It Sy S 365If in the owner permissions, the file is not executable and 366set-user-ID mode is set. 367If in the group permissions, the file is not executable 368and set-group-ID mode is set. 369.It Sy s 370If in the owner permissions, the file is executable 371and set-user-ID mode is set. 372If in the group permissions, the file is executable 373and setgroup-ID mode is set. 374.It Sy x 375The file is executable or the directory is 376searchable. 377.It Sy \- 378The file is neither readable, writable, executable, 379nor set-user-ID, nor set-group-ID, nor sticky (see below). 380.El 381.Pp 382These next two apply only to the third character in the last group 383(other permissions): 384.Bl -tag -width 4n -offset indent 385.It Sy T 386The sticky bit is set 387(mode 388.Li 1000 ) , 389but neither executable nor searchable (see 390.Xr chmod 1 391or 392.Xr sticky 8 ) . 393.It Sy t 394The sticky bit is set (mode 395.Li 1000 ) , 396and is searchable or executable 397(see 398.Xr chmod 1 399or 400.Xr sticky 8 ) . 401.El 402.El 403.Pp 404In addition, if the 405.Fl o 406option is specified, the file flags (see 407.Xr chflags 1 ) 408are displayed as comma-separated strings in front of the file size, 409abbreviated as follows: 410.Pp 411.Bl -tag -width 8n -offset indent -compact 412.It \&- 413no flags 414.It arch 415archived 416.It nodump 417do not dump 418.It sappnd 419system append-only 420.It schg 421system immutable 422.It uappnd 423user append-only 424.It uchg 425user immutable 426.El 427.Sh ENVIRONMENT 428.Bl -tag -width BLOCKSIZE 429.It Ev BLOCKSIZE 430If the environment variable 431.Ev BLOCKSIZE 432is set, and the 433.Fl k 434option is not specified, the block counts 435(see 436.Fl s ) 437will be displayed in units of that size block. 438.It Ev COLUMNS 439If set to a positive integer, 440output is formatted to the given width in columns. 441Otherwise, 442.Nm 443defaults to the terminal width, or 80 columns if the output is not a terminal. 444.It Ev LC_CTYPE 445If set to a string ending in 446.Qq .UTF-8 , 447.Nm 448respects character display widths when columnating output. 449Otherwise, non-ASCII bytes are replaced by question marks. 450.It Ev TZ 451The time zone to use when displaying dates. 452See 453.Xr environ 7 454for more information. 455.El 456.Sh EXIT STATUS 457.Ex -std ls 458.Sh EXAMPLES 459List the contents of the current working directory in long format: 460.Pp 461.Dl $ ls -l 462.Pp 463In addition to listing the contents of the current working directory in 464long format, show inode numbers, file flags (see 465.Xr chflags 1 ) , 466and suffix each filename with a symbol representing its file type: 467.Pp 468.Dl $ ls -lioF 469.Pp 470List the files in 471.Pa /var/log , 472sorting the output such that the most recently modified entries are 473printed first: 474.Pp 475.Dl $ ls -lt /var/log 476.Sh SEE ALSO 477.Xr chflags 1 , 478.Xr chmod 1 , 479.Xr symlink 7 , 480.Xr sticky 8 481.Sh STANDARDS 482The 483.Nm 484utility is compliant with the 485.St -p1003.1-2008 486specification, 487except behaviour for the 488.Fl o 489flag differs. 490.Pp 491The flags 492.Op Fl hT , 493as well as the 494.Ev BLOCKSIZE 495environment variable, 496are extensions to that specification. 497.Pp 498The flags 499.Op Fl go 500are marked by 501.St -p1003.1-2008 502as being an X/Open System Interfaces option. 503.Pp 504Historically, the 505.Fl g 506flag was used to specify that the group field be included in long listings. 507The group field is now automatically included in the long listing for 508files and the meaning of the 509.Fl g 510flag has been changed in order to be compatible with the 511.St -p1003.1-2008 512specification. 513.Sh HISTORY 514An 515.Nm 516utility appeared in 517.At v3 . 518