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