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