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