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