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