ls/ls.1

   1 .\"     $NetBSD: ls.1,v 1.19 1998/06/01 21:11:28 hubertf 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. All advertising materials mentioning features or use of this software
  18 .\"    must display the following acknowledgement:
  19 .\"     This product includes software developed by the University of
  20 .\"     California, Berkeley and its contributors.
  21 .\" 4. Neither the name of the University nor the names of its contributors
  22 .\"    may be used to endorse or promote products derived from this software
  23 .\"    without specific prior written permission.
  24 .\"
  25 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  26 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  27 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  28 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  29 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  30 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  31 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  32 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  33 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  34 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  35 .\" SUCH DAMAGE.
  36 .\"
  37 .\"     @(#)ls.1        8.7 (Berkeley) 7/29/94
  38 .\"
  39 .Dd July 29, 1994
  40 .Dt LS 1
  41 .Os
  42 .Sh NAME
  43 .Nm ls
  44 .Nd list directory contents
  45 .Sh SYNOPSIS
  46 .Nm
  47 .Op Fl ACFLRSTWacdfgiklnoqrstux1
  48 .Op Ar file ...
  49 .Sh DESCRIPTION
  50 For each operand that names a
  51 .Ar file
  52 of a type other than
  53 directory,
  54 .Nm
  55 displays its name as well as any requested,
  56 associated information.
  57 For each operand that names a
  58 .Ar file
  59 of type directory,
  60 .Nm
  61 displays the names of files contained
  62 within that directory, as well as any requested, associated
  63 information.
  64 .Pp
  65 If no operands are given, the contents of the current
  66 directory are displayed.
  67 If more than one operand is given,
  68 non-directory operands are displayed first; directory
  69 and non-directory operands are sorted separately and in
  70 lexicographical order.
  71 .Pp
  72 The following options are available:
  73 .Bl -tag -width indent
  74 .It Fl A
  75 List all entries except for
  76 .Ql \&.
  77 and
  78 .Ql \&.. .
  79 Always set for the super-user.
  80 .It Fl C
  81 Force multi-column output; this is the default when output is to a terminal.
  82 .It Fl F
  83 Display a slash (/) immediately after each pathname that is a directory,
  84 an asterisk (*) after each that is executable,
  85 an at sign (@) after each symbolic link,
  86 a percent sign (%) after each whiteout,
  87 an equal sign (=) after each socket,
  88 and a vertical bar (|) after each that is a
  89 .Tn FIFO .
  90 .It Fl L
  91 If argument is a symbolic link, list the file or directory the link references
  92 rather than the link itself.
  93 .It Fl R
  94 Recursively list subdirectories encountered.
  95 .It Fl S
  96 Sort by size, largest file first.
  97 .It Fl T
  98 Display complete time information for the file, including
  99 month, day, hour, minute, second, and year.
 100 .It Fl W
 101 Display whiteouts when scanning directories.
 102 .It Fl a
 103 Include directory entries whose names begin with a
 104 dot (.).
 105 .It Fl c
 106 Use time when file status was last changed for sorting or printing.
 107 .It Fl d
 108 Directories are listed as plain files (not searched recursively) and
 109 symbolic links in the argument list are not indirected through.
 110 .It Fl f
 111 Output is not sorted.
 112 .It Fl g
 113 Does nothing; kept for compatibility with older versions of
 114 .Xr ls 1 .
 115 .It Fl i
 116 For each file, print the file's file serial number (inode number).
 117 .It Fl k
 118 Modifies the
 119 .Fl s
 120 option, causing the sizes to be reported in kilobytes.
 121 .It Fl l
 122 (The lowercase letter ``ell.'')  List in long format. (See below.)
 123 If the output is to a terminal, a total sum for all the file
 124 sizes is output on a line before the long listing.
 125 .It Fl n
 126 Display the user and group IDs numerically rather than converting
 127 to a user or group name in a long
 128 .Pq Fl l
 129 output.
 130 .It Fl o
 131 Include the file flags in a long
 132 .Pq Fl l
 133 output.
 134 .It Fl q
 135 Force printing of non-graphic characters in file names as
 136 the character `?'; this is the default when output is to a terminal.
 137 .It Fl r
 138 Reverse the order of the sort to get reverse
 139 lexicographical order or the smallest or oldest entries first.
 140 .It Fl s
 141 Display the number of file system blocks actually used by each file, in units
 142 of 512 bytes, where partial units are rounded up to the next integer value.
 143 If the output is to a terminal, a total sum for all the file
 144 sizes is output on a line before the listing.
 145 .It Fl t
 146 Sort by time modified (most recently modified
 147 first) before sorting the operands by lexicographical
 148 order.
 149 .It Fl u
 150 Use time of last access,
 151 instead of last modification
 152 of the file for sorting
 153 .Pq Fl t
 154 or printing
 155 .Pq Fl l .
 156 .It Fl x
 157 Multi-column output sorted across the page rather than down the page.
 158 .It Fl v
 159 Force unedited printing of non-graphic characters; this is the default when
 160 output is not to a terminal.
 161 .It Fl \&1
 162 (The numeric digit ``one.'')  Force output to be
 163 one entry per line.
 164 This is the default when
 165 output is not to a terminal.
 166 .El
 167 .Pp
 168 The
 169 .Fl 1 ,
 170 .Fl C ,
 171 .Fl l ,
 172 and
 173 .Fl x
 174 options all override each other; the last one specified determines
 175 the format used.
 176 .Pp
 177 The
 178 .Fl c ,
 179 and
 180 .Fl u
 181 options override each other; the last one specified determines
 182 the file time used.
 183 .Pp
 184 By default,
 185 .Nm
 186 lists one entry per line to standard
 187 output; the exceptions are to terminals or when the
 188 .Fl C
 189 option is specified.
 190 .Pp
 191 File information is displayed with one or more
 192 <blank>s separating the information associated with the
 193 .Fl i ,
 194 .Fl s ,
 195 and
 196 .Fl l
 197 options.
 198 .Ss The Long Format
 199 If the
 200 .Fl l
 201 option is given, the following information
 202 is displayed for each file:
 203 file mode,
 204 number of links, owner name, group name,
 205 number of bytes in the file, abbreviated
 206 month, day-of-month file was last modified,
 207 hour file last modified, minute file last
 208 modified, and the pathname.
 209 In addition, for each directory whose contents are displayed, the total
 210 number of 512-byte blocks used by the files in the directory is displayed
 211 on a line by itself immediately before the information for the files in the
 212 directory.
 213 .Pp
 214 If the owner or group names are not a known user or group name,
 215 or the
 216 .Fl n
 217 option is given,
 218 the numeric ID's are displayed.
 219 .Pp
 220 If the file is a character special or block special file,
 221 the major and minor device numbers for the file are displayed
 222 in the size field. If the file is a symbolic link the pathname of the
 223 linked-to file is preceded by
 224 .Dq \-> .
 225 .Pp
 226 The file mode printed under the
 227 .Fl l
 228 option consists of the
 229 entry type, owner permissions, and group permissions.
 230 The entry type character describes the type of file, as
 231 follows:
 232 .Pp
 233 .Bl -tag -width 4n -offset indent -compact
 234 .It Sy b
 235 Block special file.
 236 .It Sy c
 237 Character special file.
 238 .It Sy d
 239 Directory.
 240 .It Sy l
 241 Symbolic link.
 242 .It Sy s
 243 Socket link.
 244 .\" .It Sy p
 245 .\" .Tn FIFO .
 246 .It Sy w
 247 Whiteout.
 248 .It Sy \-
 249 Regular file.
 250 .El
 251 .Pp
 252 The next three fields
 253 are three characters each:
 254 owner permissions,
 255 group permissions, and
 256 other permissions.
 257 Each field has three character positions:
 258 .Bl -enum -offset indent
 259 .It
 260 If
 261 .Sy r ,
 262 the file is readable; if
 263 .Sy \- ,
 264 it is not readable.
 265 .It
 266 If
 267 .Sy w ,
 268 the file is writable; if
 269 .Sy \- ,
 270 it is not writable.
 271 .It
 272 The first of the following that applies:
 273 .Bl -tag -width 4n -offset indent
 274 .It Sy S
 275 If in the owner permissions, the file is not executable and
 276 set-user-ID mode is set.
 277 If in the group permissions, the file is not executable
 278 and set-group-ID mode is set.
 279 .It Sy s
 280 If in the owner permissions, the file is executable
 281 and set-user-ID mode is set.
 282 If in the group permissions, the file is executable
 283 and setgroup-ID mode is set.
 284 .It Sy x
 285 The file is executable or the directory is
 286 searchable.
 287 .It Sy \-
 288 The file is neither readable, writable, executable,
 289 nor set-user-ID nor set-group-ID mode, nor sticky. (See below.)
 290 .El
 291 .Pp
 292 These next two apply only to the third character in the last group
 293 (other permissions).
 294 .Bl -tag -width 4n -offset indent
 295 .It Sy T
 296 The sticky bit is set
 297 (mode
 298 .Li 1000 ) ,
 299 but not execute or search permission. (See
 300 .Xr chmod 1
 301 or
 302 .Xr sticky 8 . )
 303 .It Sy t
 304 The sticky bit is set (mode
 305 .Li 1000 ) ,
 306 and is searchable or executable.
 307 (See
 308 .Xr chmod 1
 309 or
 310 .Xr sticky 8 . )
 311 .El
 312 .El
 313 .Pp
 314 The
 315 .Nm
 316 utility exits 0 on success, and >0 if an error occurs.
 317 .Sh ENVIRONMENT VARIABLES
 318 The following environment variables affect the execution of
 319 .Nm "" :
 320 .Bl -tag -width BLOCKSIZE
 321 .It Ev BLOCKSIZE
 322 If the environment variable
 323 .Ev BLOCKSIZE
 324 is set, and the
 325 .Fl k
 326 option is not specified, the block counts
 327 (see
 328 .Fl s )
 329 will be displayed in units of that size block.
 330 .It COLUMNS
 331 If this variable contains a string representing a
 332 decimal integer, it is used as the
 333 column position width for displaying
 334 multiple-text-column output.
 335 The
 336 .Nm
 337 utility calculates how
 338 many pathname text columns to display
 339 based on the width provided.
 340 (See
 341 .Fl C . )
 342 .It Ev TZ
 343 The timezone to use when displaying dates.
 344 See
 345 .Xr environ 7
 346 for more information.
 347 .El
 348 .Sh COMPATIBILITY
 349 The group field is now automatically included in the long listing for
 350 files in order to be compatible with the
 351 .St -p1003.2
 352 specification.
 353 .Sh SEE ALSO
 354 .Xr chmod 1 ,
 355 .Xr symlink 7 ,
 356 .Xr sticky 8
 357 .Sh STANDARDS
 358 The
 359 .Nm
 360 utility is expected to be a superset of the
 361 .St -p1003.2
 362 specification.
 363 .Sh HISTORY
 364 An
 365 .Nm
 366 utility appeared in
 367 .At v5 .