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