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 September 9, 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 .Nm .
 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 .Nm
 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 .Nm ,
 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 -quit
 739 Causes
 740 .Nm
 741 to immediately terminate.
 742 .It Ic -regex Ar pattern
 743 True if the whole path of the file matches
 744 .Ar pattern
 745 using regular expression.
 746 To match a file named
 747 .Dq Pa ./foo/xyzzy ,
 748 you can use the regular expression
 749 .Dq Li ".*/[xyz]*"
 750 or
 751 .Dq Li ".*/foo/.*" ,
 752 but not
 753 .Dq Li xyzzy
 754 or
 755 .Dq Li /foo/ .
 756 .It Ic -samefile Ar name
 757 True if the file is a hard link to
 758 .Ar name .
 759 If the command option
 760 .Ic -L
 761 is specified, it is also true if the file is a symbolic link and
 762 points to
 763 .Ar name .
 764 .It Ic -size Ar n Ns Op Cm ckMGTP
 765 True if the file's size, rounded up, in 512-byte blocks is
 766 .Ar n .
 767 If
 768 .Ar n
 769 is followed by a
 770 .Cm c ,
 771 then the primary is true if the
 772 file's size is
 773 .Ar n
 774 bytes (characters).
 775 Similarly if
 776 .Ar n
 777 is followed by a scale indicator then the file's size is compared to
 778 .Ar n
 779 scaled as:
 780 .Pp
 781 .Bl -tag -width indent -compact
 782 .It Cm k
 783 kilobytes (1024 bytes)
 784 .It Cm M
 785 megabytes (1024 kilobytes)
 786 .It Cm G
 787 gigabytes (1024 megabytes)
 788 .It Cm T
 789 terabytes (1024 gigabytes)
 790 .It Cm P
 791 petabytes (1024 terabytes)
 792 .El
 793 .It Ic -type Ar t
 794 True if the file is of the specified type.
 795 Possible file types are as follows:
 796 .Pp
 797 .Bl -tag -width indent -compact
 798 .It Cm b
 799 block special
 800 .It Cm c
 801 character special
 802 .It Cm d
 803 directory
 804 .It Cm f
 805 regular file
 806 .It Cm l
 807 symbolic link
 808 .It Cm p
 809 FIFO
 810 .It Cm s
 811 socket
 812 .El
 813 .It Ic -uid Ar uname
 814 The same thing as
 815 .Ar -user Ar uname
 816 for compatibility with GNU find.
 817 GNU find imposes a restriction that
 818 .Ar uname
 819 is numeric, while
 820 .Nm
 821 does not.
 822 .It Ic -user Ar uname
 823 True if the file belongs to the user
 824 .Ar uname .
 825 If
 826 .Ar uname
 827 is numeric and there is no such user name, then
 828 .Ar uname
 829 is treated as a user ID.
 830 .It Ic -wholename Ar pattern
 831 The same thing as
 832 .Ic -path ,
 833 for GNU find compatibility.
 834 .El
 835 .Sh OPERATORS
 836 The primaries may be combined using the following operators.
 837 The operators are listed in order of decreasing precedence.
 838 .Pp
 839 .Bl -tag -width indent -compact
 840 .It Cm \&( Ar expression Cm \&)
 841 This evaluates to true if the parenthesized expression evaluates to
 842 true.
 843 .Pp
 844 .It Cm \&! Ar expression
 845 .It Cm -not Ar expression
 846 This is the unary
 847 .Tn NOT
 848 operator.
 849 It evaluates to true if the expression is false.
 850 .Pp
 851 .It Cm -false
 852 Always false.
 853 .It Cm -true
 854 Always true.
 855 .Pp
 856 .It Ar expression Cm -and Ar expression
 857 .It Ar expression expression
 858 The
 859 .Cm -and
 860 operator is the logical
 861 .Tn AND
 862 operator.
 863 As it is implied by the juxtaposition of two expressions it does not
 864 have to be specified.
 865 The expression evaluates to true if both expressions are true.
 866 The second expression is not evaluated if the first expression is false.
 867 .Pp
 868 .It Ar expression Cm -or Ar expression
 869 The
 870 .Cm -or
 871 operator is the logical
 872 .Tn OR
 873 operator.
 874 The expression evaluates to true if either the first or the second expression
 875 is true.
 876 The second expression is not evaluated if the first expression is true.
 877 .El
 878 .Pp
 879 All operands and primaries must be separate arguments to
 880 .Nm .
 881 Primaries which themselves take arguments expect each argument
 882 to be a separate argument to
 883 .Nm .
 884 .Sh ENVIRONMENT
 885 The
 886 .Ev LANG , LC_ALL , LC_COLLATE , LC_CTYPE , LC_MESSAGES
 887 and
 888 .Ev LC_TIME
 889 environment variables affect the execution of the
 890 .Nm
 891 utility as described in
 892 .Xr environ 7 .
 893 .Sh EXAMPLES
 894 The following examples are shown as given to the shell:
 895 .Bl -tag -width indent
 896 .It Li "find / \e! -name \*q*.c\*q -print"
 897 Print out a list of all the files whose names do not end in
 898 .Pa .c .
 899 .It Li "find / -newer ttt -user wnj -print"
 900 Print out a list of all the files owned by user
 901 .Dq wnj
 902 that are newer
 903 than the file
 904 .Pa ttt .
 905 .It Li "find / \e! \e( -newer ttt -user wnj \e) -print"
 906 Print out a list of all the files which are not both newer than
 907 .Pa ttt
 908 and owned by
 909 .Dq wnj .
 910 .It Li "find / \e( -newer ttt -or -user wnj \e) -print"
 911 Print out a list of all the files that are either owned by
 912 .Dq wnj
 913 or that are newer than
 914 .Pa ttt .
 915 .It Li "find / -newerct '1 minute ago' -print"
 916 Print out a list of all the files whose inode change time is more
 917 recent than the current time minus one minute.
 918 .It Li "find / -type f -exec echo {} \e;"
 919 Use the
 920 .Xr echo 1
 921 command to print out a list of all the files.
 922 .It Li "find -L /usr/ports/packages -type l -exec rm -- {} +"
 923 Delete all broken symbolic links in
 924 .Pa /usr/ports/packages .
 925 .It Li "find /usr/src -name CVS -prune -o -depth +6 -print"
 926 Find files and directories that are at least seven levels deep
 927 in the working directory
 928 .Pa /usr/src .
 929 .It Li "find /usr/src -name CVS -prune -o -mindepth 7 -print"
 930 Is not equivalent to the previous example, since
 931 .Ic -prune
 932 is not evaluated below level seven.
 933 .El
 934 .Sh COMPATIBILITY
 935 The
 936 .Ic -follow
 937 primary is deprecated; the
 938 .Fl L
 939 option should be used instead.
 940 See the
 941 .Sx STANDARDS
 942 section below for details.
 943 .Sh SEE ALSO
 944 .Xr chflags 1 ,
 945 .Xr chmod 1 ,
 946 .Xr cvs 1 ,
 947 .Xr locate 1 ,
 948 .Xr lsvfs 1 ,
 949 .Xr whereis 1 ,
 950 .Xr which 1 ,
 951 .Xr xargs 1 ,
 952 .Xr stat 2 ,
 953 .Xr acl 3 ,
 954 .Xr fts 3 ,
 955 .Xr getgrent 3 ,
 956 .Xr getpwent 3 ,
 957 .Xr strmode 3 ,
 958 .Xr re_format 7 ,
 959 .Xr symlink 7
 960 .Sh STANDARDS
 961 The
 962 .Nm
 963 utility syntax is a superset of the syntax specified by the
 964 .St -p1003.1-2001
 965 standard.
 966 .Pp
 967 All the single character options except
 968 .Fl H
 969 and
 970 .Fl L
 971 as well as
 972 .Ic -amin , -anewer , -cmin , -cnewer , -delete , -empty , -fstype ,
 973 .Ic -iname , -inum , -iregex , -ls , -maxdepth , -mindepth , -mmin ,
 974 .Ic -path , -print0 , -regex
 975 and all of the
 976 .Ic -B*
 977 birthtime related primaries are extensions to
 978 .St -p1003.1-2001 .
 979 .Pp
 980 Historically, the
 981 .Fl d , L
 982 and
 983 .Fl x
 984 options were implemented using the primaries
 985 .Ic -depth , -follow ,
 986 and
 987 .Ic -xdev .
 988 These primaries always evaluated to true.
 989 As they were really global variables that took effect before the traversal
 990 began, some legal expressions could have unexpected results.
 991 An example is the expression
 992 .Ic -print Cm -o Ic -depth .
 993 As
 994 .Ic -print
 995 always evaluates to true, the standard order of evaluation
 996 implies that
 997 .Ic -depth
 998 would never be evaluated.
 999 This is not the case.
1000 .Pp
1001 The operator
1002 .Cm -or
1003 was implemented as
1004 .Cm -o ,
1005 and the operator
1006 .Cm -and
1007 was implemented as
1008 .Cm -a .
1009 .Pp
1010 Historic implementations of the
1011 .Ic -exec
1012 and
1013 .Ic -ok
1014 primaries did not replace the string
1015 .Dq Li {}
1016 in the utility name or the
1017 utility arguments if it had preceding or following non-whitespace characters.
1018 This version replaces it no matter where in the utility name or arguments
1019 it appears.
1020 .Pp
1021 The
1022 .Fl E
1023 option was inspired by the equivalent
1024 .Xr grep 1
1025 and
1026 .Xr sed 1
1027 options.
1028 .Sh HISTORY
1029 A
1030 .Nm
1031 command appeared in
1032 .At v1 .
1033 .Sh BUGS
1034 The special characters used by
1035 .Nm
1036 are also special characters to many shell programs.
1037 In particular, the characters
1038 .Dq Li * ,
1039 .Dq Li \&[ ,
1040 .Dq Li \&] ,
1041 .Dq Li \&? ,
1042 .Dq Li \&( ,
1043 .Dq Li \&) ,
1044 .Dq Li \&! ,
1045 .Dq Li \e
1046 and
1047 .Dq Li \&;
1048 may have to be escaped from the shell.
1049 .Pp
1050 As there is no delimiter separating options and file names or file
1051 names and the
1052 .Ar expression ,
1053 it is difficult to specify files named
1054 .Pa -xdev
1055 or
1056 .Pa \&! .
1057 These problems are handled by the
1058 .Fl f
1059 option and the
1060 .Xr getopt 3
1061 .Dq Fl Fl
1062 construct.
1063 .Pp
1064 The
1065 .Ic -delete
1066 primary does not interact well with other options that cause the file system
1067 tree traversal options to be changed.
1068 .Pp
1069 The
1070 .Ic -mindepth
1071 and
1072 .Ic -maxdepth
1073 primaries are actually global options (as documented above).
1074 They should
1075 probably be replaced by options which look like options.