bin/ls/ls.1

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