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 January 5, 2014
  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 Ignore errors because a file or a directory is deleted
 472 after reading the name from a directory.
 473 This option does not affect errors occurring on starting points.
 474 .It Ic -ilname Ar pattern
 475 Like
 476 .Ic -lname ,
 477 but the match is case insensitive.
 478 This is a GNU find extension.
 479 .It Ic -iname Ar pattern
 480 Like
 481 .Ic -name ,
 482 but the match is case insensitive.
 483 .It Ic -inum Ar n
 484 True if the file has inode number
 485 .Ar n .
 486 .It Ic -ipath Ar pattern
 487 Like
 488 .Ic -path ,
 489 but the match is case insensitive.
 490 .It Ic -iregex Ar pattern
 491 Like
 492 .Ic -regex ,
 493 but the match is case insensitive.
 494 .It Ic -iwholename Ar pattern
 495 The same thing as
 496 .Ic -ipath ,
 497 for GNU find compatibility.
 498 .It Ic -links Ar n
 499 True if the file has
 500 .Ar n
 501 links.
 502 .It Ic -lname Ar pattern
 503 Like
 504 .Ic -name ,
 505 but the contents of the symbolic link are matched instead of the file
 506 name.
 507 Note that this only matches broken symbolic links
 508 if symbolic links are being followed.
 509 This is a GNU find extension.
 510 .It Ic -ls
 511 This primary always evaluates to true.
 512 The following information for the current file is written to standard output:
 513 its inode number, size in 512-byte blocks, file permissions, number of hard
 514 links, owner, group, size in bytes, last modification time, and pathname.
 515 If the file is a block or character special file, the major and minor numbers
 516 will be displayed instead of the size in bytes.
 517 If the file is a symbolic link, the pathname of the linked-to file will be
 518 displayed preceded by
 519 .Dq Li -> .
 520 The format is identical to that produced by
 521 .Bk -words
 522 .Dq Nm ls Fl dgils .
 523 .Ek
 524 .It Ic -maxdepth Ar n
 525 Always true; descend at most
 526 .Ar n
 527 directory levels below the command line arguments.
 528 If any
 529 .Ic -maxdepth
 530 primary is specified, it applies to the entire expression even if it would
 531 not normally be evaluated.
 532 .Dq Ic -maxdepth Li 0
 533 limits the whole search to the command line arguments.
 534 .It Ic -mindepth Ar n
 535 Always true; do not apply any tests or actions at levels less than
 536 .Ar n .
 537 If any
 538 .Ic -mindepth
 539 primary is specified, it applies to the entire expression even if it would
 540 not normally be evaluated.
 541 .Dq Ic -mindepth Li 1
 542 processes all but the command line arguments.
 543 .It Ic -mmin Ar n
 544 True if the difference between the file last modification time and the time
 545 .Nm
 546 was started, rounded up to the next full minute, is
 547 .Ar n
 548 minutes.
 549 .It Ic -mnewer Ar file
 550 Same as
 551 .Ic -newer .
 552 .It Ic -mount
 553 The same thing as
 554 .Ic -xdev ,
 555 for GNU find compatibility.
 556 .It Ic -mtime Ar n Ns Op Cm smhdw
 557 If no units are specified, this primary evaluates to
 558 true if the difference between the file last modification time and the time
 559 .Nm
 560 was started, rounded up to the next full 24-hour period, is
 561 .Ar n
 562 24-hour periods.
 563 .Pp
 564 If units are specified, this primary evaluates to
 565 true if the difference between the file last modification time and the time
 566 .Nm
 567 was started is exactly
 568 .Ar n
 569 units.
 570 Please refer to the
 571 .Ic -atime
 572 primary description for information on supported time units.
 573 .It Ic -name Ar pattern
 574 True if the last component of the pathname being examined matches
 575 .Ar pattern .
 576 Special shell pattern matching characters
 577 .Dq ( Li \&[ ,
 578 .Dq Li \&] ,
 579 .Dq Li * ,
 580 and
 581 .Dq Li \&? )
 582 may be used as part of
 583 .Ar pattern .
 584 These characters may be matched explicitly by escaping them with a
 585 backslash
 586 .Pq Dq Li \e .
 587 .It Ic -newer Ar file
 588 True if the current file has a more recent last modification time than
 589 .Ar file .
 590 .It Ic -newer Ns Ar X Ns Ar Y Ar file
 591 True if the current file has a more recent last access time
 592 .Pq Ar X Ns = Ns Cm a ,
 593 inode creation time
 594 .Pq Ar X Ns = Ns Cm B ,
 595 change time
 596 .Pq Ar X Ns = Ns Cm c ,
 597 or modification time
 598 .Pq Ar X Ns = Ns Cm m
 599 than the last access time
 600 .Pq Ar Y Ns = Ns Cm a ,
 601 inode creation time
 602 .Pq Ar Y Ns = Ns Cm B ,
 603 change time
 604 .Pq Ar Y Ns = Ns Cm c ,
 605 or modification time
 606 .Pq Ar Y Ns = Ns Cm m
 607 of
 608 .Ar file .
 609 In addition, if
 610 .Ar Y Ns = Ns Cm t ,
 611 then
 612 .Ar file
 613 is instead interpreted as a direct date specification of the form
 614 understood by
 615 .Xr cvs 1 .
 616 Note that
 617 .Ic -newermm
 618 is equivalent to
 619 .Ic -newer .
 620 .It Ic -nogroup
 621 True if the file belongs to an unknown group.
 622 .It Ic -noignore_readdir_race
 623 Turn off the effect of
 624 .Ic -ignore_readdir_race .
 625 This is default behaviour.
 626 .It Ic -noleaf
 627 This option is for GNU find compatibility.
 628 In GNU find it disables an optimization not relevant to
 629 .Nm ,
 630 so it is ignored.
 631 .It Ic -nouser
 632 True if the file belongs to an unknown user.
 633 .It Ic -ok Ar utility Oo Ar argument ... Oc Li \&;
 634 The
 635 .Ic -ok
 636 primary is identical to the
 637 .Ic -exec
 638 primary with the exception that
 639 .Nm
 640 requests user affirmation for the execution of the
 641 .Ar utility
 642 by printing
 643 a message to the terminal and reading a response.
 644 If the response is not affirmative
 645 .Ql ( y
 646 in the
 647 .Dq Li POSIX
 648 locale),
 649 the command is not executed and the
 650 value of the
 651 .Ic -ok
 652 expression is false.
 653 .It Ic -okdir Ar utility Oo Ar argument ... Oc Li \&;
 654 The
 655 .Ic -okdir
 656 primary is identical to the
 657 .Ic -execdir
 658 primary with the same exception as described for the
 659 .Ic -ok
 660 primary.
 661 .It Ic -path Ar pattern
 662 True if the pathname being examined matches
 663 .Ar pattern .
 664 Special shell pattern matching characters
 665 .Dq ( Li \&[ ,
 666 .Dq Li \&] ,
 667 .Dq Li * ,
 668 and
 669 .Dq Li \&? )
 670 may be used as part of
 671 .Ar pattern .
 672 These characters may be matched explicitly by escaping them with a
 673 backslash
 674 .Pq Dq Li \e .
 675 Slashes
 676 .Pq Dq Li /
 677 are treated as normal characters and do not have to be
 678 matched explicitly.
 679 .It Ic -perm Oo Cm - Ns | Ns Cm + Oc Ns Ar mode
 680 The
 681 .Ar mode
 682 may be either symbolic (see
 683 .Xr chmod 1 )
 684 or an octal number.
 685 If the
 686 .Ar mode
 687 is symbolic, a starting value of zero is assumed and the
 688 .Ar mode
 689 sets or clears permissions without regard to the process' file mode
 690 creation mask.
 691 If the
 692 .Ar mode
 693 is octal, only bits 07777
 694 .Pq Dv S_ISUID | S_ISGID | S_ISTXT | S_IRWXU | S_IRWXG | S_IRWXO
 695 of the file's mode bits participate
 696 in the comparison.
 697 If the
 698 .Ar mode
 699 is preceded by a dash
 700 .Pq Dq Li - ,
 701 this primary evaluates to true
 702 if at least all of the bits in the
 703 .Ar mode
 704 are set in the file's mode bits.
 705 If the
 706 .Ar mode
 707 is preceded by a plus
 708 .Pq Dq Li + ,
 709 this primary evaluates to true
 710 if any of the bits in the
 711 .Ar mode
 712 are set in the file's mode bits.
 713 Otherwise, this primary evaluates to true if
 714 the bits in the
 715 .Ar mode
 716 exactly match the file's mode bits.
 717 Note, the first character of a symbolic mode may not be a dash
 718 .Pq Dq Li - .
 719 .It Ic -print
 720 This primary always evaluates to true.
 721 It prints the pathname of the current file to standard output.
 722 If none of
 723 .Ic -exec , -ls , -print0 ,
 724 or
 725 .Ic -ok
 726 is specified, the given expression shall be effectively replaced by
 727 .Cm \&( Ar "given expression" Cm \&) Ic -print .
 728 .It Ic -print0
 729 This primary always evaluates to true.
 730 It prints the pathname of the current file to standard output, followed by an
 731 .Tn ASCII
 732 .Dv NUL
 733 character (character code 0).
 734 .It Ic -prune
 735 This primary always evaluates to true.
 736 It causes
 737 .Nm
 738 to not descend into the current file.
 739 Note, the
 740 .Ic -prune
 741 primary has no effect if the
 742 .Fl d
 743 option was specified.
 744 .It Ic -quit
 745 Causes
 746 .Nm
 747 to immediately terminate.
 748 .It Ic -regex Ar pattern
 749 True if the whole path of the file matches
 750 .Ar pattern
 751 using regular expression.
 752 To match a file named
 753 .Dq Pa ./foo/xyzzy ,
 754 you can use the regular expression
 755 .Dq Li ".*/[xyz]*"
 756 or
 757 .Dq Li ".*/foo/.*" ,
 758 but not
 759 .Dq Li xyzzy
 760 or
 761 .Dq Li /foo/ .
 762 .It Ic -samefile Ar name
 763 True if the file is a hard link to
 764 .Ar name .
 765 If the command option
 766 .Ic -L
 767 is specified, it is also true if the file is a symbolic link and
 768 points to
 769 .Ar name .
 770 .It Ic -size Ar n Ns Op Cm ckMGTP
 771 True if the file's size, rounded up, in 512-byte blocks is
 772 .Ar n .
 773 If
 774 .Ar n
 775 is followed by a
 776 .Cm c ,
 777 then the primary is true if the
 778 file's size is
 779 .Ar n
 780 bytes (characters).
 781 Similarly if
 782 .Ar n
 783 is followed by a scale indicator then the file's size is compared to
 784 .Ar n
 785 scaled as:
 786 .Pp
 787 .Bl -tag -width indent -compact
 788 .It Cm k
 789 kilobytes (1024 bytes)
 790 .It Cm M
 791 megabytes (1024 kilobytes)
 792 .It Cm G
 793 gigabytes (1024 megabytes)
 794 .It Cm T
 795 terabytes (1024 gigabytes)
 796 .It Cm P
 797 petabytes (1024 terabytes)
 798 .El
 799 .It Ic -type Ar t
 800 True if the file is of the specified type.
 801 Possible file types are as follows:
 802 .Pp
 803 .Bl -tag -width indent -compact
 804 .It Cm b
 805 block special
 806 .It Cm c
 807 character special
 808 .It Cm d
 809 directory
 810 .It Cm f
 811 regular file
 812 .It Cm l
 813 symbolic link
 814 .It Cm p
 815 FIFO
 816 .It Cm s
 817 socket
 818 .El
 819 .It Ic -uid Ar uname
 820 The same thing as
 821 .Ar -user Ar uname
 822 for compatibility with GNU find.
 823 GNU find imposes a restriction that
 824 .Ar uname
 825 is numeric, while
 826 .Nm
 827 does not.
 828 .It Ic -user Ar uname
 829 True if the file belongs to the user
 830 .Ar uname .
 831 If
 832 .Ar uname
 833 is numeric and there is no such user name, then
 834 .Ar uname
 835 is treated as a user ID.
 836 .It Ic -wholename Ar pattern
 837 The same thing as
 838 .Ic -path ,
 839 for GNU find compatibility.
 840 .El
 841 .Sh OPERATORS
 842 The primaries may be combined using the following operators.
 843 The operators are listed in order of decreasing precedence.
 844 .Pp
 845 .Bl -tag -width indent -compact
 846 .It Cm \&( Ar expression Cm \&)
 847 This evaluates to true if the parenthesized expression evaluates to
 848 true.
 849 .Pp
 850 .It Cm \&! Ar expression
 851 .It Cm -not Ar expression
 852 This is the unary
 853 .Tn NOT
 854 operator.
 855 It evaluates to true if the expression is false.
 856 .Pp
 857 .It Cm -false
 858 Always false.
 859 .It Cm -true
 860 Always true.
 861 .Pp
 862 .It Ar expression Cm -and Ar expression
 863 .It Ar expression expression
 864 The
 865 .Cm -and
 866 operator is the logical
 867 .Tn AND
 868 operator.
 869 As it is implied by the juxtaposition of two expressions it does not
 870 have to be specified.
 871 The expression evaluates to true if both expressions are true.
 872 The second expression is not evaluated if the first expression is false.
 873 .Pp
 874 .It Ar expression Cm -or Ar expression
 875 The
 876 .Cm -or
 877 operator is the logical
 878 .Tn OR
 879 operator.
 880 The expression evaluates to true if either the first or the second expression
 881 is true.
 882 The second expression is not evaluated if the first expression is true.
 883 .El
 884 .Pp
 885 All operands and primaries must be separate arguments to
 886 .Nm .
 887 Primaries which themselves take arguments expect each argument
 888 to be a separate argument to
 889 .Nm .
 890 .Sh ENVIRONMENT
 891 The
 892 .Ev LANG , LC_ALL , LC_COLLATE , LC_CTYPE , LC_MESSAGES
 893 and
 894 .Ev LC_TIME
 895 environment variables affect the execution of the
 896 .Nm
 897 utility as described in
 898 .Xr environ 7 .
 899 .Sh EXAMPLES
 900 The following examples are shown as given to the shell:
 901 .Bl -tag -width indent
 902 .It Li "find / \e! -name \*q*.c\*q -print"
 903 Print out a list of all the files whose names do not end in
 904 .Pa .c .
 905 .It Li "find / -newer ttt -user wnj -print"
 906 Print out a list of all the files owned by user
 907 .Dq wnj
 908 that are newer
 909 than the file
 910 .Pa ttt .
 911 .It Li "find / \e! \e( -newer ttt -user wnj \e) -print"
 912 Print out a list of all the files which are not both newer than
 913 .Pa ttt
 914 and owned by
 915 .Dq wnj .
 916 .It Li "find / \e( -newer ttt -or -user wnj \e) -print"
 917 Print out a list of all the files that are either owned by
 918 .Dq wnj
 919 or that are newer than
 920 .Pa ttt .
 921 .It Li "find / -newerct '1 minute ago' -print"
 922 Print out a list of all the files whose inode change time is more
 923 recent than the current time minus one minute.
 924 .It Li "find / -type f -exec echo {} \e;"
 925 Use the
 926 .Xr echo 1
 927 command to print out a list of all the files.
 928 .It Li "find -L /usr/ports/packages -type l -exec rm -- {} +"
 929 Delete all broken symbolic links in
 930 .Pa /usr/ports/packages .
 931 .It Li "find /usr/src -name CVS -prune -o -depth +6 -print"
 932 Find files and directories that are at least seven levels deep
 933 in the working directory
 934 .Pa /usr/src .
 935 .It Li "find /usr/src -name CVS -prune -o -mindepth 7 -print"
 936 Is not equivalent to the previous example, since
 937 .Ic -prune
 938 is not evaluated below level seven.
 939 .El
 940 .Sh COMPATIBILITY
 941 The
 942 .Ic -follow
 943 primary is deprecated; the
 944 .Fl L
 945 option should be used instead.
 946 See the
 947 .Sx STANDARDS
 948 section below for details.
 949 .Sh SEE ALSO
 950 .Xr chflags 1 ,
 951 .Xr chmod 1 ,
 952 .Xr cvs 1 ,
 953 .Xr locate 1 ,
 954 .Xr lsvfs 1 ,
 955 .Xr whereis 1 ,
 956 .Xr which 1 ,
 957 .Xr xargs 1 ,
 958 .Xr stat 2 ,
 959 .Xr acl 3 ,
 960 .Xr fts 3 ,
 961 .Xr getgrent 3 ,
 962 .Xr getpwent 3 ,
 963 .Xr strmode 3 ,
 964 .Xr re_format 7 ,
 965 .Xr symlink 7
 966 .Sh STANDARDS
 967 The
 968 .Nm
 969 utility syntax is a superset of the syntax specified by the
 970 .St -p1003.1-2001
 971 standard.
 972 .Pp
 973 All the single character options except
 974 .Fl H
 975 and
 976 .Fl L
 977 as well as
 978 .Ic -amin , -anewer , -cmin , -cnewer , -delete , -empty , -fstype ,
 979 .Ic -iname , -inum , -iregex , -ls , -maxdepth , -mindepth , -mmin ,
 980 .Ic -path , -print0 , -regex
 981 and all of the
 982 .Ic -B*
 983 birthtime related primaries are extensions to
 984 .St -p1003.1-2001 .
 985 .Pp
 986 Historically, the
 987 .Fl d , L
 988 and
 989 .Fl x
 990 options were implemented using the primaries
 991 .Ic -depth , -follow ,
 992 and
 993 .Ic -xdev .
 994 These primaries always evaluated to true.
 995 As they were really global variables that took effect before the traversal
 996 began, some legal expressions could have unexpected results.
 997 An example is the expression
 998 .Ic -print Cm -o Ic -depth .
 999 As
1000 .Ic -print
1001 always evaluates to true, the standard order of evaluation
1002 implies that
1003 .Ic -depth
1004 would never be evaluated.
1005 This is not the case.
1006 .Pp
1007 The operator
1008 .Cm -or
1009 was implemented as
1010 .Cm -o ,
1011 and the operator
1012 .Cm -and
1013 was implemented as
1014 .Cm -a .
1015 .Pp
1016 Historic implementations of the
1017 .Ic -exec
1018 and
1019 .Ic -ok
1020 primaries did not replace the string
1021 .Dq Li {}
1022 in the utility name or the
1023 utility arguments if it had preceding or following non-whitespace characters.
1024 This version replaces it no matter where in the utility name or arguments
1025 it appears.
1026 .Pp
1027 The
1028 .Fl E
1029 option was inspired by the equivalent
1030 .Xr grep 1
1031 and
1032 .Xr sed 1
1033 options.
1034 .Sh HISTORY
1035 A
1036 .Nm
1037 command appeared in
1038 .At v1 .
1039 .Sh BUGS
1040 The special characters used by
1041 .Nm
1042 are also special characters to many shell programs.
1043 In particular, the characters
1044 .Dq Li * ,
1045 .Dq Li \&[ ,
1046 .Dq Li \&] ,
1047 .Dq Li \&? ,
1048 .Dq Li \&( ,
1049 .Dq Li \&) ,
1050 .Dq Li \&! ,
1051 .Dq Li \e
1052 and
1053 .Dq Li \&;
1054 may have to be escaped from the shell.
1055 .Pp
1056 As there is no delimiter separating options and file names or file
1057 names and the
1058 .Ar expression ,
1059 it is difficult to specify files named
1060 .Pa -xdev
1061 or
1062 .Pa \&! .
1063 These problems are handled by the
1064 .Fl f
1065 option and the
1066 .Xr getopt 3
1067 .Dq Fl Fl
1068 construct.
1069 .Pp
1070 The
1071 .Ic -delete
1072 primary does not interact well with other options that cause the file system
1073 tree traversal options to be changed.
1074 .Pp
1075 The
1076 .Ic -mindepth
1077 and
1078 .Ic -maxdepth
1079 primaries are actually global options (as documented above).
1080 They should
1081 probably be replaced by options which look like options.