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