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