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 January 5, 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 .It Ic -execdir Ar utility Oo Ar argument ... Oc Li \&;
 388 The
 389 .Ic -execdir
 390 primary is identical to the
 391 .Ic -exec
 392 primary with the exception that
 393 .Ar utility
 394 will be executed from the directory that holds
 395 the current file.
 396 The filename substituted for
 397 the string
 398 .Dq Li {}
 399 is not qualified.
 400 .It Ic -execdir Ar utility Oo Ar argument ... Oc Li {} +
 401 Same as
 402 .Ic -execdir ,
 403 except that
 404 .Dq Li {}
 405 is replaced with as many pathnames as possible for each invocation of
 406 .Ar utility .
 407 This behaviour is similar to that of
 408 .Xr xargs 1 .
 409 .It Ic -flags Oo Cm - Ns | Ns Cm + Oc Ns Ar flags , Ns Ar notflags
 410 The flags are specified using symbolic names (see
 411 .Xr chflags 1 ) .
 412 Those with the
 413 .Qq Li no
 414 prefix (except
 415 .Qq Li nodump )
 416 are said to be
 417 .Ar notflags .
 418 Flags in
 419 .Ar flags
 420 are checked to be set, and flags in
 421 .Ar notflags
 422 are checked to be not set.
 423 Note that this is different from
 424 .Ic -perm ,
 425 which only allows the user to specify mode bits that are set.
 426 .Pp
 427 If flags are preceded by a dash
 428 .Pq Dq Li - ,
 429 this primary evaluates to true
 430 if at least all of the bits in
 431 .Ar flags
 432 and none of the bits in
 433 .Ar notflags
 434 are set in the file's flags bits.
 435 If flags are preceded by a plus
 436 .Pq Dq Li + ,
 437 this primary evaluates to true
 438 if any of the bits in
 439 .Ar flags
 440 is set in the file's flags bits,
 441 or any of the bits in
 442 .Ar notflags
 443 is not set in the file's flags bits.
 444 Otherwise,
 445 this primary evaluates to true
 446 if the bits in
 447 .Ar flags
 448 exactly match the file's flags bits,
 449 and none of the
 450 .Ar flags
 451 bits match those of
 452 .Ar notflags .
 453 .It Ic -fstype Ar type
 454 True if the file is contained in a file system of type
 455 .Ar type .
 456 The
 457 .Xr lsvfs 1
 458 command can be used to find out the types of file systems
 459 that are available on the system.
 460 In addition, there are two pseudo-types,
 461 .Dq Li local
 462 and
 463 .Dq Li rdonly .
 464 The former matches any file system physically mounted on the system where
 465 the
 466 .Nm
 467 is being executed and the latter matches any file system which is
 468 mounted read-only.
 469 .It Ic -gid Ar gname
 470 The same thing as
 471 .Ar -group Ar gname
 472 for compatibility with GNU find.
 473 GNU find imposes a restriction that
 474 .Ar gname
 475 is numeric, while
 476 .Nm
 477 does not.
 478 .It Ic -group Ar gname
 479 True if the file belongs to the group
 480 .Ar gname .
 481 If
 482 .Ar gname
 483 is numeric and there is no such group name, then
 484 .Ar gname
 485 is treated as a group ID.
 486 .It Ic -ignore_readdir_race
 487 Ignore errors because a file or a directory is deleted
 488 after reading the name from a directory.
 489 This option does not affect errors occurring on starting points.
 490 .It Ic -ilname Ar pattern
 491 Like
 492 .Ic -lname ,
 493 but the match is case insensitive.
 494 This is a GNU find extension.
 495 .It Ic -iname Ar pattern
 496 Like
 497 .Ic -name ,
 498 but the match is case insensitive.
 499 .It Ic -inum Ar n
 500 True if the file has inode number
 501 .Ar n .
 502 .It Ic -ipath Ar pattern
 503 Like
 504 .Ic -path ,
 505 but the match is case insensitive.
 506 .It Ic -iregex Ar pattern
 507 Like
 508 .Ic -regex ,
 509 but the match is case insensitive.
 510 .It Ic -iwholename Ar pattern
 511 The same thing as
 512 .Ic -ipath ,
 513 for GNU find compatibility.
 514 .It Ic -links Ar n
 515 True if the file has
 516 .Ar n
 517 links.
 518 .It Ic -lname Ar pattern
 519 Like
 520 .Ic -name ,
 521 but the contents of the symbolic link are matched instead of the file
 522 name.
 523 Note that this only matches broken symbolic links
 524 if symbolic links are being followed.
 525 This is a GNU find extension.
 526 .It Ic -ls
 527 This primary always evaluates to true.
 528 The following information for the current file is written to standard output:
 529 its inode number, size in 512-byte blocks, file permissions, number of hard
 530 links, owner, group, size in bytes, last modification time, and pathname.
 531 If the file is a block or character special file, the device number
 532 will be displayed instead of the size in bytes.
 533 If the file is a symbolic link, the pathname of the linked-to file will be
 534 displayed preceded by
 535 .Dq Li -> .
 536 The format is identical to that produced by
 537 .Bk -words
 538 .Dq Nm ls Fl dgils .
 539 .Ek
 540 .It Ic -maxdepth Ar n
 541 Always true; descend at most
 542 .Ar n
 543 directory levels below the command line arguments.
 544 If any
 545 .Ic -maxdepth
 546 primary is specified, it applies to the entire expression even if it would
 547 not normally be evaluated.
 548 .Dq Ic -maxdepth Li 0
 549 limits the whole search to the command line arguments.
 550 .It Ic -mindepth Ar n
 551 Always true; do not apply any tests or actions at levels less than
 552 .Ar n .
 553 If any
 554 .Ic -mindepth
 555 primary is specified, it applies to the entire expression even if it would
 556 not normally be evaluated.
 557 .Dq Ic -mindepth Li 1
 558 processes all but the command line arguments.
 559 .It Ic -mmin Oo Cm - Ns | Ns Cm + Oc Ns Ar n
 560 True if the difference between the file last modification time and the time
 561 .Nm
 562 was started, rounded up to the next full minute, is
 563 .Ar n
 564 .Pq + Ns Ar n ,
 565 less than
 566 .Ar n
 567 .Pq - Ns Ar n ,
 568 or exactly
 569 .Ar n
 570 minutes ago.
 571 .It Ic -mnewer Ar file
 572 Same as
 573 .Ic -newer .
 574 .It Ic -mount
 575 The same thing as
 576 .Ic -xdev ,
 577 for GNU find compatibility.
 578 .It Ic -mtime Ar n Ns Op Cm smhdw
 579 If no units are specified, this primary evaluates to
 580 true if the difference between the file last modification time and the time
 581 .Nm
 582 was started, rounded up to the next full 24-hour period, is
 583 .Ar n
 584 24-hour periods.
 585 .Pp
 586 If units are specified, this primary evaluates to
 587 true if the difference between the file last modification time and the time
 588 .Nm
 589 was started is exactly
 590 .Ar n
 591 units.
 592 Please refer to the
 593 .Ic -atime
 594 primary description for information on supported time units.
 595 .It Ic -name Ar pattern
 596 True if the last component of the pathname being examined matches
 597 .Ar pattern .
 598 Special shell pattern matching characters
 599 .Dq ( Li \&[ ,
 600 .Dq Li \&] ,
 601 .Dq Li * ,
 602 and
 603 .Dq Li \&? )
 604 may be used as part of
 605 .Ar pattern .
 606 These characters may be matched explicitly by escaping them with a
 607 backslash
 608 .Pq Dq Li \e .
 609 .It Ic -newer Ar file
 610 True if the current file has a more recent last modification time than
 611 .Ar file .
 612 .It Ic -newer Ns Ar X Ns Ar Y Ar file
 613 True if the current file has a more recent last access time
 614 .Pq Ar X Ns = Ns Cm a ,
 615 inode creation time
 616 .Pq Ar X Ns = Ns Cm B ,
 617 change time
 618 .Pq Ar X Ns = Ns Cm c ,
 619 or modification time
 620 .Pq Ar X Ns = Ns Cm m
 621 than the last access time
 622 .Pq Ar Y Ns = Ns Cm a ,
 623 inode creation time
 624 .Pq Ar Y Ns = Ns Cm B ,
 625 change time
 626 .Pq Ar Y Ns = Ns Cm c ,
 627 or modification time
 628 .Pq Ar Y Ns = Ns Cm m
 629 of
 630 .Ar file .
 631 In addition, if
 632 .Ar Y Ns = Ns Cm t ,
 633 then
 634 .Ar file
 635 is instead interpreted as a direct date specification of the form
 636 understood by
 637 .Xr cvs 1 .
 638 Note that
 639 .Ic -newermm
 640 is equivalent to
 641 .Ic -newer .
 642 .It Ic -nogroup
 643 True if the file belongs to an unknown group.
 644 .It Ic -noignore_readdir_race
 645 Turn off the effect of
 646 .Ic -ignore_readdir_race .
 647 This is default behaviour.
 648 .It Ic -noleaf
 649 This option is for GNU find compatibility.
 650 In GNU find it disables an optimization not relevant to
 651 .Nm ,
 652 so it is ignored.
 653 .It Ic -nouser
 654 True if the file belongs to an unknown user.
 655 .It Ic -ok Ar utility Oo Ar argument ... Oc Li \&;
 656 The
 657 .Ic -ok
 658 primary is identical to the
 659 .Ic -exec
 660 primary with the exception that
 661 .Nm
 662 requests user affirmation for the execution of the
 663 .Ar utility
 664 by printing
 665 a message to the terminal and reading a response.
 666 If the response is not affirmative
 667 .Ql ( y
 668 in the
 669 .Dq Li POSIX
 670 locale),
 671 the command is not executed and the
 672 value of the
 673 .Ic -ok
 674 expression is false.
 675 .It Ic -okdir Ar utility Oo Ar argument ... Oc Li \&;
 676 The
 677 .Ic -okdir
 678 primary is identical to the
 679 .Ic -execdir
 680 primary with the same exception as described for the
 681 .Ic -ok
 682 primary.
 683 .It Ic -path Ar pattern
 684 True if the pathname being examined matches
 685 .Ar pattern .
 686 Special shell pattern matching characters
 687 .Dq ( Li \&[ ,
 688 .Dq Li \&] ,
 689 .Dq Li * ,
 690 and
 691 .Dq Li \&? )
 692 may be used as part of
 693 .Ar pattern .
 694 These characters may be matched explicitly by escaping them with a
 695 backslash
 696 .Pq Dq Li \e .
 697 Slashes
 698 .Pq Dq Li /
 699 are treated as normal characters and do not have to be
 700 matched explicitly.
 701 .It Ic -perm Oo Cm - Ns | Ns Cm + Oc Ns Ar mode
 702 The
 703 .Ar mode
 704 may be either symbolic (see
 705 .Xr chmod 1 )
 706 or an octal number.
 707 If the
 708 .Ar mode
 709 is symbolic, a starting value of zero is assumed and the
 710 .Ar mode
 711 sets or clears permissions without regard to the process' file mode
 712 creation mask.
 713 If the
 714 .Ar mode
 715 is octal, only bits 07777
 716 .Pq Dv S_ISUID | S_ISGID | S_ISTXT | S_IRWXU | S_IRWXG | S_IRWXO
 717 of the file's mode bits participate
 718 in the comparison.
 719 If the
 720 .Ar mode
 721 is preceded by a dash
 722 .Pq Dq Li - ,
 723 this primary evaluates to true
 724 if at least all of the bits in the
 725 .Ar mode
 726 are set in the file's mode bits.
 727 If the
 728 .Ar mode
 729 is preceded by a plus
 730 .Pq Dq Li + ,
 731 this primary evaluates to true
 732 if any of the bits in the
 733 .Ar mode
 734 are set in the file's mode bits.
 735 Otherwise, this primary evaluates to true if
 736 the bits in the
 737 .Ar mode
 738 exactly match the file's mode bits.
 739 Note, the first character of a symbolic mode may not be a dash
 740 .Pq Dq Li - .
 741 .It Ic -print
 742 This primary always evaluates to true.
 743 It prints the pathname of the current file to standard output.
 744 If none of
 745 .Ic -exec , -ls , -print0 ,
 746 or
 747 .Ic -ok
 748 is specified, the given expression shall be effectively replaced by
 749 .Cm \&( Ar "given expression" Cm \&) Ic -print .
 750 .It Ic -print0
 751 This primary always evaluates to true.
 752 It prints the pathname of the current file to standard output, followed by an
 753 .Tn ASCII
 754 .Dv NUL
 755 character (character code 0).
 756 .It Ic -prune
 757 This primary always evaluates to true.
 758 It causes
 759 .Nm
 760 to not descend into the current file.
 761 Note, the
 762 .Ic -prune
 763 primary has no effect if the
 764 .Fl d
 765 option was specified.
 766 .It Ic -quit
 767 Causes
 768 .Nm
 769 to immediately terminate successfully.
 770 .It Ic -regex Ar pattern
 771 True if the whole path of the file matches
 772 .Ar pattern
 773 using regular expression.
 774 To match a file named
 775 .Dq Pa ./foo/xyzzy ,
 776 you can use the regular expression
 777 .Dq Li ".*/[xyz]*"
 778 or
 779 .Dq Li ".*/foo/.*" ,
 780 but not
 781 .Dq Li xyzzy
 782 or
 783 .Dq Li /foo/ .
 784 .It Ic -samefile Ar name
 785 True if the file is a hard link to
 786 .Ar name .
 787 If the command option
 788 .Ic -L
 789 is specified, it is also true if the file is a symbolic link and
 790 points to
 791 .Ar name .
 792 .It Ic -size Ar n Ns Op Cm ckMGTP
 793 True if the file's size, rounded up, in 512-byte blocks is
 794 .Ar n .
 795 If
 796 .Ar n
 797 is followed by a
 798 .Cm c ,
 799 then the primary is true if the
 800 file's size is
 801 .Ar n
 802 bytes (characters).
 803 Similarly if
 804 .Ar n
 805 is followed by a scale indicator then the file's size is compared to
 806 .Ar n
 807 scaled as:
 808 .Pp
 809 .Bl -tag -width indent -compact
 810 .It Cm k
 811 kilobytes (1024 bytes)
 812 .It Cm M
 813 megabytes (1024 kilobytes)
 814 .It Cm G
 815 gigabytes (1024 megabytes)
 816 .It Cm T
 817 terabytes (1024 gigabytes)
 818 .It Cm P
 819 petabytes (1024 terabytes)
 820 .El
 821 .It Ic -sparse
 822 True if the current file is sparse,
 823 i.e. has fewer blocks allocated than expected based on its size in bytes.
 824 This might also match files that have been compressed by the filesystem.
 825 .It Ic -type Ar t
 826 True if the file is of the specified type.
 827 Possible file types are as follows:
 828 .Pp
 829 .Bl -tag -width indent -compact
 830 .It Cm b
 831 block special
 832 .It Cm c
 833 character special
 834 .It Cm d
 835 directory
 836 .It Cm f
 837 regular file
 838 .It Cm l
 839 symbolic link
 840 .It Cm p
 841 FIFO
 842 .It Cm s
 843 socket
 844 .El
 845 .It Ic -uid Ar uname
 846 The same thing as
 847 .Ar -user Ar uname
 848 for compatibility with GNU find.
 849 GNU find imposes a restriction that
 850 .Ar uname
 851 is numeric, while
 852 .Nm
 853 does not.
 854 .It Ic -user Ar uname
 855 True if the file belongs to the user
 856 .Ar uname .
 857 If
 858 .Ar uname
 859 is numeric and there is no such user name, then
 860 .Ar uname
 861 is treated as a user ID.
 862 .It Ic -wholename Ar pattern
 863 The same thing as
 864 .Ic -path ,
 865 for GNU find compatibility.
 866 .El
 867 .Sh OPERATORS
 868 The primaries may be combined using the following operators.
 869 The operators are listed in order of decreasing precedence.
 870 .Pp
 871 .Bl -tag -width indent -compact
 872 .It Cm \&( Ar expression Cm \&)
 873 This evaluates to true if the parenthesized expression evaluates to
 874 true.
 875 .Pp
 876 .It Cm \&! Ar expression
 877 .It Cm -not Ar expression
 878 This is the unary
 879 .Tn NOT
 880 operator.
 881 It evaluates to true if the expression is false.
 882 .Pp
 883 .It Cm -false
 884 Always false.
 885 .It Cm -true
 886 Always true.
 887 .Pp
 888 .It Ar expression Cm -and Ar expression
 889 .It Ar expression expression
 890 The
 891 .Cm -and
 892 operator is the logical
 893 .Tn AND
 894 operator.
 895 As it is implied by the juxtaposition of two expressions it does not
 896 have to be specified.
 897 The expression evaluates to true if both expressions are true.
 898 The second expression is not evaluated if the first expression is false.
 899 .Pp
 900 .It Ar expression Cm -or Ar expression
 901 The
 902 .Cm -or
 903 operator is the logical
 904 .Tn OR
 905 operator.
 906 The expression evaluates to true if either the first or the second expression
 907 is true.
 908 The second expression is not evaluated if the first expression is true.
 909 .El
 910 .Pp
 911 All operands and primaries must be separate arguments to
 912 .Nm .
 913 Primaries which themselves take arguments expect each argument
 914 to be a separate argument to
 915 .Nm .
 916 .Sh ENVIRONMENT
 917 The
 918 .Ev LANG , LC_ALL , LC_COLLATE , LC_CTYPE , LC_MESSAGES
 919 and
 920 .Ev LC_TIME
 921 environment variables affect the execution of the
 922 .Nm
 923 utility as described in
 924 .Xr environ 7 .
 925 .Sh EXAMPLES
 926 The following examples are shown as given to the shell:
 927 .Bl -tag -width indent
 928 .It Li "find / \e! -name \*q*.c\*q -print"
 929 Print out a list of all the files whose names do not end in
 930 .Pa .c .
 931 .It Li "find / -newer ttt -user wnj -print"
 932 Print out a list of all the files owned by user
 933 .Dq wnj
 934 that are newer
 935 than the file
 936 .Pa ttt .
 937 .It Li "find / \e! \e( -newer ttt -user wnj \e) -print"
 938 Print out a list of all the files which are not both newer than
 939 .Pa ttt
 940 and owned by
 941 .Dq wnj .
 942 .It Li "find / \e( -newer ttt -or -user wnj \e) -print"
 943 Print out a list of all the files that are either owned by
 944 .Dq wnj
 945 or that are newer than
 946 .Pa ttt .
 947 .It Li "find / -newerct '1 minute ago' -print"
 948 Print out a list of all the files whose inode change time is more
 949 recent than the current time minus one minute.
 950 .It Li "find / -type f -exec echo {} \e;"
 951 Use the
 952 .Xr echo 1
 953 command to print out a list of all the files.
 954 .It Li "find -L /usr/ports/packages -type l -exec rm -- {} +"
 955 Delete all broken symbolic links in
 956 .Pa /usr/ports/packages .
 957 .It Li "find /usr/src -name CVS -prune -o -depth +6 -print"
 958 Find files and directories that are at least seven levels deep
 959 in the working directory
 960 .Pa /usr/src .
 961 .It Li "find /usr/src -name CVS -prune -o -mindepth 7 -print"
 962 Is not equivalent to the previous example, since
 963 .Ic -prune
 964 is not evaluated below level seven.
 965 .El
 966 .Sh COMPATIBILITY
 967 The
 968 .Ic -follow
 969 primary is deprecated; the
 970 .Fl L
 971 option should be used instead.
 972 See the
 973 .Sx STANDARDS
 974 section below for details.
 975 .Sh SEE ALSO
 976 .Xr chflags 1 ,
 977 .Xr chmod 1 ,
 978 .Xr cvs 1 ,
 979 .Xr locate 1 ,
 980 .Xr lsvfs 1 ,
 981 .Xr whereis 1 ,
 982 .Xr which 1 ,
 983 .Xr xargs 1 ,
 984 .Xr stat 2 ,
 985 .Xr acl 3 ,
 986 .Xr fts 3 ,
 987 .Xr getgrent 3 ,
 988 .Xr getpwent 3 ,
 989 .Xr strmode 3 ,
 990 .Xr re_format 7 ,
 991 .Xr symlink 7
 992 .Sh STANDARDS
 993 The
 994 .Nm
 995 utility syntax is a superset of the syntax specified by the
 996 .St -p1003.1-2001
 997 standard.
 998 .Pp
 999 All the single character options except
1000 .Fl H
1001 and
1002 .Fl L
1003 as well as
1004 .Ic -amin , -anewer , -cmin , -cnewer , -delete , -empty , -fstype ,
1005 .Ic -iname , -inum , -iregex , -ls , -maxdepth , -mindepth , -mmin ,
1006 .Ic -path , -print0 , -regex, -sparse
1007 and all of the
1008 .Ic -B*
1009 birthtime related primaries are extensions to
1010 .St -p1003.1-2001 .
1011 .Pp
1012 Historically, the
1013 .Fl d , L
1014 and
1015 .Fl x
1016 options were implemented using the primaries
1017 .Ic -depth , -follow ,
1018 and
1019 .Ic -xdev .
1020 These primaries always evaluated to true.
1021 As they were really global variables that took effect before the traversal
1022 began, some legal expressions could have unexpected results.
1023 An example is the expression
1024 .Ic -print Cm -o Ic -depth .
1025 As
1026 .Ic -print
1027 always evaluates to true, the standard order of evaluation
1028 implies that
1029 .Ic -depth
1030 would never be evaluated.
1031 This is not the case.
1032 .Pp
1033 The operator
1034 .Cm -or
1035 was implemented as
1036 .Cm -o ,
1037 and the operator
1038 .Cm -and
1039 was implemented as
1040 .Cm -a .
1041 .Pp
1042 Historic implementations of the
1043 .Ic -exec
1044 and
1045 .Ic -ok
1046 primaries did not replace the string
1047 .Dq Li {}
1048 in the utility name or the
1049 utility arguments if it had preceding or following non-whitespace characters.
1050 This version replaces it no matter where in the utility name or arguments
1051 it appears.
1052 .Pp
1053 The
1054 .Fl E
1055 option was inspired by the equivalent
1056 .Xr grep 1
1057 and
1058 .Xr sed 1
1059 options.
1060 .Sh HISTORY
1061 A
1062 .Nm
1063 command appeared in
1064 .At v1 .
1065 .Sh BUGS
1066 The special characters used by
1067 .Nm
1068 are also special characters to many shell programs.
1069 In particular, the characters
1070 .Dq Li * ,
1071 .Dq Li \&[ ,
1072 .Dq Li \&] ,
1073 .Dq Li \&? ,
1074 .Dq Li \&( ,
1075 .Dq Li \&) ,
1076 .Dq Li \&! ,
1077 .Dq Li \e
1078 and
1079 .Dq Li \&;
1080 may have to be escaped from the shell.
1081 .Pp
1082 As there is no delimiter separating options and file names or file
1083 names and the
1084 .Ar expression ,
1085 it is difficult to specify files named
1086 .Pa -xdev
1087 or
1088 .Pa \&! .
1089 These problems are handled by the
1090 .Fl f
1091 option and the
1092 .Xr getopt 3
1093 .Dq Fl Fl
1094 construct.
1095 .Pp
1096 The
1097 .Ic -delete
1098 primary does not interact well with other options that cause the file system
1099 tree traversal options to be changed.
1100 .Pp
1101 The
1102 .Ic -mindepth
1103 and
1104 .Ic -maxdepth
1105 primaries are actually global options (as documented above).
1106 They should
1107 probably be replaced by options which look like options.