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