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 September 9, 2012
  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 .Pp
 185 All primaries which take a numeric argument allow the number to be
 186 preceded by a plus sign
 187 .Pq Dq Li +
 188 or a minus sign
 189 .Pq Dq Li - .
 190 A preceding plus sign means
 191 .Dq more than n ,
 192 a preceding minus sign means
 193 .Dq less than n
 194 and neither means
 195 .Dq exactly n .
 196 .Bl -tag -width indent
 197 .It Ic -Bmin Ar n
 198 True if the difference between the time of a file's inode creation
 199 and the time
 200 .Nm
 201 was started, rounded up to the next full minute, is
 202 .Ar n
 203 minutes.
 204 .It Ic -Bnewer Ar file
 205 Same as
 206 .Ic -newerBm .
 207 .It Ic -Btime Ar n Ns Op Cm smhdw
 208 If no units are specified, this primary evaluates to
 209 true if the difference between the time of a file's inode creation
 210 and the time
 211 .Nm
 212 was started, rounded up to the next full 24-hour period, is
 213 .Ar n
 214 24-hour periods.
 215 .Pp
 216 If units are specified, this primary evaluates to
 217 true if the difference between the time of a file's inode creation
 218 and the time
 219 .Nm
 220 was started is exactly
 221 .Ar n
 222 units.
 223 Please refer to the
 224 .Ic -atime
 225 primary description for information on supported time units.
 226 .It Ic -acl
 227 May be used in conjunction with other primaries to locate
 228 files with extended ACLs.
 229 See
 230 .Xr acl 3
 231 for more information.
 232 .It Ic -amin Ar n
 233 True if the difference between the file last access time and the time
 234 .Nm
 235 was started, rounded up to the next full minute, is
 236 .Ar n
 237 minutes.
 238 .It Ic -anewer Ar file
 239 Same as
 240 .Ic -neweram .
 241 .It Ic -atime Ar n Ns Op Cm smhdw
 242 If no units are specified, this primary evaluates to
 243 true if the difference between the file last access time and the time
 244 .Nm
 245 was started, rounded up to the next full 24-hour period, is
 246 .Ar n
 247 24-hour periods.
 248 .Pp
 249 If units are specified, this primary evaluates to
 250 true if the difference between the file last access time and the time
 251 .Nm
 252 was started is exactly
 253 .Ar n
 254 units.
 255 Possible time units are as follows:
 256 .Pp
 257 .Bl -tag -width indent -compact
 258 .It Cm s
 259 second
 260 .It Cm m
 261 minute (60 seconds)
 262 .It Cm h
 263 hour (60 minutes)
 264 .It Cm d
 265 day (24 hours)
 266 .It Cm w
 267 week (7 days)
 268 .El
 269 .Pp
 270 Any number of units may be combined in one
 271 .Ic -atime
 272 argument, for example,
 273 .Dq Li "-atime -1h30m" .
 274 Units are probably only useful when used in conjunction with the
 275 .Cm +
 276 or
 277 .Cm -
 278 modifier.
 279 .It Ic -cmin Ar n
 280 True if the difference between the time of last change of file status
 281 information and the time
 282 .Nm
 283 was started, rounded up to the next full minute, is
 284 .Ar n
 285 minutes.
 286 .It Ic -cnewer Ar file
 287 Same as
 288 .Ic -newercm .
 289 .It Ic -ctime Ar n Ns Op Cm smhdw
 290 If no units are specified, this primary evaluates to
 291 true if the difference between the time of last change of file status
 292 information and the time
 293 .Nm
 294 was started, rounded up to the next full 24-hour period, is
 295 .Ar n
 296 24-hour periods.
 297 .Pp
 298 If units are specified, this primary evaluates to
 299 true if the difference between the time of last change of file status
 300 information and the time
 301 .Nm
 302 was started is exactly
 303 .Ar n
 304 units.
 305 Please refer to the
 306 .Ic -atime
 307 primary description for information on supported time units.
 308 .It Ic -d
 309 Same as
 310 .Ic depth .
 311 GNU find implements this as a primary in mistaken emulation of
 312 .Fx
 313 .Xr find 1 .
 314 .It Ic -delete
 315 Delete found files and/or directories.
 316 Always returns true.
 317 This executes
 318 from the current working directory as
 319 .Nm
 320 recurses down the tree.
 321 It will not attempt to delete a filename with a
 322 .Dq Pa /
 323 character in its pathname relative to
 324 .Dq Pa \&.
 325 for security reasons.
 326 Depth-first traversal processing is implied by this option.
 327 Following symlinks is incompatible with this option.
 328 .It Ic -depth
 329 Always true;
 330 same as the
 331 .Fl d
 332 option.
 333 .It Ic -depth Ar n
 334 True if the depth of the file relative to the starting point of the traversal
 335 is
 336 .Ar n .
 337 .It Ic -empty
 338 True if the current file or directory is empty.
 339 .It Ic -exec Ar utility Oo Ar argument ... Oc Li \&;
 340 True if the program named
 341 .Ar utility
 342 returns a zero value as its exit status.
 343 Optional
 344 .Ar arguments
 345 may be passed to the utility.
 346 The expression must be terminated by a semicolon
 347 .Pq Dq Li \&; .
 348 If you invoke
 349 .Nm
 350 from a shell you may need to quote the semicolon if the shell would
 351 otherwise treat it as a control operator.
 352 If the string
 353 .Dq Li {}
 354 appears anywhere in the utility name or the
 355 arguments it is replaced by the pathname of the current file.
 356 .Ar Utility
 357 will be executed from the directory from which
 358 .Nm
 359 was executed.
 360 .Ar Utility
 361 and
 362 .Ar arguments
 363 are not subject to the further expansion of shell patterns
 364 and constructs.
 365 .It Ic -exec Ar utility Oo Ar argument ... Oc Li {} +
 366 Same as
 367 .Ic -exec ,
 368 except that
 369 .Dq Li {}
 370 is replaced with as many pathnames as possible for each invocation of
 371 .Ar utility .
 372 This behaviour is similar to that of
 373 .Xr xargs 1 .
 374 .It Ic -execdir Ar utility Oo Ar argument ... Oc Li \&;
 375 The
 376 .Ic -execdir
 377 primary is identical to the
 378 .Ic -exec
 379 primary with the exception that
 380 .Ar utility
 381 will be executed from the directory that holds
 382 the current file.
 383 The filename substituted for
 384 the string
 385 .Dq Li {}
 386 is not qualified.
 387 .It Ic -execdir Ar utility Oo Ar argument ... Oc Li {} +
 388 Same as
 389 .Ic -execdir ,
 390 except that
 391 .Dq Li {}
 392 is replaced with as many pathnames as possible for each invocation of
 393 .Ar utility .
 394 This behaviour is similar to that of
 395 .Xr xargs 1 .
 396 .It Ic -flags Oo Cm - Ns | Ns Cm + Oc Ns Ar flags , Ns Ar notflags
 397 The flags are specified using symbolic names (see
 398 .Xr chflags 1 ) .
 399 Those with the
 400 .Qq Li no
 401 prefix (except
 402 .Qq Li nodump )
 403 are said to be
 404 .Ar notflags .
 405 Flags in
 406 .Ar flags
 407 are checked to be set, and flags in
 408 .Ar notflags
 409 are checked to be not set.
 410 Note that this is different from
 411 .Ic -perm ,
 412 which only allows the user to specify mode bits that are set.
 413 .Pp
 414 If flags are preceded by a dash
 415 .Pq Dq Li - ,
 416 this primary evaluates to true
 417 if at least all of the bits in
 418 .Ar flags
 419 and none of the bits in
 420 .Ar notflags
 421 are set in the file's flags bits.
 422 If flags are preceded by a plus
 423 .Pq Dq Li + ,
 424 this primary evaluates to true
 425 if any of the bits in
 426 .Ar flags
 427 is set in the file's flags bits,
 428 or any of the bits in
 429 .Ar notflags
 430 is not set in the file's flags bits.
 431 Otherwise,
 432 this primary evaluates to true
 433 if the bits in
 434 .Ar flags
 435 exactly match the file's flags bits,
 436 and none of the
 437 .Ar flags
 438 bits match those of
 439 .Ar notflags .
 440 .It Ic -fstype Ar type
 441 True if the file is contained in a file system of type
 442 .Ar type .
 443 The
 444 .Xr sysctl 8
 445 command can be used to find out the types of file systems
 446 that are available on the system:
 447 .Pp
 448 .Dl "sysctl vfs"
 449 .Pp
 450 In addition, there are two pseudo-types,
 451 .Dq Li local
 452 and
 453 .Dq Li rdonly .
 454 The former matches any file system physically mounted on the system where
 455 the
 456 .Nm
 457 is being executed and the latter matches any file system which is
 458 mounted read-only.
 459 .It Ic -gid Ar gname
 460 The same thing as
 461 .Ar -group Ar gname
 462 for compatibility with GNU find.
 463 GNU find imposes a restriction that
 464 .Ar gname
 465 is numeric, while
 466 .Xr find 1
 467 does not.
 468 .It Ic -group Ar gname
 469 True if the file belongs to the group
 470 .Ar gname .
 471 If
 472 .Ar gname
 473 is numeric and there is no such group name, then
 474 .Ar gname
 475 is treated as a group ID.
 476 .It Ic -ignore_readdir_race
 477 This option is for GNU find compatibility and is ignored.
 478 .It Ic -ilname Ar pattern
 479 Like
 480 .Ic -lname ,
 481 but the match is case insensitive.
 482 This is a GNU find extension.
 483 .It Ic -iname Ar pattern
 484 Like
 485 .Ic -name ,
 486 but the match is case insensitive.
 487 .It Ic -inum Ar n
 488 True if the file has inode number
 489 .Ar n .
 490 .It Ic -ipath Ar pattern
 491 Like
 492 .Ic -path ,
 493 but the match is case insensitive.
 494 .It Ic -iregex Ar pattern
 495 Like
 496 .Ic -regex ,
 497 but the match is case insensitive.
 498 .It Ic -iwholename Ar pattern
 499 The same thing as
 500 .Ic -ipath ,
 501 for GNU find compatibility.
 502 .It Ic -links Ar n
 503 True if the file has
 504 .Ar n
 505 links.
 506 .It Ic -lname Ar pattern
 507 Like
 508 .Ic -name ,
 509 but the contents of the symbolic link are matched instead of the file
 510 name.
 511 This is a GNU find extension.
 512 .It Ic -ls
 513 This primary always evaluates to true.
 514 The following information for the current file is written to standard output:
 515 its inode number, size in 512-byte blocks, file permissions, number of hard
 516 links, owner, group, size in bytes, last modification time, and pathname.
 517 If the file is a block or character special file, the major and minor numbers
 518 will be displayed instead of the size in bytes.
 519 If the file is a symbolic link, the pathname of the linked-to file will be
 520 displayed preceded by
 521 .Dq Li -> .
 522 The format is identical to that produced by
 523 .Bk -words
 524 .Dq Nm ls Fl dgils .
 525 .Ek
 526 .It Ic -maxdepth Ar n
 527 Always true; descend at most
 528 .Ar n
 529 directory levels below the command line arguments.
 530 If any
 531 .Ic -maxdepth
 532 primary is specified, it applies to the entire expression even if it would
 533 not normally be evaluated.
 534 .Dq Ic -maxdepth Li 0
 535 limits the whole search to the command line arguments.
 536 .It Ic -mindepth Ar n
 537 Always true; do not apply any tests or actions at levels less than
 538 .Ar n .
 539 If any
 540 .Ic -mindepth
 541 primary is specified, it applies to the entire expression even if it would
 542 not normally be evaluated.
 543 .Dq Ic -mindepth Li 1
 544 processes all but the command line arguments.
 545 .It Ic -mmin Ar n
 546 True if the difference between the file last modification time and the time
 547 .Nm
 548 was started, rounded up to the next full minute, is
 549 .Ar n
 550 minutes.
 551 .It Ic -mnewer Ar file
 552 Same as
 553 .Ic -newer .
 554 .It Ic -mount
 555 The same thing as
 556 .Ic -xdev ,
 557 for GNU find compatibility.
 558 .It Ic -mtime Ar n Ns Op Cm smhdw
 559 If no units are specified, this primary evaluates to
 560 true if the difference between the file last modification time and the time
 561 .Nm
 562 was started, rounded up to the next full 24-hour period, is
 563 .Ar n
 564 24-hour periods.
 565 .Pp
 566 If units are specified, this primary evaluates to
 567 true if the difference between the file last modification time and the time
 568 .Nm
 569 was started is exactly
 570 .Ar n
 571 units.
 572 Please refer to the
 573 .Ic -atime
 574 primary description for information on supported time units.
 575 .It Ic -name Ar pattern
 576 True if the last component of the pathname being examined matches
 577 .Ar pattern .
 578 Special shell pattern matching characters
 579 .Dq ( Li \&[ ,
 580 .Dq Li \&] ,
 581 .Dq Li * ,
 582 and
 583 .Dq Li \&? )
 584 may be used as part of
 585 .Ar pattern .
 586 These characters may be matched explicitly by escaping them with a
 587 backslash
 588 .Pq Dq Li \e .
 589 .It Ic -newer Ar file
 590 True if the current file has a more recent last modification time than
 591 .Ar file .
 592 .It Ic -newer Ns Ar X Ns Ar Y Ar file
 593 True if the current file has a more recent last access time
 594 .Pq Ar X Ns = Ns Cm a ,
 595 inode creation time
 596 .Pq Ar X Ns = Ns Cm B ,
 597 change time
 598 .Pq Ar X Ns = Ns Cm c ,
 599 or modification time
 600 .Pq Ar X Ns = Ns Cm m
 601 than the last access time
 602 .Pq Ar Y Ns = Ns Cm a ,
 603 inode creation time
 604 .Pq Ar Y Ns = Ns Cm B ,
 605 change time
 606 .Pq Ar Y Ns = Ns Cm c ,
 607 or modification time
 608 .Pq Ar Y Ns = Ns Cm m
 609 of
 610 .Ar file .
 611 In addition, if
 612 .Ar Y Ns = Ns Cm t ,
 613 then
 614 .Ar file
 615 is instead interpreted as a direct date specification of the form
 616 understood by
 617 .Xr cvs 1 .
 618 Note that
 619 .Ic -newermm
 620 is equivalent to
 621 .Ic -newer .
 622 .It Ic -nogroup
 623 True if the file belongs to an unknown group.
 624 .It Ic -noignore_readdir_race
 625 This option is for GNU find compatibility and is ignored.
 626 .It Ic -noleaf
 627 This option is for GNU find compatibility.
 628 In GNU find it disables an optimization not relevant to
 629 .Xr find 1 ,
 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 .Xr find 1
 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 whereis 1 ,
 955 .Xr which 1 ,
 956 .Xr xargs 1 ,
 957 .Xr stat 2 ,
 958 .Xr acl 3 ,
 959 .Xr fts 3 ,
 960 .Xr getgrent 3 ,
 961 .Xr getpwent 3 ,
 962 .Xr strmode 3 ,
 963 .Xr re_format 7 ,
 964 .Xr symlink 7
 965 .Sh STANDARDS
 966 The
 967 .Nm
 968 utility syntax is a superset of the syntax specified by the
 969 .St -p1003.1-2001
 970 standard.
 971 .Pp
 972 All the single character options except
 973 .Fl H
 974 and
 975 .Fl L
 976 as well as
 977 .Ic -amin , -anewer , -cmin , -cnewer , -delete , -empty , -fstype ,
 978 .Ic -iname , -inum , -iregex , -ls , -maxdepth , -mindepth , -mmin ,
 979 .Ic -path , -print0 , -regex
 980 and all of the
 981 .Ic -B*
 982 birthtime related primaries are extensions to
 983 .St -p1003.1-2001 .
 984 .Pp
 985 Historically, the
 986 .Fl d , L
 987 and
 988 .Fl x
 989 options were implemented using the primaries
 990 .Ic -depth , -follow ,
 991 and
 992 .Ic -xdev .
 993 These primaries always evaluated to true.
 994 As they were really global variables that took effect before the traversal
 995 began, some legal expressions could have unexpected results.
 996 An example is the expression
 997 .Ic -print Cm -o Ic -depth .
 998 As
 999 .Ic -print
1000 always evaluates to true, the standard order of evaluation
1001 implies that
1002 .Ic -depth
1003 would never be evaluated.
1004 This is not the case.
1005 .Pp
1006 The operator
1007 .Cm -or
1008 was implemented as
1009 .Cm -o ,
1010 and the operator
1011 .Cm -and
1012 was implemented as
1013 .Cm -a .
1014 .Pp
1015 Historic implementations of the
1016 .Ic -exec
1017 and
1018 .Ic -ok
1019 primaries did not replace the string
1020 .Dq Li {}
1021 in the utility name or the
1022 utility arguments if it had preceding or following non-whitespace characters.
1023 This version replaces it no matter where in the utility name or arguments
1024 it appears.
1025 .Pp
1026 The
1027 .Fl E
1028 option was inspired by the equivalent
1029 .Xr grep 1
1030 and
1031 .Xr sed 1
1032 options.
1033 .Sh HISTORY
1034 A
1035 .Nm
1036 command appeared in
1037 .At v1 .
1038 .Sh BUGS
1039 The special characters used by
1040 .Nm
1041 are also special characters to many shell programs.
1042 In particular, the characters
1043 .Dq Li * ,
1044 .Dq Li \&[ ,
1045 .Dq Li \&] ,
1046 .Dq Li \&? ,
1047 .Dq Li \&( ,
1048 .Dq Li \&) ,
1049 .Dq Li \&! ,
1050 .Dq Li \e
1051 and
1052 .Dq Li \&;
1053 may have to be escaped from the shell.
1054 .Pp
1055 As there is no delimiter separating options and file names or file
1056 names and the
1057 .Ar expression ,
1058 it is difficult to specify files named
1059 .Pa -xdev
1060 or
1061 .Pa \&! .
1062 These problems are handled by the
1063 .Fl f
1064 option and the
1065 .Xr getopt 3
1066 .Dq Fl Fl
1067 construct.
1068 .Pp
1069 The
1070 .Ic -delete
1071 primary does not interact well with other options that cause the file system
1072 tree traversal options to be changed.
1073 .Pp
1074 The
1075 .Ic -mindepth
1076 and
1077 .Ic -maxdepth
1078 primaries are actually global options (as documented above).
1079 They should
1080 probably be replaced by options which look like options.