bin/ls/ls.1

   1 .\"     $NetBSD: ls.1,v 1.69 2011/04/02 08:38:56 mbalmer Exp $
   2 .\"
   3 .\" Copyright (c) 1980, 1990, 1991, 1993, 1994
   4 .\"     The Regents of the University of California.  All rights reserved.
   5 .\"
   6 .\" This code is derived from software contributed to Berkeley by
   7 .\" the Institute of Electrical and Electronics Engineers, Inc.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\" 3. Neither the name of the University nor the names of its contributors
  18 .\"    may be used to endorse or promote products derived from this software
  19 .\"    without specific prior written permission.
  20 .\"
  21 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  22 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  23 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  24 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  25 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  26 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  27 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  28 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  29 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  30 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  31 .\" SUCH DAMAGE.
  32 .\"
  33 .\"     @(#)ls.1        8.7 (Berkeley) 7/29/94
  34 .\"
  35 .Dd April 2, 2011
  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 AaBbCcdFfghikLlMmnopqRrSsTtuWwx1
  44 .Op Ar
  45 .Sh DESCRIPTION
  46 For each operand that names a
  47 .Ar file
  48 of a type other than
  49 directory,
  50 .Nm
  51 displays its name as well as any requested,
  52 associated information.
  53 For each operand that names a
  54 .Ar file
  55 of type directory,
  56 .Nm
  57 displays the names of files contained
  58 within that directory, as well as any requested, associated
  59 information.
  60 .Pp
  61 If no operands are given, the contents of the current
  62 directory are displayed.
  63 If more than one operand is given,
  64 non-directory operands are displayed first; directory
  65 and non-directory operands are sorted separately and in
  66 lexicographical order.
  67 .Pp
  68 The following options are available:
  69 .Bl -tag -width indent
  70 .It Fl A
  71 List all entries except for
  72 .Ql \&.
  73 and
  74 .Ql \&.. .
  75 Always set for the super-user.
  76 .It Fl a
  77 Include directory entries whose names begin with a
  78 dot
  79 .Pq Sq \&. .
  80 .It Fl B
  81 Force printing of non-graphic characters in file names as \exxx, where xxx
  82 is the numeric value of the character in octal.
  83 .It Fl b
  84 As
  85 .Fl B ,
  86 but use C escape codes whenever possible.
  87 .It Fl C
  88 Force multi-column output; this is the default when output is to a terminal.
  89 .It Fl c
  90 Use time when file status was last changed,
  91 instead of time of last modification of the file for sorting
  92 .Pq Fl t
  93 or printing
  94 .Pq Fl l .
  95 .It Fl d
  96 Directories are listed as plain files (not searched recursively) and
  97 symbolic links in the argument list are not followed.
  98 .It Fl F
  99 Display a slash
 100 .Pq Sq \&/
 101 immediately after each pathname that is a directory,
 102 an asterisk
 103 .Pq Sq \&*
 104 after each that is executable,
 105 an at sign
 106 .Pq Sq \&@
 107 after each symbolic link,
 108 a percent sign
 109 .Pq Sq \&%
 110 after each whiteout,
 111 an equal sign
 112 .Pq Sq \&=
 113 after each socket,
 114 and a vertical bar
 115 .Pq Sq \&|
 116 after each that is a
 117 .Tn FIFO .
 118 .It Fl f
 119 Output is not sorted.
 120 .It Fl g
 121 The same as
 122 .Fl l ,
 123 except that the owner is not printed.
 124 .It Fl h
 125 Modifies the
 126 .Fl s
 127 and
 128 .Fl l
 129 options, causing the sizes to be reported in bytes displayed in a human
 130 readable format.
 131 Overrides
 132 .Fl k
 133 and
 134 .Fl M .
 135 .It Fl i
 136 For each file, print the file's file serial number (inode number).
 137 .It Fl k
 138 Modifies the
 139 .Fl s
 140 option, causing the sizes to be reported in kilobytes.
 141 The rightmost of the
 142 .Fl k
 143 and
 144 .Fl h
 145 flags overrides the previous flag.
 146 See also
 147 .Fl h
 148 and
 149 .Fl M .
 150 .It Fl L
 151 For each file, if it's a link, evaluate file information and file type
 152 of the referenced file and not the link itself; however still print
 153 the link name, unless used with
 154 .Fl l ,
 155 for example.
 156 .It Fl l
 157 (The lowercase letter
 158 .Dq ell ) .
 159 List in long format.
 160 (See below.)
 161 A total sum for all the file sizes is output on a line before the long
 162 listing.
 163 .It Fl M
 164 Modifies the
 165 .Fl l
 166 and
 167 .Fl s
 168 options, causing the sizes or block counts reported to be separated with
 169 commas (or a locale appropriate separator) resulting in a more readable
 170 output.
 171 Overrides
 172 .Fl h .
 173 Does not override
 174 .Fl k .
 175 .It Fl m
 176 Stream output format; list files across the page, separated by commas.
 177 .It Fl n
 178 The same as
 179 .Fl l ,
 180 except that
 181 the owner and group IDs are displayed numerically rather than converting
 182 to a owner or group name.
 183 .It Fl o
 184 Include the file flags in a long
 185 .Pq Fl l
 186 output.
 187 If no file flags are set,
 188 .Dq -
 189 is displayed.
 190 (See
 191 .Xr chflags 1
 192 for a list of possible flags and their meanings.)
 193 .It Fl p
 194 Display a slash
 195 .Pq Sq \&/
 196 immediately after each pathname that is a directory.
 197 .It Fl q
 198 Force printing of non-printable characters in file names as
 199 the character
 200 .Sq \&? ;
 201 this is the default when output is to a terminal.
 202 .It Fl R
 203 Recursively list subdirectories encountered.
 204 .It Fl r
 205 Reverse the order of the sort to get reverse
 206 lexicographical order or the smallest or oldest entries first.
 207 .It Fl S
 208 Sort by size, largest file first.
 209 .It Fl s
 210 Display the number of file system blocks actually used by each file, in units
 211 of 512 bytes or
 212 .Ev BLOCKSIZE
 213 (see
 214 .Sx ENVIRONMENT )
 215 where partial units are rounded up to the
 216 next integer value.
 217 If the output is to a terminal, a total sum for all the file
 218 sizes is output on a line before the listing.
 219 .It Fl T
 220 When used with the
 221 .Fl l
 222 (the lowercase letter
 223 .Dq ell )
 224 option, display complete time information for the file, including
 225 month, day, hour, minute, second, and year.
 226 .It Fl t
 227 Sort by time modified (most recently modified
 228 first) before sorting the operands by lexicographical
 229 order.
 230 .It Fl u
 231 Use time of last access,
 232 instead of last modification
 233 of the file for sorting
 234 .Pq Fl t
 235 or printing
 236 .Pq Fl l .
 237 .It Fl W
 238 Display whiteouts when scanning directories.
 239 .It Fl w
 240 Force raw printing of non-printable characters.
 241 This is the default when output is not to a terminal.
 242 .It Fl x
 243 Multi-column output sorted across the page rather than down the page.
 244 .It Fl \&1
 245 (The numeric digit
 246 .Dq one ) .
 247 Force output to be one entry per line.
 248 This is the default when output is not to a terminal.
 249 .El
 250 .Pp
 251 The
 252 .Fl B ,
 253 .Fl b ,
 254 .Fl w ,
 255 and
 256 .Fl q
 257 options all override each other; the last one specified determines
 258 the format used for non-printable characters.
 259 .Pp
 260 The
 261 .Fl 1 ,
 262 .Fl C ,
 263 .Fl g ,
 264 .Fl l ,
 265 .Fl m ,
 266 and
 267 .Fl x
 268 options all override each other; the last one specified determines
 269 the format used with the exception that if both
 270 .Fl l
 271 and
 272 .Fl g
 273 are specified,
 274 .Fl l
 275 will always override
 276 .Fl g ,
 277 even if
 278 .Fl g
 279 was specified last.
 280 .Pp
 281 The
 282 .Fl c
 283 and
 284 .Fl u
 285 options override each other; the last one specified determines
 286 the file time used.
 287 .Pp
 288 By default,
 289 .Nm
 290 lists one entry per line to standard
 291 output; the exceptions are to terminals or when the
 292 .Fl C
 293 or
 294 .Fl m
 295 options are specified.
 296 .Pp
 297 File information is displayed with one or more
 298 .Aq blank
 299 separating the information associated with the
 300 .Fl i ,
 301 .Fl s ,
 302 and
 303 .Fl l
 304 options.
 305 .Ss The Long Format
 306 If the
 307 .Fl l
 308 option is given, the following information
 309 is displayed for each file:
 310 .Bl -item -offset indent -compact
 311 .It
 312 file mode
 313 .It
 314 number of links
 315 .It
 316 owner name
 317 .It
 318 group name
 319 .It
 320 file flags (if
 321 .Fl o
 322 given)
 323 .It
 324 number of bytes in the file
 325 .It
 326 abbreviated month file was last modified
 327 .It
 328 day-of-month file was last modified
 329 .It
 330 hour and minute file was last modified
 331 .It
 332 pathname
 333 .El
 334 .Pp
 335 In addition, for each directory whose contents are displayed, the total
 336 number of 512-byte blocks used by the files in the directory is displayed
 337 on a line by itself immediately before the information for the files in the
 338 directory.
 339 .Pp
 340 If the owner or group names are not a known owner or group name,
 341 or the
 342 .Fl n
 343 option is given,
 344 the numeric ID's are displayed.
 345 .Pp
 346 If the file is a character special or block special file,
 347 the major and minor device numbers for the file are displayed
 348 in the size field.
 349 If the file is a symbolic link the pathname of the
 350 linked-to file is preceded by
 351 .Dq \-\*[Gt] .
 352 .Pp
 353 The file mode printed under the
 354 .Fl l
 355 option consists of the entry type, owner permissions, group
 356 permissions, and other permissions.
 357 The entry type character describes the type of file, as
 358 follows:
 359 .Pp
 360 .Bl -tag -width 4n -offset indent -compact
 361 .It Sy a
 362 Archive state 1.
 363 .It Sy A
 364 Archive state 2.
 365 .It Sy b
 366 Block special file.
 367 .It Sy c
 368 Character special file.
 369 .It Sy d
 370 Directory.
 371 .It Sy l
 372 Symbolic link.
 373 .It Sy s
 374 Socket link.
 375 .It Sy p
 376 FIFO.
 377 .It Sy w
 378 Whiteout.
 379 .It Sy \-
 380 Regular file.
 381 .El
 382 .Pp
 383 The next three fields
 384 are three characters each:
 385 owner permissions,
 386 group permissions, and
 387 other permissions.
 388 Each field has three character positions:
 389 .Bl -enum -offset indent
 390 .It
 391 If
 392 .Sy r ,
 393 the file is readable; if
 394 .Sy \- ,
 395 it is not readable.
 396 .It
 397 If
 398 .Sy w ,
 399 the file is writable; if
 400 .Sy \- ,
 401 it is not writable.
 402 .It
 403 The first of the following that applies:
 404 .Bl -tag -width 4n -offset indent
 405 .It Sy S
 406 If in the owner permissions, the file is not executable and
 407 set-user-ID mode is set.
 408 If in the group permissions, the file is not executable
 409 and set-group-ID mode is set.
 410 .It Sy s
 411 If in the owner permissions, the file is executable
 412 and set-user-ID mode is set.
 413 If in the group permissions, the file is executable
 414 and setgroup-ID mode is set.
 415 .It Sy x
 416 The file is executable or the directory is
 417 searchable.
 418 .It Sy \-
 419 The file is neither readable, writable, executable,
 420 nor set-user-ID nor set-group-ID mode, nor sticky.
 421 (See below.)
 422 .El
 423 .Pp
 424 These next two apply only to the third character in the last group
 425 (other permissions).
 426 .Bl -tag -width 4n -offset indent
 427 .It Sy T
 428 The sticky bit is set
 429 (mode
 430 .Li 1000 ) ,
 431 but not execute or search permission.
 432 (See
 433 .Xr chmod 1
 434 or
 435 .Xr sticky 7 . )
 436 .It Sy t
 437 The sticky bit is set (mode
 438 .Li 1000 ) ,
 439 and is searchable or executable.
 440 (See
 441 .Xr chmod 1
 442 or
 443 .Xr sticky 7 . )
 444 .El
 445 .El
 446 .Pp
 447 The number of bytes displayed for a directory is a function of the
 448 number of
 449 .Xr dirent 3
 450 structures in the directory, not all of which may be allocated to
 451 any existing file.
 452 .Sh ENVIRONMENT
 453 The following environment variables affect the execution of
 454 .Nm :
 455 .Bl -tag -width BLOCKSIZE
 456 .It Ev BLOCKSIZE
 457 If the environment variable
 458 .Ev BLOCKSIZE
 459 is set, and the
 460 .Fl h
 461 and
 462 .Fl k
 463 options are not specified, the block counts
 464 (see
 465 .Fl s )
 466 will be displayed in units of that size block.
 467 .It Ev COLUMNS
 468 If this variable contains a string representing a
 469 decimal integer, it is used as the
 470 column position width for displaying
 471 multiple-text-column output.
 472 The
 473 .Nm
 474 utility calculates how
 475 many pathname text columns to display
 476 based on the width provided.
 477 (See
 478 .Fl C . )
 479 .It Ev TZ
 480 The timezone to use when displaying dates.
 481 See
 482 .Xr environ 7
 483 for more information.
 484 .El
 485 .Sh EXIT STATUS
 486 .Ex -std
 487 .Sh COMPATIBILITY
 488 The group field is now automatically included in the long listing for
 489 files in order to be compatible with the
 490 .St -p1003.2
 491 specification.
 492 .Sh SEE ALSO
 493 .Xr chflags 1 ,
 494 .Xr chmod 1 ,
 495 .Xr stat 2 ,
 496 .Xr dirent 3 ,
 497 .Xr getbsize 3 ,
 498 .Xr sticky 7 ,
 499 .Xr symlink 7
 500 .Sh STANDARDS
 501 The
 502 .Nm
 503 utility is expected to be a superset of the
 504 .St -p1003.2
 505 specification.
 506 .Sh HISTORY
 507 An
 508 .Nm
 509 utility appeared in
 510 .At v5 .