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