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