bin/ls/ls.1

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