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