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 -maxdepth Ar n
 249 True if the depth of the current file into the tree is less than or equal to
 250 .Ar n .
 251 .It Ic -mindepth Ar n
 252 True if the depth of the current file into the tree is greater than or equal to
 253 .Ar n .
 254 .It Ic -mmin 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 minutes period, is
 258 .Ar n
 259 minutes periods.
 260 .It Ic -mtime Ar n
 261 True if the difference between the file last modification time and the time
 262 .Nm find
 263 was started, rounded up to the next full 24\-hour period, is
 264 .Ar n
 265 24\-hour periods.
 266 .It Ic \&-ok Ar utility Op argument ... ;
 267 The
 268 .Ic \&-ok
 269 primary is identical to the
 270 .Ic -exec
 271 primary with the exception that
 272 .Nm find
 273 requests user affirmation for the execution of the utility by printing
 274 a message to the terminal and reading a response.
 275 If the response is other than ``y'' the command is not executed and the
 276 value of the
 277 .Ar \&ok
 278 expression is false.
 279 .It Ic -name Ar pattern
 280 True if the last component of the pathname being examined matches
 281 .Ar pattern  .
 282 Special shell pattern matching characters (``['', ``]'', ``*'', and ``?'')
 283 may be used as part of
 284 .Ar pattern  .
 285 These characters may be matched explicitly by escaping them with a
 286 backslash (``\e'').
 287 .It Ic -newer Ar file
 288 True if the current file has a more recent last modification time than
 289 .Ar file  .
 290 .It Ic -nouser
 291 True if the file belongs to an unknown user.
 292 .It Ic -nogroup
 293 True if the file belongs to an unknown group.
 294 .It Ic -path Ar pattern
 295 True if the pathname being examined matches
 296 .Ar pattern  .
 297 Special shell pattern matching characters (``['', ``]'', ``*'', and ``?'')
 298 may be used as part of
 299 .Ar pattern  .
 300 These characters may be matched explicitly by escaping them with a
 301 backslash (``\e'').
 302 Slashes (``/'') are treated as normal characters and do not have to be
 303 matched explicitly.
 304 .It Xo
 305 .Ic -perm
 306 .Op Fl
 307 .Ar mode
 308 .Xc
 309 The
 310 .Ar mode
 311 may be either symbolic (see
 312 .Xr chmod  1  )
 313 or an octal number.
 314 If the mode is symbolic, a starting value of zero is assumed and the
 315 mode sets or clears permissions without regard to the process' file mode
 316 creation mask.
 317 If the mode is octal, only bits 07777
 318 .Pf ( Dv S_ISUID
 319 |
 320 .Dv S_ISGID
 321 |
 322 .Dv S_ISTXT
 323 |
 324 .Dv S_IRWXU
 325 |
 326 .Dv S_IRWXG
 327 |
 328 .Dv S_IRWXO )
 329 of the file's mode bits participate
 330 in the comparison.
 331 If the mode is preceded by a dash (``\-''), this primary evaluates to true
 332 if at least all of the bits in the mode are set in the file's mode bits.
 333 If the mode is preceded by a plus (``\+''), this primary evaluates to true
 334 if any of the bits in the mode are set in the file's mode bits.
 335 Otherwise, this primary evaluates to true if
 336 the bits in the mode exactly match the file's mode bits.
 337 Note, the first character of a symbolic mode may not be a dash (``\-'').
 338 .It Ic -flags Op Fl Ns Ar flags
 339 This primary evaluates to true if exactly those flags of the file are
 340 set which are also set using the specified
 341 .Ar flags
 342 (if these are not preceded by a dash (``\-''),
 343 or if they match the specified flags (if these are preceded by a dash).
 344 The
 345 .Ar flags
 346 are specified using symbolic names (see
 347 .Xr chflags 1  ).
 348 Note that this is different from
 349 .Ic -perm  ,
 350 which only allows you to specify flags which are set.
 351 .It Ic -print
 352 This primary always evaluates to true.
 353 It prints the pathname of the current file to standard output.
 354 If none of
 355 .Ic -exec ,
 356 .Ic -ls ,
 357 .Ic -print0 ,
 358 or
 359 .Ic \&-ok
 360 is specified, the given expression shall be effectively replaced by
 361 .Cm \&( Ns Ar given\& expression Ns Cm \&)
 362 .Ic -print .
 363 .It Ic -print0
 364 This primary always evaluates to true.
 365 It prints the pathname of the current file to standard output, followed by an
 366 .Tn ASCII
 367 .Tn NUL
 368 character (character code 0).
 369 .It Ic -prune
 370 This primary always evaluates to true.
 371 It causes
 372 .Nm find
 373 to not descend into the current file.
 374 Note, the
 375 .Ic -prune
 376 primary has no effect if the
 377 .Fl d
 378 option was specified.
 379 .It Ic -size Ar n Ns Op Cm c
 380 True if the file's size, rounded up, in 512\-byte blocks is
 381 .Ar n  .
 382 If
 383 .Ar n
 384 is followed by a ``c'', then the primary is true if the
 385 file's size is
 386 .Ar n
 387 bytes.
 388 .It Ic -type Ar t
 389 True if the file is of the specified type.
 390 Possible file types are as follows:
 391 .Pp
 392 .Bl -tag -width flag -offset indent -compact
 393 .It Cm b
 394 block special
 395 .It Cm c
 396 character special
 397 .It Cm d
 398 directory
 399 .It Cm f
 400 regular file
 401 .It Cm l
 402 symbolic link
 403 .It Cm p
 404 FIFO
 405 .It Cm s
 406 socket
 407 .El
 408 .Pp
 409 .It Ic -user Ar uname
 410 True if the file belongs to the user
 411 .Ar uname  .
 412 If
 413 .Ar uname
 414 is numeric and there is no such user name, then
 415 .Ar uname
 416 is treated as a user id.
 417 .El
 418 .Pp
 419 All primaries which take a numeric argument allow the number to be
 420 preceded by a plus sign (``+'') or a minus sign (``\-'').
 421 A preceding plus sign means ``more than n'', a preceding minus sign means
 422 ``less than n'' and neither means ``exactly n'' .
 423 .Sh OPERATORS
 424 The primaries may be combined using the following operators.
 425 The operators are listed in order of decreasing precedence.
 426 .Bl -tag -width (expression)
 427 .It Cm \&( Ar expression Cm \&)
 428 This evaluates to true if the parenthesized expression evaluates to
 429 true.
 430 .Pp
 431 .It Cm \&! Ar expression
 432 This is the unary
 433 .Tn NOT
 434 operator.
 435 It evaluates to true if the expression is false.
 436 .Pp
 437 .It Ar expression Cm -and Ar expression
 438 .It Ar expression expression
 439 The
 440 .Cm -and
 441 operator is the logical
 442 .Tn AND
 443 operator.
 444 As it is implied by the juxtaposition of two expressions it does not
 445 have to be specified.
 446 The expression evaluates to true if both expressions are true.
 447 The second expression is not evaluated if the first expression is false.
 448 .Pp
 449 .It Ar expression Cm -or Ar expression
 450 The
 451 .Cm -or
 452 operator is the logical
 453 .Tn OR
 454 operator.
 455 The expression evaluates to true if either the first or the second expression
 456 is true.
 457 The second expression is not evaluated if the first expression is true.
 458 .El
 459 .Pp
 460 All operands and primaries must be separate arguments to
 461 .Nm find  .
 462 Primaries which themselves take arguments expect each argument
 463 to be a separate argument to
 464 .Nm find  .
 465 .Sh EXAMPLES
 466 .Pp
 467 The following examples are shown as given to the shell:
 468 .Bl -tag -width findx
 469 .It Li "find  /  \e!  -name  \*q*.c\*q  -print"
 470 Print out a list of all the files whose names do not end in ``.c''.
 471 .It Li "find  /  -newer  ttt  -user  wnj  -print"
 472 Print out a list of all the files owned by user ``wnj'' that are newer
 473 than the file ``ttt''.
 474 .It Li "find  /  \e!  \e(  -newer  ttt  -user  wnj  \e)  -print"
 475 Print out a list of all the files which are not both newer than ``ttt''
 476 and owned by ``wnj''.
 477 .It Li "find  /  \e(  -newer  ttt  -or  -user wnj  \e)  -print"
 478 Print out a list of all the files that are either owned by ``wnj'' or
 479 that are newer than ``ttt''.
 480 .El
 481 .Sh SEE ALSO
 482 .Xr chflags 1 ,
 483 .Xr chmod 1 ,
 484 .Xr locate 1 ,
 485 .Xr whereis 1 ,
 486 .Xr which 1 ,
 487 .Xr stat 2 ,
 488 .Xr fts 3 ,
 489 .Xr getgrent 3 ,
 490 .Xr getpwent 3 ,
 491 .Xr strmode 3 ,
 492 .Xr symlink 7
 493 .Sh STANDARDS
 494 The
 495 .Nm find
 496 utility syntax is a superset of the syntax specified by the
 497 .St -p1003.2
 498 standard.
 499 .Pp
 500 All the single character options as well as the
 501 .Ic -inum ,
 502 .Ic -print0 ,
 503 .Ic -delete ,
 504 and
 505 .Ic -ls
 506 primaries are extensions to
 507 .St -p1003.2 .
 508 .Pp
 509 Historically, the
 510 .Fl d ,
 511 .Fl h
 512 and
 513 .Fl x
 514 options were implemented using the primaries ``\-depth'', ``\-follow'',
 515 and ``\-xdev''.
 516 These primaries always evaluated to true.
 517 As they were really global variables that took effect before the traversal
 518 began, some legal expressions could have unexpected results.
 519 An example is the expression ``\-print \-o \-depth''.
 520 As \-print always evaluates to true, the standard order of evaluation
 521 implies that \-depth would never be evaluated.
 522 This is not the case.
 523 .Pp
 524 The operator ``-or'' was implemented as ``\-o'', and the operator ``-and''
 525 was implemented as ``\-a''.
 526 .Pp
 527 Historic implementations of the
 528 .Ic exec
 529 and
 530 .Ic ok
 531 primaries did not replace the string ``{}'' in the utility name or the
 532 utility arguments if it had preceding or following non-whitespace characters.
 533 This version replaces it no matter where in the utility name or arguments
 534 it appears.
 535 .Sh BUGS
 536 The special characters used by
 537 .Nm find
 538 are also special characters to many shell programs.
 539 In particular, the characters ``*'', ``['', ``]'', ``?'', ``('', ``)'',
 540 ``!'', ``\e'' and ``;'' may have to be escaped from the shell.
 541 .Pp
 542 As there is no delimiter separating options and file names or file
 543 names and the
 544 .Ar expression ,
 545 it is difficult to specify files named ``-xdev'' or ``!''.
 546 These problems are handled by the
 547 .Fl f
 548 option and the
 549 .Xr getopt 3
 550 ``--'' construct.
 551 .Pp
 552 The
 553 .Ic -delete
 554 primary does not interact well with other options that cause the filesystem
 555 tree traversal options to be changed.
 556 .Sh HISTORY
 557 A
 558 .Nm
 559 command appeared in
 560 .At v1 .