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. Neither the name of the University nor the names of its contributors 16.\" may be used to endorse or promote products derived from this software 17.\" without specific prior written permission. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 22.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 29.\" SUCH DAMAGE. 30.\" 31.\" @(#)ls.1 8.7 (Berkeley) 7/29/94 32.\" $FreeBSD: src/bin/ls/ls.1,v 1.86 2005/02/13 22:25:09 ru Exp $ 33.\" 34.Dd December 8, 2015 35.Dt LS 1 36.Os 37.Sh NAME 38.Nm ls 39.Nd list directory contents 40.Sh SYNOPSIS 41.Nm 42.Op Fl ABCFGHILPRTWabcdfghiklmnopqrstuwxy1 43.Op Ar 44.Sh DESCRIPTION 45For each operand that names a 46.Ar file 47of a type other than 48directory, 49.Nm 50displays its name as well as any requested, 51associated information. 52For each operand that names a 53.Ar file 54of type directory, 55.Nm 56displays the names of files contained 57within that directory, as well as any requested, associated 58information. 59.Pp 60If no operands are given, the contents of the current 61directory are displayed. 62If more than one operand is given, 63non-directory operands are displayed first; directory 64and non-directory operands are sorted separately and in 65lexicographical order. 66.Pp 67The following options are available: 68.Bl -tag -width indent 69.It Fl A 70List all entries, including dot files, except for dot and dot-dot. 71Always set for the super-user, but may be turned 72off with 73.Fl I . 74.It Fl B 75Force printing of non-printable characters (as defined by 76.Xr ctype 3 77and current locale settings) in file names as 78.Li \e Ns Va xxx , 79where 80.Va xxx 81is 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 86.Pq Ql / 87immediately after each pathname that is a directory, 88an asterisk 89.Pq Ql * 90after each that is executable, 91an at sign 92.Pq Ql @ 93after each symbolic link, 94an equals sign 95.Pq Ql = 96after each socket, 97a percent sign 98.Pq Ql % 99after each whiteout, 100and a vertical bar 101.Pq Ql \&| 102after each that is a 103.Tn FIFO . 104.It Fl G 105Enable colorized output. 106This option is equivalent to defining 107.Ev CLICOLOR 108in the environment. 109(See below.) 110.It Fl H 111Symbolic links on the command line are followed. 112This option is assumed if 113none of the 114.Fl F , d , 115or 116.Fl l 117options are specified. 118.It Fl I 119This turns off the listing of dot files. 120Dot files are listed by default when 121.Nm 122is run as root. 123Note that the 124.Fl I 125and 126.Fl A 127options will override each other. 128.It Fl L 129If argument is a symbolic link, list the file or directory the link references 130rather than the link itself. 131This option cancels the 132.Fl P 133option. 134.It Fl P 135If argument is a symbolic link, list the link itself rather than the 136object the link references. 137This option cancels the 138.Fl H 139and 140.Fl L 141options. 142.It Fl R 143Recursively list subdirectories encountered. 144.It Fl S 145Sort by size (largest file first) before sorting the operands in 146lexicographical order. 147.It Fl T 148When used with the 149.Fl l 150(lowercase letter 151.Dq ell ) 152option, display complete time information for the file, including 153month, day, hour, minute, second, and year (named locales use the 154ISO 8601 extended format). 155.It Fl W 156Display whiteouts when scanning directories. 157.It Fl a 158Include directory entries whose names begin with a 159dot 160.Pq Pa \&. . 161.It Fl b 162As 163.Fl B , 164but use 165.Tn C 166escape codes whenever possible. 167.It Fl c 168Use time when file status was last changed for sorting or printing. 169.It Fl d 170Directories are listed as plain files (not searched recursively). 171.It Fl f 172Output is not sorted. 173This option implies 174.Fl a . 175.It Fl g 176This option is deprecated and is only available for compatibility 177with 178.Bx 4.3 ; 179it was used to display the group name in the long 180.Pq Fl l 181format output. 182.It Fl h 183When used with the 184.Fl l 185option, use unit suffixes: Byte, Kilobyte, Megabyte, Gigabyte, Terabyte 186and Petabyte in order to reduce the number of digits to four or fewer 187using base 2 for sizes. 188.It Fl i 189For each file, print the file's file serial number (inode number). 190.It Fl k 191If the 192.Fl s 193option is specified, print the file size allocation in kilobytes, 194not blocks. 195This option overrides the environment variable 196.Ev BLOCKSIZE . 197Note that 198.Fl k 199is mutually exclusive to 200.Fl h , 201and later 202.Fl k 203will nullify earlier 204.Fl h . 205.It Fl l 206(The lowercase letter 207.Dq ell . ) 208List in long format. 209(See below.) 210A total sum (in blocks, see the 211.Fl s 212option for the block size unit) for all the file 213sizes is output on a line before the long listing. 214.It Fl m 215Stream output format; list files across the page, separated by commas. 216.It Fl n 217Display user and group IDs numerically rather than converting to a user 218or group name in a long 219.Pq Fl l 220output. 221.It Fl o 222Include the file flags in a long 223.Pq Fl l 224output. 225.It Fl p 226Write a slash 227.Pq Ql / 228after each filename if that file is a directory. 229.It Fl q 230Force printing of non-graphic characters in file names as 231the character 232.Ql \&? ; 233this is the default when output is to a terminal. 234.It Fl r 235Reverse the order of the sort to get reverse 236lexicographical order or the oldest entries first. 237.It Fl s 238Display the number of file system blocks actually used by each file, in units 239of 512 bytes, where partial units are rounded up to the next integer value. 240A total sum for all the file 241sizes is output on a line before the listing. 242The environment variable 243.Ev BLOCKSIZE 244overrides the unit size of 512 bytes. 245.It Fl t 246Sort by time modified (most recently modified 247first) before sorting the operands by lexicographical 248order. 249.It Fl u 250Use time of last access, 251instead of last modification 252of the file for sorting 253.Pq Fl t 254or printing 255.Pq Fl l . 256.It Fl w 257Force raw printing of non-printable characters. 258This is the default 259when output is not to a terminal. 260.It Fl x 261The same as 262.Fl C , 263except that the multi-column output is produced with entries sorted 264across, rather than down, the columns. 265.It Fl y 266Include the FSMID field in a long 267.Pq Fl l 268output. 269.It Fl 1 270(The numeric digit 271.Dq one . ) 272Force output to be 273one entry per line. 274This is the default when 275output is not to a terminal. 276.El 277.Pp 278The 279.Fl 1 , C , x , 280and 281.Fl l 282options all override each other; the last one specified determines 283the format used. 284.Pp 285The 286.Fl c 287and 288.Fl u 289options override each other; the last one specified determines 290the file time used. 291.Pp 292The 293.Fl S 294and 295.Fl t 296options override each other; the last one specified determines 297the sort order used. 298.Pp 299The 300.Fl B , b , w , 301and 302.Fl q 303options all override each other; the last one specified determines 304the format used for non-printable characters. 305.Pp 306The 307.Fl H , L 308and 309.Fl P 310options all override each other (either partially or fully); they 311are applied in the order specified. 312.Pp 313By default, 314.Nm 315lists one entry per line to standard 316output; the exceptions are to terminals or when the 317.Fl C 318or 319.Fl x 320options are specified. 321.Pp 322File information is displayed with one or more 323.Ao blank Ac Ns s 324separating the information associated with the 325.Fl i , s , 326and 327.Fl l 328options. 329.Ss The Long Format 330If the 331.Fl l 332option is given, the following information 333is displayed for each file: 334file mode, 335number of links, owner name, group name, 336number of bytes in the file, 337last modified time in either per POSIX requirements or 338using the format DD-MMM-YYYY hh:ss, and the pathname. 339In addition, for each directory whose contents are displayed, the total 340number of 512-byte blocks used by the files in the directory is displayed 341on a line by itself immediately before the information for the files in the 342directory. 343.Pp 344In the POSIX locale, If the modification time of the file is in the future, 345or more than 6 months in the past, then the year of the last modification 346is displayed in place of the hour and minute fields. 347.Pp 348If the owner or group names are not a known user or group name, 349or the 350.Fl n 351option is given, 352the numeric ID's are displayed. 353.Pp 354If the file is a character special or block special file, 355the major and minor device numbers for the file are displayed 356in the size field. 357If the file is a symbolic link the pathname of the 358linked-to file is preceded by 359.Dq Li -> . 360.Pp 361The file mode printed under the 362.Fl l 363option consists of the 364entry type and the permissions. 365The entry type character describes the type of file, as 366follows: 367.Pp 368.Bl -tag -width 4n -offset indent -compact 369.It Sy b 370Block special file. 371.It Sy c 372Character special file. 373.It Sy d 374Directory. 375.It Sy l 376Symbolic link. 377.It Sy s 378Socket link. 379.It Sy p 380.Tn FIFO . 381.It Sy \- 382Regular file. 383.El 384.Pp 385The next three fields 386are three characters each: 387owner permissions, 388group permissions, and 389other permissions. 390Each field has three character positions: 391.Bl -enum -offset indent 392.It 393If 394.Sy r , 395the file is readable; if 396.Sy \- , 397it is not readable. 398.It 399If 400.Sy w , 401the file is writable; if 402.Sy \- , 403it is not writable. 404.It 405The first of the following that applies: 406.Bl -tag -width 4n -offset indent 407.It Sy S 408If in the owner permissions, the file is not executable and 409set-user-ID mode is set. 410If in the group permissions, the file is not executable 411and set-group-ID mode is set. 412.It Sy s 413If in the owner permissions, the file is executable 414and set-user-ID mode is set. 415If in the group permissions, the file is executable 416and setgroup-ID mode is set. 417.It Sy x 418The file is executable or the directory is 419searchable. 420.It Sy \- 421The file is neither readable, writable, executable, 422nor set-user-ID nor set-group-ID mode, nor sticky. 423(See below.) 424.El 425.Pp 426These next two apply only to the third character in the last group 427(other permissions). 428.Bl -tag -width 4n -offset indent 429.It Sy T 430The sticky bit is set 431(mode 432.Li 1000 ) , 433but not execute or search permission. 434(See 435.Xr chmod 1 436or 437.Xr sticky 8 . ) 438.It Sy t 439The sticky bit is set (mode 440.Li 1000 ) , 441and is searchable or executable. 442(See 443.Xr chmod 1 444or 445.Xr sticky 8 . ) 446.El 447.El 448.Sh ENVIRONMENT 449The following environment variables affect the execution of 450.Nm : 451.Bl -tag -width ".Ev CLICOLOR_FORCE" 452.It Ev BLOCKSIZE 453If the environment variable 454.Ev BLOCKSIZE 455is set, the block counts 456(see 457.Fl s ) 458will be displayed in units of that size block. 459.It Ev CLICOLOR 460Use 461.Tn ANSI 462color sequences to distinguish file types. 463See 464.Ev LSCOLORS 465below. 466In addition to the file types mentioned in the 467.Fl F 468option some extra attributes (setuid bit set, etc.) are also displayed. 469The colorization is dependent on a terminal type with the proper 470.Xr termcap 5 471capabilities. 472The default 473.Dq Li cons25 474console has the proper capabilities, 475but to display the colors in an 476.Xr xterm 1 , 477for example, 478the 479.Ev TERM 480variable must be set to 481.Dq Li xterm-color . 482Other terminal types may require similar adjustments. 483Colorization 484is silently disabled if the output is not directed to a terminal 485unless the 486.Ev CLICOLOR_FORCE 487variable is defined. 488.It Ev CLICOLOR_FORCE 489Color sequences are normally disabled if the output is not directed to 490a terminal. 491This can be overridden by setting this flag. 492The 493.Ev TERM 494variable still needs to reference a color capable terminal however 495otherwise it is not possible to determine which color sequences to 496use. 497.It Ev COLUMNS 498If this variable contains a string representing a 499decimal integer, it is used as the 500column position width for displaying 501multiple-text-column output. 502The 503.Nm 504utility calculates how 505many pathname text columns to display 506based on the width provided. 507(See 508.Fl C 509and 510.Fl x . ) 511.It Ev LANG 512The locale to use when determining the order of day and month in the long 513.Fl l 514format output. 515See 516.Xr environ 7 517for more information. 518.It Ev LSCOLORS 519The value of this variable describes what color to use for which 520attribute when colors are enabled with 521.Ev CLICOLOR . 522This string is a concatenation of pairs of the format 523.Ar f Ns Ar b , 524where 525.Ar f 526is the foreground color and 527.Ar b 528is the background color. 529.Pp 530The color designators are as follows: 531.Pp 532.Bl -tag -width 4n -offset indent -compact 533.It Sy a 534black 535.It Sy b 536red 537.It Sy c 538green 539.It Sy d 540brown 541.It Sy e 542blue 543.It Sy f 544magenta 545.It Sy g 546cyan 547.It Sy h 548light grey 549.It Sy A 550bold black, usually shows up as dark grey 551.It Sy B 552bold red 553.It Sy C 554bold green 555.It Sy D 556bold brown, usually shows up as yellow 557.It Sy E 558bold blue 559.It Sy F 560bold magenta 561.It Sy G 562bold cyan 563.It Sy H 564bold light grey; looks like bright white 565.It Sy x 566default foreground or background 567.El 568.Pp 569Note that the above are standard 570.Tn ANSI 571colors. 572The actual display may differ 573depending on the color capabilities of the terminal in use. 574.Pp 575The order of the attributes are as follows: 576.Pp 577.Bl -enum -offset indent -compact 578.It 579directory 580.It 581symbolic link 582.It 583socket 584.It 585pipe 586.It 587executable 588.It 589block special 590.It 591character special 592.It 593executable with setuid bit set 594.It 595executable with setgid bit set 596.It 597directory writable to others, with sticky bit 598.It 599directory writable to others, without sticky bit 600.El 601.Pp 602The default is 603.Qq "exfxcxdxbxegedabagacad" , 604i.e., blue foreground and 605default background for regular directories, black foreground and red 606background for setuid executables, etc. 607.It Ev LS_COLWIDTHS 608If this variable is set, it is considered to be a 609colon-delimited list of minimum column widths. 610Unreasonable 611and insufficient widths are ignored (thus zero signifies 612a dynamically sized column). 613Not all columns have changeable widths. 614The fields are, 615in order: inode, block count, number of links, user name, 616group name, flags, file size, file name. 617.It Ev TERM 618The 619.Ev CLICOLOR 620functionality depends on a terminal type with color capabilities. 621.It Ev TZ 622The timezone to use when displaying dates. 623See 624.Xr environ 7 625for more information. 626.El 627.Sh COMPATIBILITY 628The group field is now automatically included in the long listing for 629files in order to be compatible with the 630.St -p1003.2 631specification. 632.Sh SEE ALSO 633.Xr chflags 1 , 634.Xr chmod 1 , 635.Xr sort 1 , 636.Xr xterm 1 Pq Pa x11/xterm , 637.Xr termcap 5 , 638.Xr symlink 7 , 639.Xr sticky 8 640.Sh STANDARDS 641With the exception of options 642.Fl g , 643.Fl n 644and 645.Fl o , 646the 647.Nm 648utility conforms to 649.St -p1003.1-2001 . 650.Sh HISTORY 651An 652.Nm 653command appeared in 654.At v1 . 655.Sh BUGS 656To maintain backward compatibility, the relationships between the many 657options are quite complex. 658