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