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 November 20, 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 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 (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 B , b , w , 294and 295.Fl q 296options all override each other; the last one specified determines 297the format used for non-printable characters. 298.Pp 299The 300.Fl H , L 301and 302.Fl P 303options all override each other (either partially or fully); they 304are applied in the order specified. 305.Pp 306By default, 307.Nm 308lists one entry per line to standard 309output; the exceptions are to terminals or when the 310.Fl C 311or 312.Fl x 313options are specified. 314.Pp 315File information is displayed with one or more 316.Ao blank Ac Ns s 317separating the information associated with the 318.Fl i , s , 319and 320.Fl l 321options. 322.Ss The Long Format 323If the 324.Fl l 325option is given, the following information 326is displayed for each file: 327file mode, 328number of links, owner name, group name, 329number of bytes in the file, 330last modified time in either per POSIX requirements or 331using the format DD-MMM-YYYY hh:ss, 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 337In the POSIX locale, If the modification time of the file is in the future, 338or more than 6 months in the past, 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