usr.bin/find/find.1

   1 .\" Copyright (c) 1990, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" This code is derived from software contributed to Berkeley by
   5 .\" the Institute of Electrical and Electronics Engineers, Inc.
   6 .\"
   7 .\" Redistribution and use in source and binary forms, with or without
   8 .\" modification, are permitted provided that the following conditions
   9 .\" are met:
  10 .\" 1. Redistributions of source code must retain the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer.
  12 .\" 2. Redistributions in binary form must reproduce the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer in the
  14 .\"    documentation and/or other materials provided with the distribution.
  15 .\" 4. Neither the name of the University nor the names of its contributors
  16 .\"    may be used to endorse or promote products derived from this software
  17 .\"    without specific prior written permission.
  18 .\"
  19 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  20 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  21 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  22 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  23 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  24 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  25 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  26 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  27 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  28 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  29 .\" SUCH DAMAGE.
  30 .\"
  31 .\"     @(#)find.1      8.7 (Berkeley) 5/9/95
  32 .\" $FreeBSD$
  33 .\"
  34 .Dd June 13, 2012
  35 .Dt FIND 1
  36 .Os
  37 .Sh NAME
  38 .Nm find
  39 .Nd walk a file hierarchy
  40 .Sh SYNOPSIS
  41 .Nm
  42 .Op Fl H | Fl L | Fl P
  43 .Op Fl EXdsx
  44 .Op Fl f Ar path
  45 .Ar path ...
  46 .Op Ar expression
  47 .Nm
  48 .Op Fl H | Fl L | Fl P
  49 .Op Fl EXdsx
  50 .Fl f Ar path
  51 .Op Ar path ...
  52 .Op Ar expression
  53 .Sh DESCRIPTION
  54 The
  55 .Nm
  56 utility recursively descends the directory tree for each
  57 .Ar path
  58 listed, evaluating an
  59 .Ar expression
  60 (composed of the
  61 .Dq primaries
  62 and
  63 .Dq operands
  64 listed below) in terms
  65 of each file in the tree.
  66 .Pp
  67 The options are as follows:
  68 .Bl -tag -width indent
  69 .It Fl E
  70 Interpret regular expressions followed by
  71 .Ic -regex
  72 and
  73 .Ic -iregex
  74 primaries as extended (modern) regular expressions rather than basic
  75 regular expressions (BRE's).
  76 The
  77 .Xr re_format 7
  78 manual page fully describes both formats.
  79 .It Fl H
  80 Cause the file information and file type (see
  81 .Xr stat 2 )
  82 returned for each symbolic link specified on the command line to be
  83 those of the file referenced by the link, not the link itself.
  84 If the referenced file does not exist, the file information and type will
  85 be for the link itself.
  86 File information of all symbolic links not on
  87 the command line is that of the link itself.
  88 .It Fl L
  89 Cause the file information and file type (see
  90 .Xr stat 2 )
  91 returned for each symbolic link to be those of the file referenced by the
  92 link, not the link itself.
  93 If the referenced file does not exist, the file information and type will
  94 be for the link itself.
  95 .Pp
  96 This option is equivalent to the deprecated
  97 .Ic -follow
  98 primary.
  99 .It Fl P
 100 Cause the file information and file type (see
 101 .Xr stat 2 )
 102 returned for each symbolic link to be those of the link itself.
 103 This is the default.
 104 .It Fl X
 105 Permit
 106 .Nm
 107 to be safely used in conjunction with
 108 .Xr xargs 1 .
 109 If a file name contains any of the delimiting characters used by
 110 .Xr xargs 1 ,
 111 a diagnostic message is displayed on standard error, and the file
 112 is skipped.
 113 The delimiting characters include single
 114 .Pq Dq Li " ' "
 115 and double
 116 .Pq Dq Li " \*q "
 117 quotes, backslash
 118 .Pq Dq Li \e ,
 119 space, tab and newline characters.
 120 .Pp
 121 However, you may wish to consider the
 122 .Fl print0
 123 primary in conjunction with
 124 .Dq Nm xargs Fl 0
 125 as an effective alternative.
 126 .It Fl d
 127 Cause
 128 .Nm
 129 to perform a depth-first traversal.
 130 .Pp
 131 This option is a BSD-specific equivalent of the
 132 .Ic -depth
 133 primary specified by
 134 .St -p1003.1-2001 .
 135 Refer to its description under
 136 .Sx PRIMARIES
 137 for more information.
 138 .It Fl s
 139 Cause
 140 .Nm
 141 to traverse the file hierarchies in lexicographical order,
 142 i.e., alphabetical order within each directory.
 143 Note:
 144 .Ql find -s
 145 and
 146 .Ql "find | sort"
 147 may give different results.
 148 .It Fl x
 149 Prevent
 150 .Nm
 151 from descending into directories that have a device number different
 152 than that of the file from which the descent began.
 153 .Pp
 154 This option is equivalent to the deprecated
 155 .Ic -xdev
 156 primary.
 157 .El
 158 .Sh PRIMARIES
 159 .Pp
 160 All primaries which take a numeric argument allow the number to be
 161 preceded by a plus sign
 162 .Pq Dq Li +
 163 or a minus sign
 164 .Pq Dq Li - .
 165 A preceding plus sign means
 166 .Dq more than n ,
 167 a preceding minus sign means
 168 .Dq less than n
 169 and neither means
 170 .Dq exactly n .
 171 .Bl -tag -width indent
 172 .It Ic -Bmin Ar n
 173 True if the difference between the time of a file's inode creation
 174 and the time
 175 .Nm
 176 was started, rounded up to the next full minute, is
 177 .Ar n
 178 minutes.
 179 .It Ic -Bnewer Ar file
 180 Same as
 181 .Ic -newerBm .
 182 .It Ic -Btime Ar n Ns Op Cm smhdw
 183 If no units are specified, this primary evaluates to
 184 true if the difference between the time of a file's inode creation
 185 and the time
 186 .Nm
 187 was started, rounded up to the next full 24-hour period, is
 188 .Ar n
 189 24-hour periods.
 190 .Pp
 191 If units are specified, this primary evaluates to
 192 true if the difference between the time of a file's inode creation
 193 and the time
 194 .Nm
 195 was started is exactly
 196 .Ar n
 197 units.
 198 Please refer to the
 199 .Ic -atime
 200 primary description for information on supported time units.
 201 .It Ic -acl
 202 May be used in conjunction with other primaries to locate
 203 files with extended ACLs.
 204 See
 205 .Xr acl 3
 206 for more information.
 207 .It Ic -amin Ar n
 208 True if the difference between the file last access time and the time
 209 .Nm
 210 was started, rounded up to the next full minute, is
 211 .Ar n
 212 minutes.
 213 .It Ic -anewer Ar file
 214 Same as
 215 .Ic -neweram .
 216 .It Ic -atime Ar n Ns Op Cm smhdw
 217 If no units are specified, this primary evaluates to
 218 true if the difference between the file last access time and the time
 219 .Nm
 220 was started, rounded up to the next full 24-hour period, is
 221 .Ar n
 222 24-hour periods.
 223 .Pp
 224 If units are specified, this primary evaluates to
 225 true if the difference between the file last access time and the time
 226 .Nm
 227 was started is exactly
 228 .Ar n
 229 units.
 230 Possible time units are as follows:
 231 .Pp
 232 .Bl -tag -width indent -compact
 233 .It Cm s
 234 second
 235 .It Cm m
 236 minute (60 seconds)
 237 .It Cm h
 238 hour (60 minutes)
 239 .It Cm d
 240 day (24 hours)
 241 .It Cm w
 242 week (7 days)
 243 .El
 244 .Pp
 245 Any number of units may be combined in one
 246 .Ic -atime
 247 argument, for example,
 248 .Dq Li "-atime -1h30m" .
 249 Units are probably only useful when used in conjunction with the
 250 .Cm +
 251 or
 252 .Cm -
 253 modifier.
 254 .It Ic -cmin Ar n
 255 True if the difference between the time of last change of file status
 256 information and the time
 257 .Nm
 258 was started, rounded up to the next full minute, is
 259 .Ar n
 260 minutes.
 261 .It Ic -cnewer Ar file
 262 Same as
 263 .Ic -newercm .
 264 .It Ic -ctime Ar n Ns Op Cm smhdw
 265 If no units are specified, this primary evaluates to
 266 true if the difference between the time of last change of file status
 267 information and the time
 268 .Nm
 269 was started, rounded up to the next full 24-hour period, is
 270 .Ar n
 271 24-hour periods.
 272 .Pp
 273 If units are specified, this primary evaluates to
 274 true if the difference between the time of last change of file status
 275 information and the time
 276 .Nm
 277 was started is exactly
 278 .Ar n
 279 units.
 280 Please refer to the
 281 .Ic -atime
 282 primary description for information on supported time units.
 283 .It Ic -d
 284 Non-portable, BSD-specific version of
 285 .Ic depth .
 286 GNU find implements this as a primary in mistaken emulation of
 287 .Fx
 288 .Xr find 1 .
 289 .It Ic -delete
 290 Delete found files and/or directories.
 291 Always returns true.
 292 This executes
 293 from the current working directory as
 294 .Nm
 295 recurses down the tree.
 296 It will not attempt to delete a filename with a
 297 .Dq Pa /
 298 character in its pathname relative to
 299 .Dq Pa \&.
 300 for security reasons.
 301 Depth-first traversal processing is implied by this option.
 302 Following symlinks is incompatible with this option.
 303 .It Ic -depth
 304 Always true;
 305 same as the non-portable
 306 .Fl d
 307 option.
 308 Cause
 309 .Nm
 310 to perform a depth-first traversal, i.e., directories
 311 are visited in post-order and all entries in a directory will be acted
 312 on before the directory itself.
 313 By default,
 314 .Nm
 315 visits directories in pre-order, i.e., before their contents.
 316 Note, the default is
 317 .Em not
 318 a breadth-first traversal.
 319 .Pp
 320 The
 321 .Ic -depth
 322 primary
 323 can be useful when
 324 .Nm
 325 is used with
 326 .Xr cpio 1
 327 to process files that are contained in directories with unusual permissions.
 328 It ensures that you have write permission while you are placing files in a
 329 directory, then sets the directory's permissions as the last thing.
 330 .It Ic -depth Ar n
 331 True if the depth of the file relative to the starting point of the traversal
 332 is
 333 .Ar n .
 334 .It Ic -empty
 335 True if the current file or directory is empty.
 336 .It Ic -exec Ar utility Oo Ar argument ... Oc Li \&;
 337 True if the program named
 338 .Ar utility
 339 returns a zero value as its exit status.
 340 Optional
 341 .Ar arguments
 342 may be passed to the utility.
 343 The expression must be terminated by a semicolon
 344 .Pq Dq Li \&; .
 345 If you invoke
 346 .Nm
 347 from a shell you may need to quote the semicolon if the shell would
 348 otherwise treat it as a control operator.
 349 If the string
 350 .Dq Li {}
 351 appears anywhere in the utility name or the
 352 arguments it is replaced by the pathname of the current file.
 353 .Ar Utility
 354 will be executed from the directory from which
 355 .Nm
 356 was executed.
 357 .Ar Utility
 358 and
 359 .Ar arguments
 360 are not subject to the further expansion of shell patterns
 361 and constructs.
 362 .It Ic -exec Ar utility Oo Ar argument ... Oc Li {} +
 363 Same as
 364 .Ic -exec ,
 365 except that
 366 .Dq Li {}
 367 is replaced with as many pathnames as possible for each invocation of
 368 .Ar utility .
 369 This behaviour is similar to that of
 370 .Xr xargs 1 .
 371 .It Ic -execdir Ar utility Oo Ar argument ... Oc Li \&;
 372 The
 373 .Ic -execdir
 374 primary is identical to the
 375 .Ic -exec
 376 primary with the exception that
 377 .Ar utility
 378 will be executed from the directory that holds
 379 the current file.
 380 The filename substituted for
 381 the string
 382 .Dq Li {}
 383 is not qualified.
 384 .It Ic -execdir Ar utility Oo Ar argument ... Oc Li {} +
 385 Same as
 386 .Ic -execdir ,
 387 except that
 388 .Dq Li {}
 389 is replaced with as many pathnames as possible for each invocation of
 390 .Ar utility .
 391 This behaviour is similar to that of
 392 .Xr xargs 1 .
 393 .It Ic -flags Oo Cm - Ns | Ns Cm + Oc Ns Ar flags , Ns Ar notflags
 394 The flags are specified using symbolic names (see
 395 .Xr chflags 1 ) .
 396 Those with the
 397 .Qq Li no
 398 prefix (except
 399 .Qq Li nodump )
 400 are said to be
 401 .Ar notflags .
 402 Flags in
 403 .Ar flags
 404 are checked to be set, and flags in
 405 .Ar notflags
 406 are checked to be not set.
 407 Note that this is different from
 408 .Ic -perm ,
 409 which only allows the user to specify mode bits that are set.
 410 .Pp
 411 If flags are preceded by a dash
 412 .Pq Dq Li - ,
 413 this primary evaluates to true
 414 if at least all of the bits in
 415 .Ar flags
 416 and none of the bits in
 417 .Ar notflags
 418 are set in the file's flags bits.
 419 If flags are preceded by a plus
 420 .Pq Dq Li + ,
 421 this primary evaluates to true
 422 if any of the bits in
 423 .Ar flags
 424 is set in the file's flags bits,
 425 or any of the bits in
 426 .Ar notflags
 427 is not set in the file's flags bits.
 428 Otherwise,
 429 this primary evaluates to true
 430 if the bits in
 431 .Ar flags
 432 exactly match the file's flags bits,
 433 and none of the
 434 .Ar flags
 435 bits match those of
 436 .Ar notflags .
 437 .It Ic -fstype Ar type
 438 True if the file is contained in a file system of type
 439 .Ar type .
 440 The
 441 .Xr lsvfs 1
 442 command can be used to find out the types of file systems
 443 that are available on the system.
 444 In addition, there are two pseudo-types,
 445 .Dq Li local
 446 and
 447 .Dq Li rdonly .
 448 The former matches any file system physically mounted on the system where
 449 the
 450 .Nm
 451 is being executed and the latter matches any file system which is
 452 mounted read-only.
 453 .It Ic -gid Ar gname
 454 The same thing as
 455 .Ar -group Ar gname
 456 for compatibility with GNU find.
 457 GNU find imposes a restriction that
 458 .Ar gname
 459 is numeric, while
 460 .Xr find 1
 461 does not.
 462 .It Ic -group Ar gname
 463 True if the file belongs to the group
 464 .Ar gname .
 465 If
 466 .Ar gname
 467 is numeric and there is no such group name, then
 468 .Ar gname
 469 is treated as a group ID.
 470 .It Ic -ignore_readdir_race
 471 This option is for GNU find compatibility and is ignored.
 472 .It Ic -ilname Ar pattern
 473 Like
 474 .Ic -lname ,
 475 but the match is case insensitive.
 476 This is a GNU find extension.
 477 .It Ic -iname Ar pattern
 478 Like
 479 .Ic -name ,
 480 but the match is case insensitive.
 481 .It Ic -inum Ar n
 482 True if the file has inode number
 483 .Ar n .
 484 .It Ic -ipath Ar pattern
 485 Like
 486 .Ic -path ,
 487 but the match is case insensitive.
 488 .It Ic -iregex Ar pattern
 489 Like
 490 .Ic -regex ,
 491 but the match is case insensitive.
 492 .It Ic -iwholename Ar pattern
 493 The same thing as
 494 .Ic -ipath ,
 495 for GNU find compatibility.
 496 .It Ic -links Ar n
 497 True if the file has
 498 .Ar n
 499 links.
 500 .It Ic -lname Ar pattern
 501 Like
 502 .Ic -name ,
 503 but the contents of the symbolic link are matched instead of the file
 504 name.
 505 This is a GNU find extension.
 506 .It Ic -ls
 507 This primary always evaluates to true.
 508 The following information for the current file is written to standard output:
 509 its inode number, size in 512-byte blocks, file permissions, number of hard
 510 links, owner, group, size in bytes, last modification time, and pathname.
 511 If the file is a block or character special file, the major and minor numbers
 512 will be displayed instead of the size in bytes.
 513 If the file is a symbolic link, the pathname of the linked-to file will be
 514 displayed preceded by
 515 .Dq Li -> .
 516 The format is identical to that produced by
 517 .Bk -words
 518 .Dq Nm ls Fl dgils .
 519 .Ek
 520 .It Ic -maxdepth Ar n
 521 Always true; descend at most
 522 .Ar n
 523 directory levels below the command line arguments.
 524 If any
 525 .Ic -maxdepth
 526 primary is specified, it applies to the entire expression even if it would
 527 not normally be evaluated.
 528 .Dq Ic -maxdepth Li 0
 529 limits the whole search to the command line arguments.
 530 .It Ic -mindepth Ar n
 531 Always true; do not apply any tests or actions at levels less than
 532 .Ar n .
 533 If any
 534 .Ic -mindepth
 535 primary is specified, it applies to the entire expression even if it would
 536 not normally be evaluated.
 537 .Dq Ic -mindepth Li 1
 538 processes all but the command line arguments.
 539 .It Ic -mmin Ar n
 540 True if the difference between the file last modification time and the time
 541 .Nm
 542 was started, rounded up to the next full minute, is
 543 .Ar n
 544 minutes.
 545 .It Ic -mnewer Ar file
 546 Same as
 547 .Ic -newer .
 548 .It Ic -mount
 549 The same thing as
 550 .Ic -xdev ,
 551 for GNU find compatibility.
 552 .It Ic -mtime Ar n Ns Op Cm smhdw
 553 If no units are specified, this primary evaluates to
 554 true if the difference between the file last modification time and the time
 555 .Nm
 556 was started, rounded up to the next full 24-hour period, is
 557 .Ar n
 558 24-hour periods.
 559 .Pp
 560 If units are specified, this primary evaluates to
 561 true if the difference between the file last modification time and the time
 562 .Nm
 563 was started is exactly
 564 .Ar n
 565 units.
 566 Please refer to the
 567 .Ic -atime
 568 primary description for information on supported time units.
 569 .It Ic -name Ar pattern
 570 True if the last component of the pathname being examined matches
 571 .Ar pattern .
 572 Special shell pattern matching characters
 573 .Dq ( Li \&[ ,
 574 .Dq Li \&] ,
 575 .Dq Li * ,
 576 and
 577 .Dq Li \&? )
 578 may be used as part of
 579 .Ar pattern .
 580 These characters may be matched explicitly by escaping them with a
 581 backslash
 582 .Pq Dq Li \e .
 583 .It Ic -newer Ar file
 584 True if the current file has a more recent last modification time than
 585 .Ar file .
 586 .It Ic -newer Ns Ar X Ns Ar Y Ar file
 587 True if the current file has a more recent last access time
 588 .Pq Ar X Ns = Ns Cm a ,
 589 inode creation time
 590 .Pq Ar X Ns = Ns Cm B ,
 591 change time
 592 .Pq Ar X Ns = Ns Cm c ,
 593 or modification time
 594 .Pq Ar X Ns = Ns Cm m
 595 than the last access time
 596 .Pq Ar Y Ns = Ns Cm a ,
 597 inode creation time
 598 .Pq Ar Y Ns = Ns Cm B ,
 599 change time
 600 .Pq Ar Y Ns = Ns Cm c ,
 601 or modification time
 602 .Pq Ar Y Ns = Ns Cm m
 603 of
 604 .Ar file .
 605 In addition, if
 606 .Ar Y Ns = Ns Cm t ,
 607 then
 608 .Ar file
 609 is instead interpreted as a direct date specification of the form
 610 understood by
 611 .Xr cvs 1 .
 612 Note that
 613 .Ic -newermm
 614 is equivalent to
 615 .Ic -newer .
 616 .It Ic -nogroup
 617 True if the file belongs to an unknown group.
 618 .It Ic -noignore_readdir_race
 619 This option is for GNU find compatibility and is ignored.
 620 .It Ic -noleaf
 621 This option is for GNU find compatibility.
 622 In GNU find it disables an optimization not relevant to
 623 .Xr find 1 ,
 624 so it is ignored.
 625 .It Ic -nouser
 626 True if the file belongs to an unknown user.
 627 .It Ic -ok Ar utility Oo Ar argument ... Oc Li \&;
 628 The
 629 .Ic -ok
 630 primary is identical to the
 631 .Ic -exec
 632 primary with the exception that
 633 .Nm
 634 requests user affirmation for the execution of the
 635 .Ar utility
 636 by printing
 637 a message to the terminal and reading a response.
 638 If the response is not affirmative
 639 .Ql ( y
 640 in the
 641 .Dq Li POSIX
 642 locale),
 643 the command is not executed and the
 644 value of the
 645 .Ic -ok
 646 expression is false.
 647 .It Ic -okdir Ar utility Oo Ar argument ... Oc Li \&;
 648 The
 649 .Ic -okdir
 650 primary is identical to the
 651 .Ic -execdir
 652 primary with the same exception as described for the
 653 .Ic -ok
 654 primary.
 655 .It Ic -path Ar pattern
 656 True if the pathname being examined matches
 657 .Ar pattern .
 658 Special shell pattern matching characters
 659 .Dq ( Li \&[ ,
 660 .Dq Li \&] ,
 661 .Dq Li * ,
 662 and
 663 .Dq Li \&? )
 664 may be used as part of
 665 .Ar pattern .
 666 These characters may be matched explicitly by escaping them with a
 667 backslash
 668 .Pq Dq Li \e .
 669 Slashes
 670 .Pq Dq Li /
 671 are treated as normal characters and do not have to be
 672 matched explicitly.
 673 .It Ic -perm Oo Cm - Ns | Ns Cm + Oc Ns Ar mode
 674 The
 675 .Ar mode
 676 may be either symbolic (see
 677 .Xr chmod 1 )
 678 or an octal number.
 679 If the
 680 .Ar mode
 681 is symbolic, a starting value of zero is assumed and the
 682 .Ar mode
 683 sets or clears permissions without regard to the process' file mode
 684 creation mask.
 685 If the
 686 .Ar mode
 687 is octal, only bits 07777
 688 .Pq Dv S_ISUID | S_ISGID | S_ISTXT | S_IRWXU | S_IRWXG | S_IRWXO
 689 of the file's mode bits participate
 690 in the comparison.
 691 If the
 692 .Ar mode
 693 is preceded by a dash
 694 .Pq Dq Li - ,
 695 this primary evaluates to true
 696 if at least all of the bits in the
 697 .Ar mode
 698 are set in the file's mode bits.
 699 If the
 700 .Ar mode
 701 is preceded by a plus
 702 .Pq Dq Li + ,
 703 this primary evaluates to true
 704 if any of the bits in the
 705 .Ar mode
 706 are set in the file's mode bits.
 707 Otherwise, this primary evaluates to true if
 708 the bits in the
 709 .Ar mode
 710 exactly match the file's mode bits.
 711 Note, the first character of a symbolic mode may not be a dash
 712 .Pq Dq Li - .
 713 .It Ic -print
 714 This primary always evaluates to true.
 715 It prints the pathname of the current file to standard output.
 716 If none of
 717 .Ic -exec , -ls , -print0 ,
 718 or
 719 .Ic -ok
 720 is specified, the given expression shall be effectively replaced by
 721 .Cm \&( Ar "given expression" Cm \&) Ic -print .
 722 .It Ic -print0
 723 This primary always evaluates to true.
 724 It prints the pathname of the current file to standard output, followed by an
 725 .Tn ASCII
 726 .Dv NUL
 727 character (character code 0).
 728 .It Ic -prune
 729 This primary always evaluates to true.
 730 It causes
 731 .Nm
 732 to not descend into the current file.
 733 Note, the
 734 .Ic -prune
 735 primary has no effect if the
 736 .Fl d
 737 option was specified.
 738 .It Ic -regex Ar pattern
 739 True if the whole path of the file matches
 740 .Ar pattern
 741 using regular expression.
 742 To match a file named
 743 .Dq Pa ./foo/xyzzy ,
 744 you can use the regular expression
 745 .Dq Li ".*/[xyz]*"
 746 or
 747 .Dq Li ".*/foo/.*" ,
 748 but not
 749 .Dq Li xyzzy
 750 or
 751 .Dq Li /foo/ .
 752 .It Ic -samefile Ar name
 753 True if the file is a hard link to
 754 .Ar name .
 755 If the command option
 756 .Ic -L
 757 is specified, it is also true if the file is a symbolic link and
 758 points to
 759 .Ar name .
 760 .It Ic -size Ar n Ns Op Cm ckMGTP
 761 True if the file's size, rounded up, in 512-byte blocks is
 762 .Ar n .
 763 If
 764 .Ar n
 765 is followed by a
 766 .Cm c ,
 767 then the primary is true if the
 768 file's size is
 769 .Ar n
 770 bytes (characters).
 771 Similarly if
 772 .Ar n
 773 is followed by a scale indicator then the file's size is compared to
 774 .Ar n
 775 scaled as:
 776 .Pp
 777 .Bl -tag -width indent -compact
 778 .It Cm k
 779 kilobytes (1024 bytes)
 780 .It Cm M
 781 megabytes (1024 kilobytes)
 782 .It Cm G
 783 gigabytes (1024 megabytes)
 784 .It Cm T
 785 terabytes (1024 gigabytes)
 786 .It Cm P
 787 petabytes (1024 terabytes)
 788 .El
 789 .It Ic -type Ar t
 790 True if the file is of the specified type.
 791 Possible file types are as follows:
 792 .Pp
 793 .Bl -tag -width indent -compact
 794 .It Cm b
 795 block special
 796 .It Cm c
 797 character special
 798 .It Cm d
 799 directory
 800 .It Cm f
 801 regular file
 802 .It Cm l
 803 symbolic link
 804 .It Cm p
 805 FIFO
 806 .It Cm s
 807 socket
 808 .El
 809 .It Ic -uid Ar uname
 810 The same thing as
 811 .Ar -user Ar uname
 812 for compatibility with GNU find.
 813 GNU find imposes a restriction that
 814 .Ar uname
 815 is numeric, while
 816 .Xr find 1
 817 does not.
 818 .It Ic -user Ar uname
 819 True if the file belongs to the user
 820 .Ar uname .
 821 If
 822 .Ar uname
 823 is numeric and there is no such user name, then
 824 .Ar uname
 825 is treated as a user ID.
 826 .It Ic -wholename Ar pattern
 827 The same thing as
 828 .Ic -path ,
 829 for GNU find compatibility.
 830 .El
 831 .Sh OPERATORS
 832 The primaries may be combined using the following operators.
 833 The operators are listed in order of decreasing precedence.
 834 .Pp
 835 .Bl -tag -width indent -compact
 836 .It Cm \&( Ar expression Cm \&)
 837 This evaluates to true if the parenthesized expression evaluates to
 838 true.
 839 .Pp
 840 .It Cm \&! Ar expression
 841 .It Cm -not Ar expression
 842 This is the unary
 843 .Tn NOT
 844 operator.
 845 It evaluates to true if the expression is false.
 846 .Pp
 847 .It Cm -false
 848 Always false.
 849 .It Cm -true
 850 Always true.
 851 .Pp
 852 .It Ar expression Cm -and Ar expression
 853 .It Ar expression expression
 854 The
 855 .Cm -and
 856 operator is the logical
 857 .Tn AND
 858 operator.
 859 As it is implied by the juxtaposition of two expressions it does not
 860 have to be specified.
 861 The expression evaluates to true if both expressions are true.
 862 The second expression is not evaluated if the first expression is false.
 863 .Pp
 864 .It Ar expression Cm -or Ar expression
 865 The
 866 .Cm -or
 867 operator is the logical
 868 .Tn OR
 869 operator.
 870 The expression evaluates to true if either the first or the second expression
 871 is true.
 872 The second expression is not evaluated if the first expression is true.
 873 .El
 874 .Pp
 875 All operands and primaries must be separate arguments to
 876 .Nm .
 877 Primaries which themselves take arguments expect each argument
 878 to be a separate argument to
 879 .Nm .
 880 .Sh ENVIRONMENT
 881 The
 882 .Ev LANG , LC_ALL , LC_COLLATE , LC_CTYPE , LC_MESSAGES
 883 and
 884 .Ev LC_TIME
 885 environment variables affect the execution of the
 886 .Nm
 887 utility as described in
 888 .Xr environ 7 .
 889 .Sh EXAMPLES
 890 The following examples are shown as given to the shell:
 891 .Bl -tag -width indent
 892 .It Li "find / \e! -name \*q*.c\*q -print"
 893 Print out a list of all the files whose names do not end in
 894 .Pa .c .
 895 .It Li "find / -newer ttt -user wnj -print"
 896 Print out a list of all the files owned by user
 897 .Dq wnj
 898 that are newer
 899 than the file
 900 .Pa ttt .
 901 .It Li "find / \e! \e( -newer ttt -user wnj \e) -print"
 902 Print out a list of all the files which are not both newer than
 903 .Pa ttt
 904 and owned by
 905 .Dq wnj .
 906 .It Li "find / \e( -newer ttt -or -user wnj \e) -print"
 907 Print out a list of all the files that are either owned by
 908 .Dq wnj
 909 or that are newer than
 910 .Pa ttt .
 911 .It Li "find / -newerct '1 minute ago' -print"
 912 Print out a list of all the files whose inode change time is more
 913 recent than the current time minus one minute.
 914 .It Li "find / -type f -exec echo {} \e;"
 915 Use the
 916 .Xr echo 1
 917 command to print out a list of all the files.
 918 .It Li "find -L /usr/ports/packages -type l -exec rm -- {} +"
 919 Delete all broken symbolic links in
 920 .Pa /usr/ports/packages .
 921 .It Li "find /usr/src -name CVS -prune -o -depth +6 -print"
 922 Find files and directories that are at least seven levels deep
 923 in the working directory
 924 .Pa /usr/src .
 925 .It Li "find /usr/src -name CVS -prune -o -mindepth 7 -print"
 926 Is not equivalent to the previous example, since
 927 .Ic -prune
 928 is not evaluated below level seven.
 929 .El
 930 .Sh COMPATIBILITY
 931 The
 932 .Ic -follow
 933 primary is deprecated; the
 934 .Fl L
 935 option should be used instead.
 936 See the
 937 .Sx STANDARDS
 938 section below for details.
 939 .Sh SEE ALSO
 940 .Xr chflags 1 ,
 941 .Xr chmod 1 ,
 942 .Xr cvs 1 ,
 943 .Xr locate 1 ,
 944 .Xr lsvfs 1 ,
 945 .Xr whereis 1 ,
 946 .Xr which 1 ,
 947 .Xr xargs 1 ,
 948 .Xr stat 2 ,
 949 .Xr acl 3 ,
 950 .Xr fts 3 ,
 951 .Xr getgrent 3 ,
 952 .Xr getpwent 3 ,
 953 .Xr strmode 3 ,
 954 .Xr re_format 7 ,
 955 .Xr symlink 7
 956 .Sh STANDARDS
 957 The
 958 .Nm
 959 utility syntax is a superset of the syntax specified by the
 960 .St -p1003.1-2001
 961 standard.
 962 .Pp
 963 All the single character options except
 964 .Fl H
 965 and
 966 .Fl L
 967 as well as
 968 .Ic -amin , -anewer , -cmin , -cnewer , -delete , -empty , -fstype ,
 969 .Ic -iname , -inum , -iregex , -ls , -maxdepth , -mindepth , -mmin ,
 970 .Ic -path , -print0 , -regex
 971 and all of the
 972 .Ic -B*
 973 birthtime related primaries are extensions to
 974 .St -p1003.1-2001 .
 975 .Pp
 976 Historically, the
 977 .Fl d , L
 978 and
 979 .Fl x
 980 options were implemented using the primaries
 981 .Ic -depth , -follow ,
 982 and
 983 .Ic -xdev .
 984 These primaries always evaluated to true.
 985 As they were really global variables that took effect before the traversal
 986 began, some legal expressions could have unexpected results.
 987 An example is the expression
 988 .Ic -print Cm -o Ic -depth .
 989 As
 990 .Ic -print
 991 always evaluates to true, the standard order of evaluation
 992 implies that
 993 .Ic -depth
 994 would never be evaluated.
 995 This is not the case.
 996 .Pp
 997 The operator
 998 .Cm -or
 999 was implemented as
1000 .Cm -o ,
1001 and the operator
1002 .Cm -and
1003 was implemented as
1004 .Cm -a .
1005 .Pp
1006 Historic implementations of the
1007 .Ic -exec
1008 and
1009 .Ic -ok
1010 primaries did not replace the string
1011 .Dq Li {}
1012 in the utility name or the
1013 utility arguments if it had preceding or following non-whitespace characters.
1014 This version replaces it no matter where in the utility name or arguments
1015 it appears.
1016 .Pp
1017 The
1018 .Fl E
1019 option was inspired by the equivalent
1020 .Xr grep 1
1021 and
1022 .Xr sed 1
1023 options.
1024 .Sh HISTORY
1025 A
1026 .Nm
1027 command appeared in
1028 .At v1 .
1029 .Sh BUGS
1030 The special characters used by
1031 .Nm
1032 are also special characters to many shell programs.
1033 In particular, the characters
1034 .Dq Li * ,
1035 .Dq Li \&[ ,
1036 .Dq Li \&] ,
1037 .Dq Li \&? ,
1038 .Dq Li \&( ,
1039 .Dq Li \&) ,
1040 .Dq Li \&! ,
1041 .Dq Li \e
1042 and
1043 .Dq Li \&;
1044 may have to be escaped from the shell.
1045 .Pp
1046 As there is no delimiter separating options and file names or file
1047 names and the
1048 .Ar expression ,
1049 it is difficult to specify files named
1050 .Pa -xdev
1051 or
1052 .Pa \&! .
1053 These problems are handled by the
1054 .Fl f
1055 option and the
1056 .Xr getopt 3
1057 .Dq Fl Fl
1058 construct.
1059 .Pp
1060 The
1061 .Ic -delete
1062 primary does not interact well with other options that cause the file system
1063 tree traversal options to be changed.
1064 .Pp
1065 The
1066 .Ic -mindepth
1067 and
1068 .Ic -maxdepth
1069 primaries are actually global options (as documented above).
1070 They should
1071 probably be replaced by options which look like options.