bin/ls/ls.1

   1 .\"     $NetBSD: ls.1,v 1.62 2006/09/22 23:00:32 elad 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 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 AaBbCcdFfghikLlmnopqRrSsTtuWwx1
  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 \\xxx, 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 indirected through.
  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 .It Fl i
 134 For each file, print the file's file serial number (inode number).
 135 .It Fl k
 136 Modifies the
 137 .Fl s
 138 option, causing the sizes to be reported in kilobytes.
 139 The rightmost of the
 140 .Fl k
 141 and
 142 .Fl h
 143 flags overrides the previous flag.
 144 See also
 145 .Fl h .
 146 .It Fl L
 147 For each file, if it's a link, evaluate file information and file type
 148 of the referenced file and not the link itself; however still print
 149 the link name, unless used with
 150 .Fl l ,
 151 for example.
 152 .It Fl l
 153 (The lowercase letter
 154 .Dq ell ) .
 155 List in long format.
 156 (See below.)
 157 A total sum for all the file sizes is output on a line before the long
 158 listing.
 159 .It Fl m
 160 Stream output format; list files across the page, separated by commas.
 161 .It Fl n
 162 The same as
 163 .Fl l ,
 164 except that
 165 the owner and group IDs are displayed numerically rather than converting
 166 to a owner or group name.
 167 .It Fl o
 168 Include the file flags in a long
 169 .Pq Fl l
 170 output.
 171 If no file flags are set,
 172 .Dq -
 173 is displayed.
 174 (See
 175 .Xr chflags 1
 176 for a list of possible flags and their meanings.)
 177 .It Fl p
 178 Display a slash
 179 .Pq Sq \&/
 180 immediately after each pathname that is a directory.
 181 .It Fl q
 182 Force printing of non-printable characters in file names as
 183 the character
 184 .Sq \&? ;
 185 this is the default when output is to a terminal.
 186 .It Fl R
 187 Recursively list subdirectories encountered.
 188 .It Fl r
 189 Reverse the order of the sort to get reverse
 190 lexicographical order or the smallest or oldest entries first.
 191 .It Fl S
 192 Sort by size, largest file first.
 193 .It Fl s
 194 Display the number of file system blocks actually used by each file, in units
 195 of 512 bytes or
 196 .Ev BLOCKSIZE
 197 (see
 198 .Sx ENVIRONMENT )
 199 where partial units are rounded up to the
 200 next integer value.
 201 If the output is to a terminal, a total sum for all the file
 202 sizes is output on a line before the listing.
 203 .It Fl T
 204 When used with the
 205 .Fl l
 206 (the lowercase letter
 207 .Dq ell )
 208 option, display complete time information for the file, including
 209 month, day, hour, minute, second, and year.
 210 .It Fl t
 211 Sort by time modified (most recently modified
 212 first) before sorting the operands by lexicographical
 213 order.
 214 .It Fl u
 215 Use time of last access,
 216 instead of last modification
 217 of the file for sorting
 218 .Pq Fl t
 219 or printing
 220 .Pq Fl l .
 221 .It Fl W
 222 Display whiteouts when scanning directories.
 223 .It Fl w
 224 Force raw printing of non-printable characters.
 225 This is the default when output is not to a terminal.
 226 .It Fl x
 227 Multi-column output sorted across the page rather than down the page.
 228 .It Fl \&1
 229 (The numeric digit
 230 .Dq one ) .
 231 Force output to be one entry per line.
 232 This is the default when output is not to a terminal.
 233 .El
 234 .Pp
 235 The
 236 .Fl B ,
 237 .Fl b ,
 238 .Fl w ,
 239 and
 240 .Fl q
 241 options all override each other; the last one specified determines
 242 the format used for non-printable characters.
 243 .Pp
 244 The
 245 .Fl 1 ,
 246 .Fl C ,
 247 .Fl g ,
 248 .Fl l ,
 249 .Fl m ,
 250 and
 251 .Fl x
 252 options all override each other; the last one specified determines
 253 the format used with the exception that if both
 254 .Fl l
 255 and
 256 .Fl g
 257 are specified,
 258 .Fl l
 259 will always override
 260 .Fl g ,
 261 even if
 262 .Fl g
 263 was specified last.
 264 .Pp
 265 The
 266 .Fl c
 267 and
 268 .Fl u
 269 options override each other; the last one specified determines
 270 the file time used.
 271 .Pp
 272 By default,
 273 .Nm
 274 lists one entry per line to standard
 275 output; the exceptions are to terminals or when the
 276 .Fl C
 277 or
 278 .Fl m
 279 options are specified.
 280 .Pp
 281 File information is displayed with one or more
 282 .Aq blank
 283 separating the information associated with the
 284 .Fl i ,
 285 .Fl s ,
 286 and
 287 .Fl l
 288 options.
 289 .Ss The Long Format
 290 If the
 291 .Fl l
 292 option is given, the following information
 293 is displayed for each file:
 294 .Bl -item -offset indent -compact
 295 .It
 296 file mode
 297 .It
 298 number of links
 299 .It
 300 owner name
 301 .It
 302 group name
 303 .It
 304 file flags (if
 305 .Fl o
 306 given)
 307 .It
 308 number of bytes in the file
 309 .It
 310 abbreviated month file was last modified
 311 .It
 312 day-of-month file was last modified
 313 .It
 314 hour and minute file was last modified
 315 .It
 316 pathname
 317 .El
 318 .Pp
 319 In addition, for each directory whose contents are displayed, the total
 320 number of 512-byte blocks used by the files in the directory is displayed
 321 on a line by itself immediately before the information for the files in the
 322 directory.
 323 .Pp
 324 If the owner or group names are not a known owner or group name,
 325 or the
 326 .Fl n
 327 option is given,
 328 the numeric ID's are displayed.
 329 .Pp
 330 If the file is a character special or block special file,
 331 the major and minor device numbers for the file are displayed
 332 in the size field.
 333 If the file is a symbolic link the pathname of the
 334 linked-to file is preceded by
 335 .Dq \-\*[Gt] .
 336 .Pp
 337 The file mode printed under the
 338 .Fl l
 339 option consists of the entry type, owner permissions, group
 340 permissions, and other permissions.
 341 The entry type character describes the type of file, as
 342 follows:
 343 .Pp
 344 .Bl -tag -width 4n -offset indent -compact
 345 .It Sy a
 346 Archive state 1.
 347 .It Sy A
 348 Archive state 2.
 349 .It Sy b
 350 Block special file.
 351 .It Sy c
 352 Character special file.
 353 .It Sy d
 354 Directory.
 355 .It Sy l
 356 Symbolic link.
 357 .It Sy s
 358 Socket link.
 359 .It Sy p
 360 FIFO.
 361 .It Sy w
 362 Whiteout.
 363 .It Sy \-
 364 Regular file.
 365 .El
 366 .Pp
 367 The next three fields
 368 are three characters each:
 369 owner permissions,
 370 group permissions, and
 371 other permissions.
 372 Each field has three character positions:
 373 .Bl -enum -offset indent
 374 .It
 375 If
 376 .Sy r ,
 377 the file is readable; if
 378 .Sy \- ,
 379 it is not readable.
 380 .It
 381 If
 382 .Sy w ,
 383 the file is writable; if
 384 .Sy \- ,
 385 it is not writable.
 386 .It
 387 The first of the following that applies:
 388 .Bl -tag -width 4n -offset indent
 389 .It Sy S
 390 If in the owner permissions, the file is not executable and
 391 set-user-ID mode is set.
 392 If in the group permissions, the file is not executable
 393 and set-group-ID mode is set.
 394 .It Sy s
 395 If in the owner permissions, the file is executable
 396 and set-user-ID mode is set.
 397 If in the group permissions, the file is executable
 398 and setgroup-ID mode is set.
 399 .It Sy x
 400 The file is executable or the directory is
 401 searchable.
 402 .It Sy \-
 403 The file is neither readable, writable, executable,
 404 nor set-user-ID nor set-group-ID mode, nor sticky.
 405 (See below.)
 406 .El
 407 .Pp
 408 These next two apply only to the third character in the last group
 409 (other permissions).
 410 .Bl -tag -width 4n -offset indent
 411 .It Sy T
 412 The sticky bit is set
 413 (mode
 414 .Li 1000 ) ,
 415 but not execute or search permission.
 416 (See
 417 .Xr chmod 1
 418 or
 419 .Xr sticky 7 . )
 420 .It Sy t
 421 The sticky bit is set (mode
 422 .Li 1000 ) ,
 423 and is searchable or executable.
 424 (See
 425 .Xr chmod 1
 426 or
 427 .Xr sticky 7 . )
 428 .El
 429 .El
 430 .Pp
 431 The number of bytes displayed for a directory is a function of the
 432 number of
 433 .Xr dirent 5
 434 structures in the directory, not all of which may be allocated to
 435 any existing file.
 436 .Sh EXIT STATUS
 437 The
 438 .Nm
 439 utility exits 0 on success, and \*[Gt]0 if an error occurs.
 440 .Sh ENVIRONMENT
 441 The following environment variables affect the execution of
 442 .Nm :
 443 .Bl -tag -width BLOCKSIZE
 444 .It Ev BLOCKSIZE
 445 If the environment variable
 446 .Ev BLOCKSIZE
 447 is set, and the
 448 .Fl h
 449 and
 450 .Fl k
 451 options are not specified, the block counts
 452 (see
 453 .Fl s )
 454 will be displayed in units of that size block.
 455 .It Ev COLUMNS
 456 If this variable contains a string representing a
 457 decimal integer, it is used as the
 458 column position width for displaying
 459 multiple-text-column output.
 460 The
 461 .Nm
 462 utility calculates how
 463 many pathname text columns to display
 464 based on the width provided.
 465 (See
 466 .Fl C . )
 467 .It Ev TZ
 468 The timezone to use when displaying dates.
 469 See
 470 .Xr environ 7
 471 for more information.
 472 .El
 473 .Sh COMPATIBILITY
 474 The group field is now automatically included in the long listing for
 475 files in order to be compatible with the
 476 .St -p1003.2
 477 specification.
 478 .Sh SEE ALSO
 479 .Xr chflags 1 ,
 480 .Xr chmod 1 ,
 481 .Xr stat 2 ,
 482 .Xr getbsize 3 ,
 483 .Xr dir 5 ,
 484 .Xr sticky 7 ,
 485 .Xr symlink 7
 486 .Sh STANDARDS
 487 The
 488 .Nm
 489 utility is expected to be a superset of the
 490 .St -p1003.2
 491 specification.
 492 .Sh HISTORY
 493 An
 494 .Nm
 495 utility appeared in
 496 .At v5 .