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