usr.bin/find/find.1

   1 .\"     The Regents of the University of California.  All rights reserved.
   2 .\"
   3 .\" This code is derived from software contributed to Berkeley by
   4 .\" the Institute of Electrical and Electronics Engineers, Inc.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\" 3. All advertising materials mentioning features or use of this software
  15 .\"    must display the following acknowledgement:
  16 .\"     This product includes software developed by the University of
  17 .\"     California, Berkeley and its contributors.
  18 .\" 4. Neither the name of the University nor the names of its contributors
  19 .\"    may be used to endorse or promote products derived from this software
  20 .\"    without specific prior written permission.
  21 .\"
  22 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  23 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  24 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  25 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  26 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  27 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  28 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  29 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  30 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  31 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  32 .\" SUCH DAMAGE.
  33 .\"
  34 .\"     @(#)find.1      8.7 (Berkeley) 5/9/95
  35 .\" $FreeBSD$
  36 .\"
  37 .Dd May 9, 1995
  38 .Dt FIND 1
  39 .Os
  40 .Sh NAME
  41 .Nm find
  42 .Nd walk a file hierarchy
  43 .Sh SYNOPSIS
  44 .Nm find
  45 .Op Fl H | Fl L | Fl P
  46 .Op Fl Xdsx
  47 .Op Fl f Ar pathname
  48 .Op Ar pathname ...
  49 .Ar expression
  50 .Sh DESCRIPTION
  51 .Nm Find
  52 recursively descends the directory tree for each
  53 .Ar pathname
  54 listed, evaluating an
  55 .Ar expression
  56 (composed of the ``primaries'' and ``operands'' listed below) in terms
  57 of each file in the tree.
  58 .Pp
  59 The options are as follows:
  60 .Pp
  61 .Bl -tag -width Ds
  62 .It Fl H
  63 The
  64 .Fl H
  65 option causes the file information and file type (see
  66 .Xr stat 2 )
  67 returned for each symbolic link specified on the command line to be
  68 those of the file referenced by the link, not the link itself.
  69 If the referenced file does not exist, the file information and type will
  70 be for the link itself.
  71 File information of all symbolic links not on
  72 the command line is that of the link itself.
  73 .It Fl L
  74 The
  75 .Fl L
  76 option causes the file information and file type (see
  77 .Xr stat 2 )
  78 returned for each symbolic link to be those of the file referenced by the
  79 link, not the link itself.
  80 If the referenced file does not exist, the file information and type will
  81 be for the link itself.
  82 .It Fl P
  83 The
  84 .Fl P
  85 option causes the file information and file type (see
  86 .Xr stat 2 )
  87 returned for each symbolic link to be those of the link itself.
  88 This is the default.
  89 .It Fl X
  90 The
  91 .Fl X
  92 option is a modification to permit
  93 .Nm
  94 to be safely used in conjunction with
  95 .Xr xargs 1 .
  96 If a file name contains any of the delimiting characters used by
  97 .Xr xargs ,
  98 a diagnostic message is displayed on standard error, and the file
  99 is skipped.
 100 The delimiting characters include single (`` ' '') and double (`` " '')
 101 quotes, backslash (``\e''), space, tab and newline characters.
 102 .It Fl d
 103 The
 104 .Fl d
 105 option causes
 106 .Nm find
 107 to perform a depth\-first traversal, i.e. directories
 108 are visited in post\-order and all entries in a directory will be acted
 109 on before the directory itself.
 110 By default,
 111 .Nm find
 112 visits directories in pre\-order, i.e. before their contents.
 113 Note, the default is
 114 .Ar not
 115 a breadth\-first traversal.
 116 .It Fl f
 117 The
 118 .Fl f
 119 option specifies a file hierarchy for
 120 .Nm find
 121 to traverse.
 122 File hierarchies may also be specified as the operands immediately
 123 following the options.
 124 .It Fl s
 125 The
 126 .Fl s
 127 option causes
 128 .Nm find
 129 to traverse the file hierarchies in lexicographical order,
 130 i.e., alphabetical order within each directory.
 131 Note:
 132 .Sq find -s
 133 and
 134 .So
 135 find | sort
 136 .Sc
 137 may give different results.
 138 .It Fl x
 139 The
 140 .Fl x
 141 option prevents
 142 .Nm find
 143 from descending into directories that have a device number different
 144 than that of the file from which the descent began.
 145 .El
 146 .Sh PRIMARIES
 147 .Bl -tag -width Ds
 148 .It Ic -amin Ar n
 149 True if the difference between the file last access time and the time
 150 .Nm find
 151 was started, rounded up to the next full minutes period, is
 152 .Ar n
 153 minutes periods.
 154 .It Ic -atime Ar n
 155 True if the difference between the file last access time and the time
 156 .Nm find
 157 was started, rounded up to the next full 24\-hour period, is
 158 .Ar n
 159 24\-hour periods.
 160 .It Ic -cmin Ar n
 161 True if the difference between the time of last change of file status
 162 information and the time
 163 .Nm find
 164 was started, rounded up to the next full minutes period, is
 165 .Ar n
 166 minutes periods.
 167 .It Ic -ctime Ar n
 168 True if the difference between the time of last change of file status
 169 information and the time
 170 .Nm find
 171 was started, rounded up to the next full 24\-hour period, is
 172 .Ar n
 173 24\-hour periods.
 174 .It Ic -delete
 175 Delete found files and/or directories.
 176 Always returns true.
 177 This executes
 178 from the current working directory as
 179 .Nm
 180 recurses down the tree.
 181 It will not attempt to delete a filename with a ``/''
 182 character in its pathname relative to "." for security reasons.
 183 Depth\-first traversal processing is implied by this option.
 184 .It Ic -exec Ar utility Op argument ... ;
 185 True if the program named
 186 .Ar utility
 187 returns a zero value as its exit status.
 188 Optional arguments may be passed to the utility.
 189 The expression must be terminated by a semicolon (``;'').
 190 If the string ``{}'' appears anywhere in the utility name or the
 191 arguments it is replaced by the pathname of the current file.
 192 .Ar Utility
 193 will be executed from the directory from which
 194 .Nm find
 195 was executed.
 196 .It Ic -execdir Ar utility Op argument ... ;
 197 The
 198 .Ic \&-execdir
 199 primary is identical to the
 200 .Ic -exec
 201 primary with the exception that
 202 .Ar Utility
 203 will be executed from the directory that holds
 204 the current file.
 205 The filename substituted for
 206 the string ``{}'' is not qualified.
 207 .It Ic -fstype Ar type
 208 True if the file is contained in a file system of type
 209 .Ar type .
 210 The
 211 .Xr sysctl 8
 212 command can be used to find out the types of filesystems
 213 that are available on the system:
 214 .Bd -literal -offset indent
 215 sysctl vfs
 216 .Ed
 217 In addition, there are two pseudo-types, ``local'' and ``rdonly''.
 218 The former matches any file system physically mounted on the system where
 219 the
 220 .Nm find
 221 is being executed and the latter matches any file system which is
 222 mounted read-only.
 223 .It Ic -group Ar gname
 224 True if the file belongs to the group
 225 .Ar gname  .
 226 If
 227 .Ar gname
 228 is numeric and there is no such group name, then
 229 .Ar gname
 230 is treated as a group id.
 231 .It Ic -inum Ar n
 232 True if the file has inode number
 233 .Ar n  .
 234 .It Ic -links Ar n
 235 True if the file has
 236 .Ar n
 237 links.
 238 .It Ic -ls
 239 This primary always evaluates to true.
 240 The following information for the current file is written to standard output:
 241 its inode number, size in 512\-byte blocks, file permissions, number of hard
 242 links, owner, group, size in bytes, last modification time, and pathname.
 243 If the file is a block or character special file, the major and minor numbers
 244 will be displayed instead of the size in bytes.
 245 If the file is a symbolic link, the pathname of the linked\-to file will be
 246 displayed preceded by ``\->''.
 247 The format is identical to that produced by ``ls \-dgils''.
 248 .It Ic -mmin Ar n
 249 True if the difference between the file last modification time and the time
 250 .Nm find
 251 was started, rounded up to the next full minutes period, is
 252 .Ar n
 253 minutes periods.
 254 .It Ic -mtime Ar n
 255 True if the difference between the file last modification time and the time
 256 .Nm find
 257 was started, rounded up to the next full 24\-hour period, is
 258 .Ar n
 259 24\-hour periods.
 260 .It Ic \&-ok Ar utility Op argument ... ;
 261 The
 262 .Ic \&-ok
 263 primary is identical to the
 264 .Ic -exec
 265 primary with the exception that
 266 .Nm find
 267 requests user affirmation for the execution of the utility by printing
 268 a message to the terminal and reading a response.
 269 If the response is other than ``y'' the command is not executed and the
 270 value of the
 271 .Ar \&ok
 272 expression is false.
 273 .It Ic -name Ar pattern
 274 True if the last component of the pathname being examined matches
 275 .Ar pattern  .
 276 Special shell pattern matching characters (``['', ``]'', ``*'', and ``?'')
 277 may be used as part of
 278 .Ar pattern  .
 279 These characters may be matched explicitly by escaping them with a
 280 backslash (``\e'').
 281 .It Ic -newer Ar file
 282 True if the current file has a more recent last modification time than
 283 .Ar file  .
 284 .It Ic -nouser
 285 True if the file belongs to an unknown user.
 286 .It Ic -nogroup
 287 True if the file belongs to an unknown group.
 288 .It Ic -path Ar pattern
 289 True if the pathname being examined matches
 290 .Ar pattern  .
 291 Special shell pattern matching characters (``['', ``]'', ``*'', and ``?'')
 292 may be used as part of
 293 .Ar pattern  .
 294 These characters may be matched explicitly by escaping them with a
 295 backslash (``\e'').
 296 Slashes (``/'') are treated as normal characters and do not have to be
 297 matched explicitly.
 298 .It Xo
 299 .Ic -perm
 300 .Op Fl
 301 .Ar mode
 302 .Xc
 303 The
 304 .Ar mode
 305 may be either symbolic (see
 306 .Xr chmod  1  )
 307 or an octal number.
 308 If the mode is symbolic, a starting value of zero is assumed and the
 309 mode sets or clears permissions without regard to the process' file mode
 310 creation mask.
 311 If the mode is octal, only bits 07777
 312 .Pf ( Dv S_ISUID
 313 |
 314 .Dv S_ISGID
 315 |
 316 .Dv S_ISTXT
 317 |
 318 .Dv S_IRWXU
 319 |
 320 .Dv S_IRWXG
 321 |
 322 .Dv S_IRWXO )
 323 of the file's mode bits participate
 324 in the comparison.
 325 If the mode is preceded by a dash (``\-''), this primary evaluates to true
 326 if at least all of the bits in the mode are set in the file's mode bits.
 327 If the mode is not preceded by a dash, this primary evaluates to true if
 328 the bits in the mode exactly match the file's mode bits.
 329 Note, the first character of a symbolic mode may not be a dash (``\-'').
 330 .It Ic -flags Op Fl Ns Ar flags
 331 This primary evaluates to true if exactly those flags of the file are
 332 set which are also set using the specified
 333 .Ar flags
 334 (if these are not preceded by a dash (``\-''),
 335 or if they match the specified flags (if these are preceded by a dash).
 336 The
 337 .Ar flags
 338 are specified using symbolic names (see
 339 .Xr chflags 1  ).
 340 Note that this is different from
 341 .Ic -perm  ,
 342 which only allows you to specify flags which are set.
 343 .It Ic -print
 344 This primary always evaluates to true.
 345 It prints the pathname of the current file to standard output.
 346 If none of
 347 .Ic -exec ,
 348 .Ic -ls ,
 349 .Ic -print0 ,
 350 or
 351 .Ic \&-ok
 352 is specified, the given expression shall be effectively replaced by
 353 .Cm \&( Ns Ar given\& expression Ns Cm \&)
 354 .Ic -print .
 355 .It Ic -print0
 356 This primary always evaluates to true.
 357 It prints the pathname of the current file to standard output, followed by an
 358 .Tn ASCII
 359 .Tn NUL
 360 character (character code 0).
 361 .It Ic -prune
 362 This primary always evaluates to true.
 363 It causes
 364 .Nm find
 365 to not descend into the current file.
 366 Note, the
 367 .Ic -prune
 368 primary has no effect if the
 369 .Fl d
 370 option was specified.
 371 .It Ic -size Ar n Ns Op Cm c
 372 True if the file's size, rounded up, in 512\-byte blocks is
 373 .Ar n  .
 374 If
 375 .Ar n
 376 is followed by a ``c'', then the primary is true if the
 377 file's size is
 378 .Ar n
 379 bytes.
 380 .It Ic -type Ar t
 381 True if the file is of the specified type.
 382 Possible file types are as follows:
 383 .Pp
 384 .Bl -tag -width flag -offset indent -compact
 385 .It Cm b
 386 block special
 387 .It Cm c
 388 character special
 389 .It Cm d
 390 directory
 391 .It Cm f
 392 regular file
 393 .It Cm l
 394 symbolic link
 395 .It Cm p
 396 FIFO
 397 .It Cm s
 398 socket
 399 .El
 400 .Pp
 401 .It Ic -user Ar uname
 402 True if the file belongs to the user
 403 .Ar uname  .
 404 If
 405 .Ar uname
 406 is numeric and there is no such user name, then
 407 .Ar uname
 408 is treated as a user id.
 409 .El
 410 .Pp
 411 All primaries which take a numeric argument allow the number to be
 412 preceded by a plus sign (``+'') or a minus sign (``\-'').
 413 A preceding plus sign means ``more than n'', a preceding minus sign means
 414 ``less than n'' and neither means ``exactly n'' .
 415 .Sh OPERATORS
 416 The primaries may be combined using the following operators.
 417 The operators are listed in order of decreasing precedence.
 418 .Bl -tag -width (expression)
 419 .It Cm \&( Ar expression Cm \&)
 420 This evaluates to true if the parenthesized expression evaluates to
 421 true.
 422 .Pp
 423 .It Cm \&! Ar expression
 424 This is the unary
 425 .Tn NOT
 426 operator.
 427 It evaluates to true if the expression is false.
 428 .Pp
 429 .It Ar expression Cm -and Ar expression
 430 .It Ar expression expression
 431 The
 432 .Cm -and
 433 operator is the logical
 434 .Tn AND
 435 operator.
 436 As it is implied by the juxtaposition of two expressions it does not
 437 have to be specified.
 438 The expression evaluates to true if both expressions are true.
 439 The second expression is not evaluated if the first expression is false.
 440 .Pp
 441 .It Ar expression Cm -or Ar expression
 442 The
 443 .Cm -or
 444 operator is the logical
 445 .Tn OR
 446 operator.
 447 The expression evaluates to true if either the first or the second expression
 448 is true.
 449 The second expression is not evaluated if the first expression is true.
 450 .El
 451 .Pp
 452 All operands and primaries must be separate arguments to
 453 .Nm find  .
 454 Primaries which themselves take arguments expect each argument
 455 to be a separate argument to
 456 .Nm find  .
 457 .Sh EXAMPLES
 458 .Pp
 459 The following examples are shown as given to the shell:
 460 .Bl -tag -width findx
 461 .It Li "find  /  \e!  -name  \*q*.c\*q  -print"
 462 Print out a list of all the files whose names do not end in ``.c''.
 463 .It Li "find  /  -newer  ttt  -user  wnj  -print"
 464 Print out a list of all the files owned by user ``wnj'' that are newer
 465 than the file ``ttt''.
 466 .It Li "find  /  \e!  \e(  -newer  ttt  -user  wnj  \e)  -print"
 467 Print out a list of all the files which are not both newer than ``ttt''
 468 and owned by ``wnj''.
 469 .It Li "find  /  \e(  -newer  ttt  -or  -user wnj  \e)  -print"
 470 Print out a list of all the files that are either owned by ``wnj'' or
 471 that are newer than ``ttt''.
 472 .El
 473 .Sh SEE ALSO
 474 .Xr chflags 1 ,
 475 .Xr chmod 1 ,
 476 .Xr locate 1 ,
 477 .Xr whereis 1 ,
 478 .Xr which 1 ,
 479 .Xr stat 2 ,
 480 .Xr fts 3 ,
 481 .Xr getgrent 3 ,
 482 .Xr getpwent 3 ,
 483 .Xr strmode 3 ,
 484 .Xr symlink 7
 485 .Sh STANDARDS
 486 The
 487 .Nm find
 488 utility syntax is a superset of the syntax specified by the
 489 .St -p1003.2
 490 standard.
 491 .Pp
 492 All the single character options as well as the
 493 .Ic -inum ,
 494 .Ic -print0 ,
 495 .Ic -delete ,
 496 and
 497 .Ic -ls
 498 primaries are extensions to
 499 .St -p1003.2 .
 500 .Pp
 501 Historically, the
 502 .Fl d ,
 503 .Fl h
 504 and
 505 .Fl x
 506 options were implemented using the primaries ``\-depth'', ``\-follow'',
 507 and ``\-xdev''.
 508 These primaries always evaluated to true.
 509 As they were really global variables that took effect before the traversal
 510 began, some legal expressions could have unexpected results.
 511 An example is the expression ``\-print \-o \-depth''.
 512 As \-print always evaluates to true, the standard order of evaluation
 513 implies that \-depth would never be evaluated.
 514 This is not the case.
 515 .Pp
 516 The operator ``-or'' was implemented as ``\-o'', and the operator ``-and''
 517 was implemented as ``\-a''.
 518 .Pp
 519 Historic implementations of the
 520 .Ic exec
 521 and
 522 .Ic ok
 523 primaries did not replace the string ``{}'' in the utility name or the
 524 utility arguments if it had preceding or following non-whitespace characters.
 525 This version replaces it no matter where in the utility name or arguments
 526 it appears.
 527 .Sh BUGS
 528 The special characters used by
 529 .Nm find
 530 are also special characters to many shell programs.
 531 In particular, the characters ``*'', ``['', ``]'', ``?'', ``('', ``)'',
 532 ``!'', ``\e'' and ``;'' may have to be escaped from the shell.
 533 .Pp
 534 As there is no delimiter separating options and file names or file
 535 names and the
 536 .Ar expression ,
 537 it is difficult to specify files named ``-xdev'' or ``!''.
 538 These problems are handled by the
 539 .Fl f
 540 option and the
 541 .Xr getopt 3
 542 ``--'' construct.
 543 .Pp
 544 The
 545 .Ic -delete
 546 primary does not interact well with other options that cause the filesystem
 547 tree traversal options to be changed.
 548 .Sh HISTORY
 549 A
 550 .Nm
 551 command appeared in
 552 .At v1 .