Debian Codegraph @

upstream/opensuse-tumbleweed/man1/find.1

raw
1 '\" t
2 .TH FIND 1 \" -*- nroff -*-
3 .SH NAME
4 find \- search for files in a directory hierarchy
5 .SH SYNOPSIS
6 .B find
7 [\-H] [\-L] [\-P] [\-D debugopts] [\-Olevel] [starting-point...\&] [expression]
8 .
9 .SH DESCRIPTION
10 This manual page
11 documents the GNU version of
12 .BR find .
13 GNU
14 .B find
15 searches the directory tree rooted at each given starting-point by
16 evaluating the given expression from left to right, according to the
17 rules of precedence (see section OPERATORS), until the outcome is
18 known (the left hand side is false for \fIand\fR operations, true for
19 .IR or ),
20 at which point
21 .B find
22 moves on to the next file name. If no starting-point is specified,
23 `.\&' is assumed.
24 .PP
25 If you are using
26 .B find
27 in an environment where security is important (for example if you are
28 using it to search directories that are writable by other users), you
29 should read the `Security Considerations' chapter of the findutils
30 documentation, which is called \fBFinding Files\fP and comes with
31 findutils.
32 That document also includes a lot more detail
33 and discussion than this manual page, so you may find it a more useful
34 source of information.
35 .
36 .SH OPTIONS
37 The
38 .BR \-H ,
39 .B \-L
40 and
41 .B \-P
42 options control the treatment of symbolic
43 links. Command-line arguments following these are taken to be names
44 of files or directories to be examined, up to the first argument that
45 begins with `\-', or the argument `(' or `!'. That argument and any
46 following arguments are taken to be the expression describing what is
47 to be searched for. If no paths are given, the current directory is
48 used. If no expression is given, the expression
49 .B \-print
50 is used
51 (but you should probably consider using
52 .B \-print0
53 instead, anyway).
54 .PP
55 This manual page talks about `options' within the expression list.
56 These options control the behaviour of
57 .B find
58 but are specified immediately after the last path name. The five
59 `real' options
60 .BR \-H ,
61 .BR \-L ,
62 .BR \-P ,
63 .B \-D
64 and
65 .B \-O
66 must appear before
67 the first path name, if at all. A double dash
68 .B \-\-
69 could theoretically be used to signal that any remaining arguments
70 are not options, but this does not really work due to the way
71 .B find
72 determines the end of the following path arguments: it does that by reading
73 until an expression argument comes (which also starts with a `-').
74 Now, if a path argument would start with a `-', then
75 .B find
76 would treat it as expression argument instead.
77 Thus, to ensure that all start points are taken as such, and especially to
78 prevent that wildcard patterns expanded by the calling shell are not mistakenly
79 treated as expression arguments, it is generally safer to prefix wildcards or
80 dubious path names with either `./' or to use absolute path names starting
81 with '/'.
82 Alternatively, it is generally safe though non-portable to use the GNU option
83 .B \-files0\-from
84 to pass arbitrary starting points to
85 .BR find .
86
87 .IP \-P
88 Never follow symbolic links. This is the default behaviour. When
89 .B find
90 examines or prints information about files, and the file is a symbolic
91 link, the information used shall be taken from the properties of the
92 symbolic link itself.
93
94 .IP \-L
95 Follow symbolic links. When
96 .B find
97 examines or prints information about files, the information used shall
98 be taken from the properties of the file to which the link points, not
99 from the link itself (unless it is a broken symbolic link or
100 .B find
101 is unable to examine the file to which the link points). Use of this
102 option implies
103 .BR \-noleaf .
104 If you later use the
105 .B \-P
106 option,
107 .B \-noleaf
108 will still be in effect. If
109 .B \-L
110 is in effect and
111 .B find
112 discovers a symbolic link to a subdirectory during its search,
113 the subdirectory pointed to by the symbolic link will be searched.
114 .IP
115 When the
116 .B \-L
117 option is in effect, the
118 .B \-type
119 predicate will always
120 match against the type of the file that a symbolic link points to
121 rather than the link itself (unless the symbolic link is broken).
122 Actions that can cause symbolic links to become broken while
123 .B find
124 is executing (for example
125 .BR \-delete )
126 can give rise to confusing behaviour.
127 Using
128 .B \-L
129 causes the
130 .B \-lname
131 and
132 .B \-ilname
133 predicates always to return
134 false.
135
136 .IP \-H
137 Do not follow symbolic links, except while processing the command
138 line arguments. When
139 .B find
140 examines or prints information about files, the information used
141 shall be taken from the properties of the symbolic link itself.
142 The only exception to this behaviour is when a file specified on the
143 command line is a symbolic link,
144 and the link can be resolved.
145 For that situation, the information used is taken from whatever the
146 link points to
147 (that is, the link is followed).
148 The information about the link itself is used as a fallback if the
149 file pointed to by the symbolic link cannot be examined.
150 If
151 .B \-H
152 is in effect and one of the
153 paths specified on the command line is a symbolic link to a directory,
154 the contents of that directory will be examined (though of course
155 .B \-maxdepth\ 0
156 would prevent this).
157 .P
158 If more than one of
159 .BR \-H ,
160 .B \-L
161 and
162 .B \-P
163 is specified, each overrides the
164 others; the last one appearing on the command line takes effect.
165 Since it is the default, the
166 .B \-P
167 option should be considered to be in
168 effect unless either
169 .B \-H
170 or
171 .B \-L
172 is specified.
173
174 GNU
175 .B find
176 frequently stats files during the processing of the command line
177 itself, before any searching has begun. These options also affect how
178 those arguments are processed. Specifically, there are a number of
179 tests that compare files listed on the command line against a file we
180 are currently considering. In each case, the file specified on the
181 command line will have been examined and some of its properties will
182 have been saved. If the named file is in fact a symbolic link, and
183 the
184 .B \-P
185 option is in effect (or if neither
186 .B \-H
187 nor
188 .B \-L
189 were specified), the information used for the comparison will be taken from
190 the properties of the symbolic link. Otherwise, it will be taken from
191 the properties of the file the link points to. If
192 .B find
193 cannot follow the link (for example because it has insufficient
194 privileges or the link points to a nonexistent file) the properties of
195 the link itself will be used.
196 .P
197 When the
198 .B \-H
199 or
200 .B \-L
201 options are in effect, any symbolic links listed as the argument of
202 .B \-newer
203 will be dereferenced, and the timestamp
204 will be taken from the file to which the symbolic link points. The
205 same consideration applies to
206 .BR \-newerXY ,
207 .B \-anewer
208 and
209 .BR \-cnewer .
210
211 The
212 .B \-follow
213 option has a similar effect to
214 .BR \-L ,
215 though it takes
216 effect at the point where it appears (that is, if
217 .B \-L
218 is not used but
219 .B \-follow
220 is, any symbolic links appearing after
221 .B \-follow
222 on the
223 command line will be dereferenced, and those before it will not).
224
225 .IP "\-D debugopts"
226 Print diagnostic information; this can be helpful to diagnose problems
227 with why
228 .B find
229 is not doing what you want. The list of debug options should be comma
230 separated. Compatibility of the debug options is not guaranteed
231 between releases of findutils. For a complete list of valid debug
232 options, see the output of
233 .BR "find \-D\ help" .
234 Valid debug options include
235 .RS
236 .IP exec
237 Show diagnostic information relating to \-exec, \-execdir, \-ok and \-okdir
238 .IP opt
239 Prints diagnostic information relating to the optimisation of the
240 expression tree; see the \-O option.
241 .IP rates
242 Prints a summary indicating how often each predicate succeeded or
243 failed.
244 .IP search
245 Navigate the directory tree verbosely.
246 .IP stat
247 Print messages as files are examined with the
248 .B stat
249 and
250 .B lstat
251 system calls. The
252 .B find
253 program tries to minimise such calls.
254 .IP tree
255 Show the expression tree in its original and optimized form.
256 .IP all
257 Enable all of the other debug options (but
258 .BR help ).
259 .IP help
260 Explain the debugging options.
261 .RE
262 .IP \-Olevel
263 Enables query optimisation.
264 The
265 .B find
266 program reorders tests to speed up execution while preserving the
267 overall effect; that is, predicates with side effects are not
268 reordered relative to each other. The optimisations performed at each
269 optimisation level are as follows.
270 .RS
271 .IP 0
272 Equivalent to optimisation level 1.
273 .IP 1
274 This is the default optimisation level and corresponds to the
275 traditional behaviour. Expressions are reordered so that tests based
276 only on the names of files (for example
277 .B \-name
278 and
279 .BR \-regex )
280 are performed first.
281 .IP 2
282 Any
283 .B \-type
284 or
285 .B \-xtype
286 tests are performed after any tests based only on the names of files,
287 but before any tests that require information from the inode. On many
288 modern versions of Unix, file types are returned by
289 .B readdir()
290 and so these predicates are faster to evaluate than predicates which
291 need to stat the file first.
292 If you use the
293 .B "\-fstype\ \fIFOO\fR"
294 predicate and specify a filesystem type
295 .I FOO
296 which is not known (that is, present in `/etc/mtab') at the time
297 .B find
298 starts, that predicate is equivalent to
299 .BR \-false .
300 .IP 3
301 At this optimisation level, the full cost-based query optimizer is
302 enabled. The order of tests is modified so that cheap (i.e.\& fast)
303 tests are performed first and more expensive ones are performed later,
304 if necessary. Within each cost band, predicates are evaluated earlier
305 or later according to whether they are likely to succeed or not. For
306 .BR \-o ,
307 predicates which are likely to succeed are evaluated earlier, and for
308 .BR \-a ,
309 predicates which are likely to fail are evaluated earlier.
310 .RE
311 .IP
312 The cost-based optimizer has a fixed idea of how likely any given test
313 is to succeed. In some cases the probability takes account of the
314 specific nature of the test (for example,
315 .B \-type\ f
316 is assumed to be more likely to succeed than
317 .BR "\-type\ c" ).
318 The cost-based optimizer is currently being evaluated.
319 If it does not actually improve the performance of
320 .BR find ,
321 it will be removed again. Conversely, optimisations that prove to be
322 reliable, robust and effective may be enabled at lower optimisation
323 levels over time. However, the default behaviour (i.e.\& optimisation
324 level 1) will not be changed in the 4.3.x release series. The
325 findutils test suite runs all the tests on
326 .B find
327 at each optimisation level and ensures that the result is the same.
328
329 The re-ordering of operations performed by the cost-based optimizer
330 can result in user-visible behaviour change. For example, the
331 .B \-readable
332 and
333 .B \-empty
334 predicates are sensitive to re-ordering. If they are run in the order
335 .BR "\-empty \-readable" ,
336 an error message will be issued for unreadable directories. If they
337 are run in the order
338 .B \-readable \-empty
339 no error message will be issued. This is the reason why such operation
340 re-ordering is not performed at the default optimisation level.
341 .
342 .SH EXPRESSION
343 The part of the command line after the list of starting points is the
344 .IR expression .
345 This is a kind of query specification describing how we match files
346 and what we do with the files that were matched.
347 An expression is composed of a sequence of things:
348
349 .IP Tests
350 Tests return a true or false value, usually on the basis of some
351 property of a file we are considering. The
352 .B \-empty
353 test for example is true only when the current file is empty.
354
355 .IP Actions
356 Actions have side effects (such as printing something on the standard
357 output) and return either true or false, usually based on whether or
358 not they are successful. The
359 .B \-print
360 action for example prints the name of the current file on the standard
361 output.
362
363 .IP "Global options"
364 Global options affect the operation of tests and actions specified on
365 any part of the command line. Global options always return true. The
366 .B \-depth
367 option for example makes
368 .B find
369 traverse the file system in a depth-first order.
370
371 .IP "Positional options"
372 Positional options affect only tests or actions which follow them.
373 Positional options always return true. The
374 .B \-regextype
375 option for example is positional, specifying the regular expression
376 dialect for regular expressions occurring later on the command line.
377
378 .IP Operators
379 Operators join together the other items within the expression. They
380 include for example
381 .B \-o
382 (meaning logical OR) and
383 .B \-a
384 (meaning logical AND). Where an operator is missing,
385 .B \-a
386 is assumed.
387
388 .P
389 The
390 .B \-print
391 action is performed on all files for which the whole expression is
392 true, unless it contains an action other than
393 .B \-prune
394 or
395 .BR \-quit .
396 Actions which inhibit the default
397 .B \-print
398 are
399 .BR \-delete ,
400 .BR \-exec ,
401 .BR \-execdir ,
402 .BR \-ok ,
403 .BR \-okdir ,
404 .BR \-fls ,
405 .BR \-fprint ,
406 .BR \-fprintf ,
407 .BR \-ls ,
408 .B \-print
409 and
410 .BR \-printf .
411
412
413 The
414 .B \-delete
415 action also acts like an option (since it implies
416 .BR \-depth ).
417
418 .SS POSITIONAL OPTIONS
419 Positional options always return true. They affect only tests occurring
420 later on the command line.
421
422 .IP \-daystart
423 Measure times (for
424 .BR \-amin ,
425 .BR \-atime ,
426 .BR \-cmin ,
427 .BR \-ctime ,
428 .BR \-mmin ,
429 and
430 .BR \-mtime )
431 from the beginning of today rather than from 24 hours ago. This
432 option only affects tests which appear later on the command line.
433
434 .IP \-follow
435 Deprecated; use the
436 .B \-L
437 option instead. Dereference symbolic links.
438 Implies
439 .BR \-noleaf .
440 The
441 .B \-follow
442 option affects only those tests which
443 appear after it on the command line. Unless the
444 .B \-H
445 or
446 .B \-L
447 option has
448 been specified, the position of the
449 .B \-follow
450 option changes the behaviour of the
451 .B \-newer
452 predicate; any files listed as the argument
453 of
454 .B \-newer
455 will be dereferenced if they are symbolic links. The same
456 consideration applies to
457 .BR \-newerXY ,
458 .B \-anewer
459 and
460 .BR \-cnewer .
461 Similarly, the
462 .B \-type
463 predicate will always match against the type of the file
464 that a symbolic link points to rather than the link itself. Using
465 .B \-follow
466 causes the
467 .B \-lname and
468 .B \-ilname
469 predicates always to return false.
470
471 .IP "\-regextype \fItype\fR"
472 Changes the regular expression syntax understood by
473 .B \-regex
474 and
475 .B \-iregex
476 tests which occur later on the command line. To see which regular
477 expression types are known, use
478 .BR "\-regextype\ help" .
479 The Texinfo documentation (see
480 .B SEE
481 .BR ALSO )
482 explains the meaning of and differences between the various types of
483 regular expression. If you do not use this option, find behaves
484 as if the regular expression type
485 .B emacs
486 had been specified.
487
488 .IP "\-warn, \-nowarn"
489 Turn warning messages on or off. These warnings apply only to the
490 command line usage, not to any conditions that
491 .B find
492 might encounter when it searches directories. The default behaviour
493 corresponds to
494 .B \-warn
495 if standard input is a tty, and to
496 .B \-nowarn
497 otherwise. If a warning message relating to command-line usage is
498 produced, the exit status of
499 .B find
500 is not affected. If the
501 .B POSIXLY_CORRECT
502 environment variable is set, and
503 .B \-warn
504 is also used, it is not specified which, if any, warnings will be active.
505
506 .SS GLOBAL OPTIONS
507 Global options always return true.
508 Global options take effect even for tests which occur earlier on the
509 command line. To prevent confusion, global options should be specified
510 on the command-line after the list of start points, just before the
511 first test, positional option or action.
512 If you specify a global option in some other place,
513 .B find
514 will issue a warning message explaining that this can be confusing.
515
516 The global options occur after the list of start points, and so are
517 not the same kind of option as
518 .BR \-L ,
519 for example.
520
521 .IP \-d
522 A synonym for \-depth, for compatibility with FreeBSD, NetBSD, \
523 MacOS X and OpenBSD.
524
525 .IP \-depth
526 Process each directory's contents before the directory itself. The
527 \-delete action also implies
528 .BR \-depth .
529
530 .IP "\-files0\-from \fIfile\fR"
531 Read the starting points from \fIfile\fR instead of getting them on the
532 command line.
533 In contrast to the known limitations of passing starting points via arguments
534 on the command line, namely the limitation of the amount of file names,
535 and the inherent ambiguity of file names clashing with option names,
536 using this option allows to safely pass an arbitrary number of starting points
537 to \fBfind\fR.
538
539 Using this option and passing starting points on the command line is mutually
540 exclusive, and is therefore not allowed at the same time.
541
542 The \fIfile\fR argument is mandatory.
543 One can use
544 .B \-files0\-from\ \-
545 to read the list of starting points from the \fIstandard input\fR stream,
546 and e.g. from a pipe.
547 In this case, the actions
548 .B \-ok
549 and
550 .B \-okdir
551 are not allowed, because they would obviously interfere with reading from
552 \fIstandard input\fR in order to get a user confirmation.
553
554 The starting points in \fIfile\fR have to be separated by ASCII NUL characters.
555 Two consecutive NUL characters, i.e., a starting point with a Zero-length
556 file name is not allowed and will lead to an error diagnostic followed by
557 a non-Zero exit code later.
558
559 In the case the given \fIfile\fR is empty, \fBfind\fR does not process any
560 starting point and therefore will exit immediately after parsing the program
561 arguments.
562 This is unlike the standard invocation where \fBfind\fR assumes the current
563 directory as starting point if no path argument is passed.
564
565 The processing of the starting points is otherwise as usual, e.g.
566 .B find
567 will recurse into subdirectories unless otherwise prevented.
568 To process only the starting points, one can additionally pass
569 .BR \-maxdepth\ 0 .
570
571 Further notes:
572 if a file is listed more than once in the input file, it is unspecified
573 whether it is visited more than once.
574 If the \fIfile\fR is mutated during the operation of
575 .BR find ,
576 the result is unspecified as well.
577 Finally, the seek position within the named \fIfile\fR at the time
578 .B find
579 exits, be it with
580 .B \-quit
581 or in any other way, is also unspecified.
582 By "unspecified" here is meant that it may or may not work or do any specific
583 thing, and that the behavior may change from platform to platform, or from
584 .B findutils
585 release to release.
586
587 .IP "\-help, \-\-help"
588 Print a summary of the command-line usage of
589 .B find
590 and exit.
591
592 .IP \-ignore_readdir_race
593 Normally, \fBfind\fR will emit an error message when it fails to stat a file.
594 If you give this option and a file is deleted between the time \fBfind\fR
595 reads the name of the file from the directory and the time it tries to stat
596 the file, no error message will be issued.
597 This also applies to files or directories whose names are given on the
598 command line.
599 This option takes effect at the time the command line is read,
600 which means that you cannot search one part of the filesystem with
601 this option on and part of it with this option off
602 (if you need to do that, you will need to issue two \fBfind\fR commands
603 instead, one with the option and one without it).
604
605 Furthermore,
606 .B find
607 with the
608 .B \-ignore_readdir_race
609 option will ignore errors of the
610 .B \-delete
611 action in the case the file has disappeared since the parent directory was read:
612 it will not output an error diagnostic, and the return code of the
613 .B \-delete
614 action will be true.
615
616 .IP "\-maxdepth \fIlevels\fR"
617 Descend at most \fIlevels\fR (a non-negative integer) levels of
618 directories below the starting-points. Using
619 .B \-maxdepth\ 0
620 means only apply the tests and actions to the starting-points themselves.
621
622 .IP "\-mindepth \fIlevels\fR"
623 Do not apply any tests or actions at levels less than \fIlevels\fR (a
624 non-negative integer). Using
625 .B \-mindepth\ 1
626 means process all files except the starting-points.
627
628 .IP \-mount
629 Don't descend directories on other filesystems. An alternate name for
630 .BR \-xdev ,
631 for compatibility with some other versions of
632 .BR find .
633
634 .IP \-noignore_readdir_race
635 Turns off the effect of
636 .BR \-ignore_readdir_race .
637
638 .IP "\-noleaf"
639 Do not optimize by assuming that directories contain 2 fewer
640 subdirectories than their hard link count. This option is needed when
641 searching filesystems that do not follow the Unix directory-link
642 convention, such as CD-ROM or MS-DOS filesystems or AFS volume mount
643 points. Each directory on a normal Unix filesystem has at least 2
644 hard links: its name and its `.\&' entry. Additionally, its
645 subdirectories (if any) each have a `..\&' entry linked to that
646 directory. When
647 .B find
648 is examining a directory, after it has statted 2 fewer subdirectories
649 than the directory's link count, it knows that the rest of the entries
650 in the directory are non-directories (`leaf' files in the directory
651 tree). If only the files' names need to be examined, there is no need
652 to stat them; this gives a significant increase in search speed.
653
654 .IP "\-version, \-\-version"
655 Print the \fBfind\fR version number and exit.
656
657 .IP \-xautofs
658 Don't descend directories on autofs filesystems.
659
660 .IP \-xdev
661 Don't descend directories on other filesystems.
662
663 .SS TESTS
664 Some tests, for example
665 .B \-newerXY
666 and
667 .BR \-samefile ,
668 allow comparison between the file currently being examined and some
669 reference file specified on the command line. When these tests are
670 used, the interpretation of the reference file is determined by the
671 options
672 .BR \-H ,
673 .B \-L
674 and
675 .B \-P
676 and any previous
677 .BR \-follow ,
678 but the reference file is only examined once, at the time the command
679 line is parsed. If the reference file cannot be examined (for
680 example, the
681 .BR stat (2)
682 system call fails for it), an error message is issued, and
683 .B find
684 exits with a nonzero status.
685 .P
686 A numeric argument \fIn\fR can be specified to tests (like
687 .BR \-amin ,
688 .BR \-mtime ,
689 .BR \-gid ,
690 .BR \-inum ,
691 .BR \-links ,
692 .BR \-size ,
693 .BR \-uid
694 and
695 .BR \-used )
696 as
697 .IP \fI+n\fP
698 for greater than
699 .IR n ,
700 .IP \fI\-n\fP
701 for less than
702 .IR n ,
703 .IP \fIn\fP
704 for exactly
705 .IR n .
706 .
707 .P
708 Supported tests:
709
710 .IP "\-amin \fIn\fR"
711 File was last accessed less than, more than or exactly \fIn\fR minutes ago.
712
713 .IP "\-anewer \fIreference\fR"
714 Time of the last access of the current file is more recent than that
715 of the last data modification of the \fIreference\fR file.
716 If \fIreference\fR is a symbolic link and the
717 .B \-H
718 option or the
719 .B \-L
720 option is in effect, then the time of the last data modification of the file
721 it points to is always used.
722
723 .IP "\-atime \fIn\fR"
724 File was last accessed less than, more than or exactly
725 .IR n *24
726 hours ago.
727 When
728 .B find
729 figures out how many 24-hour periods ago the file
730 was last accessed, any fractional part is ignored, so to match
731 .BR "\-atime\ +1" ,
732 a file has to have been accessed at least
733 .I two
734 days ago.
735
736 .IP "\-cmin \fIn\fR"
737 File's status was last changed less than, more than or exactly \fIn\fR minutes
738 ago.
739
740 .IP "\-cnewer \fIreference\fR"
741 Time of the last status change of the current file is more recent than that
742 of the last data modification of the \fIreference\fR file.
743 If \fIreference\fR is a symbolic link and the
744 .B \-H
745 option or the
746 .B \-L
747 option is in effect, then the time of the last data modification of the file
748 it points to is always used.
749
750 .IP "\-ctime \fIn\fR"
751 File's status was last changed less than, more than or exactly
752 .IR n *24
753 hours ago.
754 See the comments for
755 .B \-atime
756 to understand how rounding affects the interpretation of file status
757 change times.
758
759 .IP \-empty
760 File is empty and is either a regular file or a directory.
761
762 .IP \-executable
763 Matches files which are executable and directories which are
764 searchable (in a file name resolution sense) by the current user.
765 This takes into account access control lists and other permissions
766 artefacts which the
767 .B \-perm
768 test ignores. This test makes use of the
769 .BR access (2)
770 system call, and so can be fooled by NFS servers which do UID
771 mapping (or root-squashing), since many systems implement
772 .BR access (2)
773 in the client's kernel and so cannot make use of the UID mapping
774 information held on the server. Because this test is based only on
775 the result of the
776 .BR access (2)
777 system call, there is no guarantee that a file for which this test
778 succeeds can actually be executed.
779
780 .IP \-false
781 Always false.
782
783 .IP "\-fstype \fItype\fR"
784 File is on a filesystem of type
785 .IR type .
786 The valid filesystem types vary among different versions of Unix;
787 an incomplete list of
788 filesystem types that are accepted on some version of Unix or another
789 is: ufs, 4.2, 4.3, nfs, tmp, mfs, S51K, S52K. You can use
790 .B \-printf
791 with the %F directive to see the types of your filesystems.
792
793 .IP "\-gid \fIn\fR"
794 File's numeric group ID is less than, more than or exactly
795 .IR n .
796
797 .IP "\-group \fIgname\fR"
798 File belongs to group \fIgname\fR (numeric group ID allowed).
799
800 .IP "\-ilname \fIpattern\fR"
801 Like
802 .BR \-lname ,
803 but the match is case insensitive.
804 If the
805 .B \-L
806 option or the
807 .B \-follow
808 option is in effect, this test returns false unless the symbolic link
809 is broken.
810
811
812 .IP "\-iname \fIpattern\fR"
813 Like
814 .BR \-name ,
815 but the match is case insensitive. For example, the
816 patterns `fo*' and `F??' match the file names `Foo', `FOO', `foo',
817 `fOo', etc.
818 The pattern `*foo*` will also match a file called '.foobar'.
819
820 .IP "\-inum \fIn\fR"
821 File has inode number smaller than, greater than or exactly
822 .IR n .
823 It is normally easier to use the
824 .B \-samefile
825 test instead.
826
827 .IP "\-ipath \fIpattern\fR"
828 Like
829 .BR \-path .
830 but the match is case insensitive.
831
832 .IP "\-iregex \fIpattern\fR"
833 Like
834 .BR \-regex ,
835 but the match is case insensitive.
836
837 .IP "\-iwholename \fIpattern\fR"
838 See \-ipath. This alternative is less portable than
839 .BR \-ipath .
840
841 .IP "\-links \fIn\fR"
842 File has less than, more than or exactly \fIn\fR hard links.
843
844 .IP "\-lname \fIpattern\fR"
845 File is a symbolic link whose contents match shell pattern
846 .IR pattern .
847 The metacharacters do not treat `/' or `.\&' specially.
848 If the
849 .B \-L
850 option or the
851 .B \-follow
852 option is in effect, this test returns false unless the symbolic link
853 is broken.
854
855 .IP "\-mmin \fIn\fR"
856 File's data was last modified less than, more than or exactly \fIn\fR minutes
857 ago.
858
859 .IP "\-mtime \fIn\fR"
860 File's data was last modified less than, more than or exactly
861 .IR n *24
862 hours ago.
863 See the comments for
864 .B \-atime
865 to understand how rounding affects the interpretation of file
866 modification times.
867
868 .IP "\-name \fIpattern\fR"
869 Base of file name (the path with the leading directories removed)
870 matches shell pattern
871 .IR pattern .
872 Because the leading directories of the file names are removed, the
873 .I pattern
874 should not include a slash, because `\-name a/b' will never match anything
875 (and you probably want to use
876 .B \-path
877 instead).
878 An exception to this is when using only a slash as \fIpattern\fR (`-name /'),
879 because that is a valid string for matching the root directory "/" (because the
880 base name of "/" is "/").
881 A warning is issued if you try to pass a pattern containing a - but not
882 consisting solely of one - slash, unless the environment variable
883 .B POSIXLY_CORRECT
884 is set or the option
885 .B \-nowarn
886 is used.
887
888 To ignore a
889 directory and the files under it, use
890 .B \-prune
891 rather than checking every file in the tree;
892 see an example in the description of that action.
893 Braces are not recognised as being
894 special, despite the fact that some shells including Bash imbue braces
895 with a special meaning in shell patterns. The filename matching is
896 performed with the use of the
897 .BR fnmatch (3)
898 library function.
899 Don't forget to enclose the pattern in quotes in order to protect it
900 from expansion by the shell.
901
902 .IP "\-newer \fIreference\fR"
903 Time of the last data modification of the current file is more recent than that
904 of the last data modification of the \fIreference\fR file.
905 If \fIreference\fR is a symbolic link and the
906 .B \-H
907 option or the
908 .B \-L
909 option is in effect, then the time of the last data modification of the file
910 it points to is always used.
911
912 .IP "\-newerXY \fIreference\fR"
913 Succeeds if timestamp \fIX\fR of the file being considered is newer
914 than timestamp \fIY\fR of the file
915 .IR reference .
916 The letters \fIX\fR and \fIY\fR can be any of the following letters:
917
918 .TS
919 ll
920 ll
921 ll
922 ll
923 llw(2i).
924 a The access time of the file \fIreference\fR
925 B The birth time of the file \fIreference\fR
926 c The inode status change time of \fIreference\fR
927 m The modification time of the file \fIreference\fR
928 t \fIreference\fR is interpreted directly as a time
929 .TE
930
931 Some combinations are invalid; for example, it is invalid for
932 .I X
933 to be
934 .IR t .
935 Some combinations are not implemented on all systems; for example
936 .I B
937 is not supported on all systems. If an invalid or unsupported
938 combination of
939 .I XY
940 is specified, a fatal error results. Time specifications are
941 interpreted as for the argument to the
942 .B \-d
943 option of GNU
944 .BR date .
945 If you try to use the birth time of a reference file, and the birth
946 time cannot be determined, a fatal error message results. If you
947 specify a test which refers to the birth time of files being examined,
948 this test will fail for any files where the birth time is unknown.
949
950 .IP \-nogroup
951 No group corresponds to file's numeric group ID.
952
953 .IP \-nouser
954 No user corresponds to file's numeric user ID.
955
956 .IP "\-path \fIpattern\fR"
957 File name matches shell pattern
958 .IR pattern .
959 The metacharacters do not treat `/' or `.\&' specially;
960 so, for example,
961 .in +4m
962 .nf
963 find . \-path \(dq./sr*sc\(dq
964 .fi
965 .in
966 will print an entry for a directory called
967 .I ./src/misc
968 (if one exists). To ignore a whole directory tree, use
969 .B \-prune
970 rather than
971 checking every file in the tree.
972 Note that the pattern match test applies to the whole file name,
973 starting from one of the start points named on the command line. It
974 would only make sense to use an absolute path name here if the
975 relevant start point is also an absolute path. This means that this
976 command will never match anything:
977 .br
978 .in +4m
979 .nf
980 find bar \-path /foo/bar/myfile \-print
981 .fi
982 .in
983 Find compares the
984 .B \-path
985 argument with the concatenation of a directory name and the base name
986 of the file it's examining. Since the concatenation will never end
987 with a slash,
988 .B \-path
989 arguments ending in a slash will match nothing (except perhaps a start
990 point specified on the command line).
991 The predicate
992 .B \-path
993 is also supported by HP-UX
994 .B find
995 and is part of the POSIX 2008 standard.
996
997 .IP "\-perm \fImode\fR"
998 File's permission bits are exactly \fImode\fR (octal or symbolic).
999 Since an exact match is required, if you want to use this form for
1000 symbolic modes, you may have to specify a rather complex mode string.
1001 For example `\-perm g=w' will only match files which have mode 0020
1002 (that is, ones for which group write permission is the only permission
1003 set). It is more likely that you will want to use the `/' or `\-'
1004 forms, for example `\-perm \-g=w', which matches any file with group
1005 write permission. See the
1006 .B EXAMPLES
1007 section for some illustrative examples.
1008
1009 .IP "\-perm \-\fImode\fR"
1010 All of the permission bits \fImode\fR are set for the file.
1011 Symbolic modes are accepted in this form, and this is usually the way
1012 in which you would want to use them. You must specify `u', `g' or `o' if
1013 you use a symbolic mode.
1014 See the
1015 .B EXAMPLES
1016 section for some illustrative examples.
1017
1018 .IP "\-perm /\fImode\fR"
1019 Any of the permission bits \fImode\fR are set for the file. Symbolic
1020 modes are accepted in this form. You must specify `u', `g' or `o' if
1021 you use a symbolic mode. See the
1022 .B EXAMPLES
1023 section for some illustrative examples. If no permission bits in
1024 .I mode
1025 are set, this test matches any file (the idea here is to be consistent
1026 with the behaviour of
1027 .BR "\-perm\ \-000" ).
1028
1029 .IP "\-perm +\fImode\fR"
1030 This is no longer supported (and has been deprecated since 2005). Use
1031 .B "\-perm /\fImode\fR"
1032 instead.
1033
1034 .IP \-readable
1035 Matches files which are readable by the current user. This takes into
1036 account access control lists and other permissions artefacts which the
1037 .B \-perm
1038 test ignores. This test makes use of the
1039 .BR access (2)
1040 system call, and so can be fooled by NFS servers which do UID
1041 mapping (or root-squashing), since many systems implement
1042 .BR access (2)
1043 in the client's kernel and so cannot make use of the UID mapping
1044 information held on the server.
1045
1046 .IP "\-regex \fIpattern\fR"
1047 File name matches regular expression
1048 .IR pattern .
1049 This is a match on the whole path, not a search.
1050 For example, to match a file named
1051 .IR ./fubar3,
1052 you can use the regular expression `.*bar.\&' or `.*b.*3',
1053 but not `f.*r3'.
1054 The regular expressions understood by
1055 .B find
1056 are by default Emacs Regular Expressions, but this can be changed with
1057 the
1058 .B \-regextype
1059 option.
1060
1061 .IP "\-samefile \fIname\fR"
1062 File refers to the same inode as
1063 .IR name .
1064 When
1065 .B \-L
1066 is in effect, this can include symbolic links.
1067
1068 .IP "\-size \fIn\fR[cwbkMG]"
1069 File uses less than, more than or exactly \fIn\fP units of space, rounding up.
1070 The following suffixes can be used:
1071 .RS
1072 .IP `b'
1073 for 512-byte blocks (this is the default if no suffix is used)
1074 .IP `c'
1075 for bytes
1076 .IP `w'
1077 for two-byte words
1078 .IP `k'
1079 for kibibytes (KiB, units of 1024 bytes)
1080 .IP `M'
1081 for mebibytes (MiB, units of 1024 * 1024 = 1\|048\|576 bytes)
1082 .IP `G'
1083 for gibibytes (GiB, units of 1024 * 1024 * 1024 = 1\|073\|741\|824 bytes)
1084 .RE
1085 .IP
1086 The size is simply the st_size member of the struct stat populated by
1087 the lstat (or stat) system call, rounded up as shown above.
1088 In other words, it's consistent with the result you get for
1089 .BR "ls\ \-l" .
1090 Bear in
1091 mind that the `%k' and `%b' format specifiers of
1092 .B \-printf
1093 handle sparse files
1094 differently. The `b' suffix always denotes 512-byte blocks and never
1095 1024-byte blocks, which is different to the behaviour of
1096 .BR \-ls .
1097 .IP
1098 The + and - prefixes signify greater than and less than, as usual;
1099 i.e., an exact size of \fIn\fR units does not match.
1100 Bear in mind that the size is rounded up to the next unit.
1101 Therefore
1102 .B \-size\ \-1M
1103 is not equivalent to
1104 .BR "\-size\ \-1\|048\|576c" .
1105 The former only matches empty files, the latter matches files from 0 to
1106 1,048,575 bytes.
1107 .IP \-true
1108 Always true.
1109
1110 .IP "\-type \fIc\fR"
1111 File is of type
1112 .IR c :
1113 .RS
1114 .IP b
1115 block (buffered) special
1116 .IP c
1117 character (unbuffered) special
1118 .IP d
1119 directory
1120 .IP p
1121 named pipe (FIFO)
1122 .IP f
1123 regular file
1124 .IP l
1125 symbolic link; this is never true if the
1126 .B \-L
1127 option or the
1128 .B \-follow
1129 option is in effect, unless the symbolic link is broken. If you want
1130 to search for symbolic links when
1131 .B \-L
1132 is in effect, use
1133 .BR \-xtype .
1134 .IP s
1135 socket
1136 .IP D
1137 door (Solaris)
1138 .RE
1139 .IP
1140 To search for more than one type at once, you can supply the combined list of
1141 type letters separated by a comma `,' (GNU extension).
1142 .IP "\-uid \fIn\fR"
1143 File's numeric user ID is less than, more than or exactly
1144 .IR n .
1145
1146 .IP "\-used \fIn\fR"
1147 File was last accessed less than, more than or exactly \fIn\fR days after its
1148 status was last changed.
1149
1150 .IP "\-user \fIuname\fR"
1151 File is owned by user \fIuname\fR (numeric user ID allowed).
1152
1153 .IP "\-wholename \fIpattern\fR"
1154 See \-path. This alternative is less portable than
1155 .BR \-path .
1156
1157 .IP "\-writable"
1158 Matches files which are writable by the current user. This takes into
1159 account access control lists and other permissions artefacts which the
1160 .B \-perm
1161 test ignores. This test makes use of the
1162 .BR access (2)
1163 system call, and so can be fooled by NFS servers which do UID
1164 mapping (or root-squashing), since many systems implement
1165 .BR access (2)
1166 in the client's kernel and so cannot make use of the UID mapping
1167 information held on the server.
1168
1169 .IP "\-xtype \fIc\fR"
1170 The same as
1171 .B \-type
1172 unless the file is a symbolic link. For symbolic
1173 links: if the
1174 .B \-H
1175 or
1176 .B \-P
1177 option was specified, true if the file is a
1178 link to a file of type
1179 .IR c ;
1180 if the
1181 .B \-L
1182 option has been given, true
1183 if \fIc\fR is `l'.
1184 In other words, for symbolic links,
1185 .B \-xtype
1186 checks the type of the file that
1187 .B \-type
1188 does not check.
1189 If a symbolic link is broken (because the thing it points to does not
1190 exist or the link points to itself) then
1191 .B \-xtype
1192 will behave the same as
1193 .BR \-type .
1194 .IP "\-context \fIpattern\fR"
1195 (SELinux only) Security context of the file matches glob
1196 .IR pattern .
1197
1198 .SS ACTIONS
1199 .IP "\-delete\fR"
1200 Delete files or directories; true if removal succeeded.
1201 If the removal failed, an error message is issued and
1202 .BR find 's
1203 exit status will be nonzero (when it eventually exits).
1204
1205 .BR Warning :
1206 Don't forget that
1207 .B find
1208 evaluates the command line as an
1209 expression, so putting
1210 .B \-delete
1211 first will make
1212 .B find
1213 try to delete everything below the starting points you specified.
1214
1215 The use of the
1216 .B \-delete
1217 action on the command line automatically turns on the
1218 .B \-depth
1219 option.
1220 As in turn
1221 .B \-depth
1222 makes
1223 .B \-prune
1224 ineffective, the
1225 .B \-delete
1226 action cannot usefully be combined with
1227 .BR \-prune .
1228
1229 Often, the user might want to test a
1230 .B find
1231 command line with
1232 .B \-print
1233 prior to adding
1234 .B \-delete
1235 for the actual removal run.
1236 To avoid surprising results, it is usually best to remember to use
1237 .B \-depth
1238 explicitly during those earlier test runs.
1239
1240 The
1241 .B \-delete
1242 action will fail to remove a directory unless it is empty.
1243
1244 Together with the
1245 .B \-ignore_readdir_race
1246 option,
1247 .B find
1248 will ignore errors of the
1249 .B \-delete
1250 action in the case the file has disappeared since the parent directory was
1251 read: it will not output an error diagnostic, not change the exit code to
1252 nonzero, and the return code of the
1253 .B \-delete
1254 action will be true.
1255
1256
1257 .IP "\-exec \fIcommand\fR ;"
1258 Execute
1259 .IR command ;
1260 true if 0 status is returned. All following
1261 arguments to
1262 .B find
1263 are taken to be arguments to the command until an argument consisting
1264 of `;' is encountered. The string `{}' is replaced by the current
1265 file name being processed everywhere it occurs in the arguments to the
1266 command, not just in arguments where it is alone, as in some versions
1267 of
1268 .BR find .
1269 Both of these constructions might need to be escaped (with a `\e') or
1270 quoted to protect them from expansion by the shell. See the
1271 .B EXAMPLES
1272 section for examples of the use of the
1273 .B \-exec
1274 option. The specified
1275 command is run once for each matched file.
1276 The command is executed in the starting directory.
1277 There are unavoidable security problems surrounding use of the
1278 .B \-exec
1279 action;
1280 you should use the
1281 .B \-execdir
1282 option instead.
1283
1284 .IP "\-exec \fIcommand\fR {} +"
1285 This variant of the
1286 .B \-exec
1287 action runs the specified command on the
1288 selected files, but the command line is built by appending each
1289 selected file name at the end; the total number of invocations of the
1290 command will be much less than the number of matched files. The
1291 command line is built in much the same way that
1292 .B xargs
1293 builds its command lines. Only one instance of `{}' is allowed within
1294 the command, and it must appear at the end, immediately before the `+';
1295 it needs to be escaped (with a `\e') or quoted to protect it from
1296 interpretation by the shell.
1297 The command is executed in the starting directory. If any invocation
1298 with the `+' form returns a non-zero value as exit status, then
1299 .B find
1300 returns a non-zero exit status. If
1301 .B find
1302 encounters an error, this can sometimes cause an
1303 immediate exit, so some pending commands may not be run
1304 at all. For this reason
1305 .B \-exec\ \fImy-command\fP\ ...\ {}\ +\ \-quit
1306 may not result in
1307 .I my-command
1308 actually being run. This variant of
1309 .B \-exec
1310 always returns true.
1311
1312 .IP "\-execdir \fIcommand\fR ;"
1313 .IP "\-execdir \fIcommand\fR {} +"
1314 Like
1315 .BR \-exec ,
1316 but the specified command is run from the subdirectory
1317 containing the matched file, which is not normally the directory in
1318 which you started
1319 .BR find .
1320 As with \-exec, the {} should be quoted if find is being invoked from
1321 a shell.
1322 This a much more secure method for invoking commands, as it avoids
1323 race conditions during resolution of the paths to the matched files.
1324 As with the
1325 .B \-exec
1326 action, the `+' form of
1327 .B \-execdir
1328 will build a
1329 command line to process more than one matched file, but any given
1330 invocation of
1331 .I command
1332 will only list files that exist in the same subdirectory. If you use
1333 this option, you must ensure that your
1334 .B PATH
1335 environment variable does not reference `.';
1336 otherwise, an attacker can run any commands they like by leaving an
1337 appropriately-named file in a directory in which you will run
1338 .BR \-execdir .
1339 The same applies to having entries in
1340 .B PATH
1341 which are empty or which are not absolute directory names. If
1342 any invocation with the `+' form returns a non-zero value as exit status,
1343 then
1344 .B find
1345 returns a non-zero exit status. If
1346 .B find
1347 encounters an error, this can sometimes cause an
1348 immediate exit, so some pending commands may not be run
1349 at all.
1350 The result of the action depends on whether the
1351 .B +
1352 or the
1353 .B ;
1354 variant is being used;
1355 .B \-execdir\ \fIcommand\fP\ {}\ +
1356 always returns true, while
1357 .B \-execdir\ \fIcommand\fP\ {}\ ;
1358 returns true only if
1359 .I command
1360 returns 0.
1361
1362
1363 .IP "\-fls \fIfile\fR"
1364 True; like
1365 .B \-ls
1366 but write to \fIfile\fR like
1367 .BR \-fprint .
1368 The output file is always created, even if the predicate is never
1369 matched.
1370 See the
1371 .B UNUSUAL FILENAMES
1372 section for information about how unusual characters in filenames are handled.
1373
1374 .IP "\-fprint \fIfile\fR"
1375 True; print the full file name into file
1376 .IR file .
1377 If \fIfile\fR
1378 does not exist when \fBfind\fR is run, it is created; if it does
1379 exist, it is truncated. The file names
1380 .I /dev/stdout
1381 and
1382 .I /dev/stderr
1383 are handled specially; they refer to the standard
1384 output and standard error output, respectively.
1385 The output file is always created, even if the predicate is never matched.
1386 See the
1387 .B UNUSUAL FILENAMES
1388 section for information about how unusual characters in filenames are handled.
1389
1390 .IP "\-fprint0 \fIfile\fR"
1391 True; like
1392 .B \-print0
1393 but write to \fIfile\fR like
1394 .BR \-fprint .
1395 The output file is always created, even if the predicate is never matched.
1396 See the
1397 .B UNUSUAL FILENAMES
1398 section for information about how unusual characters in filenames are handled.
1399
1400 .IP "\-fprintf \fIfile\fR \fIformat\fR"
1401 True; like
1402 .B \-printf
1403 but write to \fIfile\fR like
1404 .BR \-fprint .
1405 The output file is always created, even if the predicate is never matched.
1406 See the
1407 .B UNUSUAL FILENAMES
1408 section for information about how unusual characters in filenames are handled.
1409
1410 .IP \-ls
1411 True; list current file in
1412 .B ls \-dils
1413 format on standard output.
1414 The block counts are of 1\ KB blocks, unless the environment variable
1415 .B POSIXLY_CORRECT
1416 is set, in which case 512-byte blocks are used.
1417 See the
1418 .B UNUSUAL FILENAMES
1419 section for information about how unusual characters in filenames are handled.
1420
1421 .IP "\-ok \fIcommand\fR ;"
1422 Like
1423 .B \-exec
1424 but ask the user first. If the user agrees, run the command. Otherwise
1425 just return false. If the command is run, its standard input is redirected
1426 from
1427 .IR /dev/null .
1428 This action may not be specified together with the
1429 .B \-files0\-from
1430 option.
1431
1432 .IP
1433 The response to the prompt is matched against a pair of regular
1434 expressions to determine if it is an affirmative or negative
1435 response. This regular expression is obtained from the system if the
1436 .B POSIXLY_CORRECT
1437 environment variable is set, or otherwise from
1438 .BR find 's
1439 message translations. If the system has no suitable
1440 definition,
1441 .BR find 's
1442 own definition will be used.
1443 In either case, the interpretation of the regular expression itself
1444 will be affected by the environment variables
1445 .B LC_CTYPE
1446 (character classes) and
1447 .B LC_COLLATE
1448 (character ranges and equivalence classes).
1449
1450
1451
1452 .IP "\-okdir \fIcommand\fR ;"
1453 Like
1454 .B \-execdir
1455 but ask the user first in the same way as for
1456 .BR \-ok .
1457 If the user does not agree, just return false.
1458 If the command is run, its standard input is redirected from
1459 .IR /dev/null .
1460 This action may not be specified together with the
1461 .B \-files0\-from
1462 option.
1463
1464
1465 .IP \-print
1466 True; print the full file name on the standard output, followed by a
1467 newline.
1468 If you are piping the output of
1469 .B find
1470 into another program and there is the faintest possibility that the files
1471 which you are searching for might contain a newline, then you should
1472 seriously consider using the
1473 .B \-print0
1474 option instead of
1475 .BR \-print .
1476 See the
1477 .B UNUSUAL FILENAMES
1478 section for information about how unusual characters in filenames are handled.
1479
1480 .IP \-print0
1481 True; print the full file name on the standard output, followed by a
1482 null character (instead of the newline character that
1483 .B \-print
1484 uses).
1485 This allows file names that contain newlines or other types of white
1486 space to be correctly interpreted by programs that process the
1487 \fBfind\fR output. This option corresponds to the
1488 .B \-0
1489 option of
1490 .BR xargs .
1491
1492 .IP "\-printf \fIformat\fR"
1493 True; print \fIformat\fR on the standard output, interpreting `\e'
1494 escapes and `%' directives. Field widths and precisions can be
1495 specified as with the
1496 .BR printf (3)
1497 C function. Please note that many of
1498 the fields are printed as %s rather than %d, and this may mean that
1499 flags don't work as you might expect. This also means that the `\-'
1500 flag does work (it forces fields to be left-aligned). Unlike
1501 .BR \-print ,
1502 .B \-printf
1503 does not add a newline at the end of the string. The escapes
1504 and directives are:
1505 .RS
1506 .IP \ea
1507 Alarm bell.
1508 .IP \eb
1509 Backspace.
1510 .IP \ec
1511 Stop printing from this format immediately and flush the output.
1512 .IP \ef
1513 Form feed.
1514 .IP \en
1515 Newline.
1516 .IP \er
1517 Carriage return.
1518 .IP \et
1519 Horizontal tab.
1520 .IP \ev
1521 Vertical tab.
1522 .IP \e0
1523 ASCII NUL.
1524 .IP \e\e
1525 A literal backslash (`\e').
1526 .IP \eNNN
1527 The character whose ASCII code is NNN (octal).
1528 .PP
1529 A `\e' character followed by any other character is treated as an
1530 ordinary character, so they both are printed.
1531 .IP %%
1532 A literal percent sign.
1533 .IP %a
1534 File's last access time in the format returned by the C
1535 .BR ctime (3)
1536 function.
1537 .IP %A\fIk\fP
1538 File's last access time in the format specified by
1539 .IR k ,
1540 which is either `@' or a directive for the C
1541 .BR strftime (3)
1542 function.
1543 The following shows an incomplete list of possible values for \fIk\fR.
1544 Please refer to the documentation of
1545 .BR strftime (3)
1546 for the full list.
1547 Some of the conversion specification characters might not be available on all systems,
1548 due to differences in the implementation of the
1549 .BR strftime (3)
1550 library function.
1551 .RS
1552 .IP @
1553 seconds since Jan.\& 1, 1970, 00:00 GMT, with fractional part.
1554 .PP
1555 Time fields:
1556 .IP H
1557 hour (00..23)
1558 .IP I
1559 hour (01..12)
1560 .IP k
1561 hour ( 0..23)
1562 .IP l
1563 hour ( 1..12)
1564 .IP M
1565 minute (00..59)
1566 .IP p
1567 locale's AM or PM
1568 .IP r
1569 time, 12-hour (hh:mm:ss [AP]M)
1570 .IP S
1571 Second (00.00 \&..\& 61.00). There is a fractional part.
1572 .IP T
1573 time, 24-hour (hh:mm:ss.xxxxxxxxxx)
1574 .IP +
1575 Date and time, separated by `+', for example
1576 `2004\-04\-28+22:22:05.0'. This is a GNU extension. The time is
1577 given in the current timezone (which may be affected by setting the
1578 .B TZ
1579 environment variable). The seconds field includes a fractional part.
1580 .IP X
1581 locale's time representation (H:M:S). The seconds field includes a
1582 fractional part.
1583 .IP Z
1584 time zone (e.g., EDT), or nothing if no time zone is determinable
1585 .PP
1586 Date fields:
1587 .IP a
1588 locale's abbreviated weekday name (Sun..Sat)
1589 .IP A
1590 locale's full weekday name, variable length (Sunday..Saturday)
1591 .IP b
1592 locale's abbreviated month name (Jan..Dec)
1593 .IP B
1594 locale's full month name, variable length (January..December)
1595 .IP c
1596 locale's date and time (Sat Nov 04 12:02:33 EST 1989). The format is
1597 the same as for
1598 .BR ctime (3)
1599 and so to preserve compatibility with that format, there is no fractional part
1600 in the seconds field.
1601 .IP d
1602 day of month (01..31)
1603 .IP D
1604 date (mm/dd/yy)
1605 .IP F
1606 date (yyyy-mm-dd)
1607 .IP h
1608 same as b
1609 .IP j
1610 day of year (001..366)
1611 .IP m
1612 month (01..12)
1613 .IP U
1614 week number of year with Sunday as first day of week (00..53)
1615 .IP w
1616 day of week (0..6)
1617 .IP W
1618 week number of year with Monday as first day of week (00..53)
1619 .IP x
1620 locale's date representation (mm/dd/yy)
1621 .IP y
1622 last two digits of year (00..99)
1623 .IP Y
1624 year (1970...\&)
1625 .RE
1626 .IP %b
1627 The amount of disk space used for this file in 512-byte blocks. Since disk
1628 space is allocated in multiples of the filesystem block size this is usually
1629 greater than %s/512, but it can also be smaller if the file is a sparse file.
1630
1631 .IP %B\fIk\fP
1632 File's birth time, i.e., its creation time, in the format specified by
1633 .IR k ,
1634 which is the same as for %A.
1635 This directive produces an empty string if the underlying operating system or
1636 filesystem does not support birth times.
1637
1638 .IP %c
1639 File's last status change time in the format returned by the C
1640 .BR ctime (3)
1641 function.
1642 .IP %C\fIk\fP
1643 File's last status change time in the format specified by
1644 .IR k ,
1645 which is the same as for %A.
1646 .IP %d
1647 File's depth in the directory tree; 0 means the file is a starting-point.
1648 .IP %D
1649 The device number on which the file exists (the st_dev field of struct
1650 stat), in decimal.
1651 .IP %f
1652 Print the basename; the file's name with any leading directories
1653 removed (only the last element). For
1654 .BR / ,
1655 the result is `/'.
1656 See the
1657 .B EXAMPLES
1658 section for an example.
1659
1660 .IP %F
1661 Type of the filesystem the file is on; this value can be used for
1662 \-fstype.
1663 .IP %g
1664 File's group name, or numeric group ID if the group has no name.
1665 .IP %G
1666 File's numeric group ID.
1667 .IP %h
1668 Dirname; the Leading directories of the file's name (all but the last
1669 element). If the file name contains no slashes (since it is in the
1670 current directory) the %h specifier expands to `.'. For files which
1671 are themselves directories and contain a slash (including
1672 .BR / ),
1673 %h expands to the empty string. See the
1674 .B EXAMPLES
1675 section for an example.
1676 .IP %H
1677 Starting-point under which file was found.
1678 .IP %i
1679 File's inode number (in decimal).
1680 .IP %k
1681 The amount of disk space used for this file in 1\ KB blocks.
1682 Since disk space is allocated in multiples of the filesystem block
1683 size this is usually greater than %s/1024,
1684 but it can also be smaller if the file is a sparse file.
1685 .IP %l
1686 Object of symbolic link (empty string if file is not a symbolic link).
1687 .IP %m
1688 File's permission bits (in octal). This option uses the `traditional'
1689 numbers which most Unix implementations use, but if your particular
1690 implementation uses an unusual ordering of octal permissions bits, you
1691 will see a difference between the actual value of the file's mode and
1692 the output of %m.
1693 Normally you will want to have a leading zero on this number,
1694 and to do this, you should use the
1695 .B #
1696 flag (as in, for example, `%#m').
1697 .IP %M
1698 File's permissions (in symbolic form, as for
1699 .BR ls ).
1700 This directive is supported in findutils 4.2.5 and later.
1701 .IP %n
1702 Number of hard links to file.
1703 .IP %p
1704 File's name.
1705 .IP %P
1706 File's name with the name of the starting-point under which
1707 it was found removed.
1708 .IP %s
1709 File's size in bytes.
1710 .IP %S
1711 File's sparseness. This is calculated as (BLOCKSIZE*st_blocks /
1712 st_size). The exact value you will get for an ordinary file of a
1713 certain length is system-dependent. However, normally sparse files
1714 will have values less than 1.0, and files which use indirect blocks
1715 may have a value which is greater than 1.0. In general the number of
1716 blocks used by a file is file system dependent.
1717 The value used for BLOCKSIZE is system-dependent, but is usually 512
1718 bytes.
1719 If the file size is zero, the value printed is undefined.
1720 On systems which lack support for st_blocks,
1721 a file's sparseness is assumed to be 1.0.
1722 .IP %t
1723 File's last modification time in the format returned by the C
1724 .BR ctime (3)
1725 function.
1726 .IP %T\fIk\fP
1727 File's last modification time in the format specified by
1728 .IR k ,
1729 which is the same as for %A.
1730 .IP %u
1731 File's user name, or numeric user ID if the user has no name.
1732 .IP %U
1733 File's numeric user ID.
1734 .IP %y
1735 File's type (like in
1736 .BR "ls \-l" ),
1737 U=unknown type (shouldn't happen)
1738 .IP %Y
1739 File's type (like %y), plus follow symbolic links: `L'=loop, `N'=nonexistent,
1740 `?' for any other error when determining the type of the target of a symbolic
1741 link.
1742 .IP %Z
1743 (SELinux only) file's security context.
1744 .IP "%{ %[ %("
1745 Reserved for future use.
1746 .PP
1747 A `%' character followed by any other character is discarded, but the
1748 other character is printed (don't rely on this, as further format
1749 characters may be introduced). A `%' at the end of the format
1750 argument causes undefined behaviour since there is no following
1751 character. In some locales, it may hide your door keys, while in
1752 others it may remove the final page from the novel you are reading.
1753
1754 The %m and %d directives support the
1755 .BR # ,
1756 .B 0
1757 and
1758 .B +
1759 flags, but the other directives do not, even if they
1760 print numbers. Numeric directives that do not support these flags
1761 include
1762 .BR G ,
1763 .BR U ,
1764 .BR b ,
1765 .BR D ,
1766 .B k
1767 and
1768 .BR n .
1769 The `\-' format flag is supported and changes the alignment of a field
1770 from right-justified (which is the default) to left-justified.
1771 .PP
1772 See the
1773 .B UNUSUAL FILENAMES
1774 section for information about how unusual characters in filenames are handled.
1775
1776
1777 .RE
1778 .IP \-prune
1779 True; if the file is a directory, do not descend into it. If
1780 .B \-depth
1781 is given, then
1782 .B \-prune
1783 has no effect. Because
1784 .B \-delete
1785 implies
1786 .BR \-depth ,
1787 you cannot usefully use
1788 .B \-prune
1789 and
1790 .B \-delete
1791 together.
1792 For example, to skip the directory
1793 .I src/emacs
1794 and all files and directories under it, and print the names of the other files
1795 found, do something like this:
1796 .in +4m
1797 .nf
1798 find . \-path ./src/emacs \-prune \-o \-print
1799 .fi
1800 .in
1801
1802
1803 .IP "\-quit"
1804 Exit immediately (with return value zero if no errors have occurred).
1805 This is different to
1806 .B \-prune
1807 because
1808 .B \-prune
1809 only applies to the contents of pruned directories, while
1810 .B \-quit
1811 simply makes
1812 .B find
1813 stop immediately. No child processes will be left
1814 running. Any command lines which have been built by
1815 .B \-exec\ ...\ +
1816 or
1817 .B \-execdir\ ...\ +
1818 are invoked before the program is
1819 exited. After
1820 .B \-quit
1821 is executed, no more files specified on the command line will be
1822 processed. For example,
1823 .RB ` "find\ \fI/tmp/foo\fP\ \fI/tmp/bar\fP\ \-print\ \-quit" `
1824 will print only `/tmp/foo`.
1825 .br
1826 One common use of
1827 .B \-quit
1828 is to stop searching the file system once we have
1829 found what we want. For example, if we want to find just a single
1830 file we can do this:
1831 .in +4m
1832 .nf
1833 find / -name needle -print -quit
1834 .fi
1835 .in
1836
1837 .SS OPERATORS
1838 Listed in order of decreasing precedence:
1839
1840 .IP "( \fIexpr\fR )"
1841 Force precedence. Since parentheses are special to the shell, you
1842 will normally need to quote them. Many of the examples in this manual
1843 page use backslashes for this purpose: `\e(...\e)' instead of `(...)'.
1844
1845 .IP "! \fIexpr\fR"
1846 True if \fIexpr\fR is false. This character will also usually need
1847 protection from interpretation by the shell.
1848
1849 .IP "\-not \fIexpr\fR"
1850 Same as !\&
1851 .IR expr ,
1852 but not POSIX compliant.
1853
1854 .IP "\fIexpr1 expr2\fR"
1855 Two expressions in a row are taken to be joined with an
1856 implied
1857 .BR \-a ;
1858 \fIexpr2\fR is not evaluated if \fIexpr1\fR is false.
1859
1860 .IP "\fIexpr1\fR \-a \fIexpr2\fR"
1861 Same as
1862 .IR "expr1 expr2" .
1863
1864 .IP "\fIexpr1\fR \-and \fIexpr2\fR"
1865 Same as
1866 .IR "expr1 expr2" ,
1867 but not POSIX compliant.
1868
1869 .IP "\fIexpr1\fR \-o \fIexpr2\fR"
1870 Or; \fIexpr2\fR is not evaluated if \fIexpr1\fR is true.
1871
1872 .IP "\fIexpr1\fR \-or \fIexpr2\fR"
1873 Same as \fIexpr1\fR
1874 .B \-o
1875 .IR expr2 ,
1876 but not POSIX compliant.
1877
1878 .IP "\fIexpr1\fR , \fIexpr2\fR"
1879 List; both \fIexpr1\fR and \fIexpr2\fR are always evaluated. The
1880 value of \fIexpr1\fR is discarded; the value of the list is the value
1881 of
1882 .IR expr2 .
1883 The comma operator can be useful for searching for
1884 several different types of thing, but traversing the filesystem
1885 hierarchy only once. The
1886 .B \-fprintf
1887 action can be used to list the various matched items into several
1888 different output files.
1889 .P
1890 Please note that
1891 .B \-a
1892 when specified implicitly (for example by two tests appearing without
1893 an explicit operator between them) or explicitly has higher precedence
1894 than
1895 .BR \-o .
1896 This means that
1897 .B find . \-name afile \-o \-name bfile \-print
1898 will never print
1899 .IR afile .
1900 .
1901 .SH UNUSUAL FILENAMES
1902 Many of the actions of
1903 .B find
1904 result in the printing of data which is under the control of other
1905 users. This includes file names, sizes, modification times and so
1906 forth. File names are a potential problem since they can contain any
1907 character except `\e0' and `/'. Unusual characters in file names can
1908 do unexpected and often undesirable things to your terminal (for
1909 example, changing the settings of your function keys on some
1910 terminals). Unusual characters are handled differently by various
1911 actions, as described below.
1912
1913 .IP "\-print0, \-fprint0"
1914 Always print the exact filename, unchanged, even if the output is
1915 going to a terminal.
1916
1917 .IP "\-ls, \-fls"
1918 Unusual characters are always escaped. White space, backslash, and
1919 double quote characters are printed using C-style escaping (for
1920 example `\ef', `\e\(dq'). Other unusual characters are printed using an
1921 octal escape. Other printable characters (for
1922 .B \-ls
1923 and
1924 .B \-fls
1925 these are the characters between octal 041 and 0176) are printed as-is.
1926
1927 .IP "\-printf, \-fprintf"
1928 If the output is not going to a terminal, it is printed as-is.
1929 Otherwise, the result depends on which directive is in use. The
1930 directives %D, %F, %g, %G, %H, %Y, and %y expand to values which are
1931 not under control of files' owners, and so are printed as-is. The
1932 directives %a, %b, %c, %d, %i, %k, %m, %M, %n, %s, %t, %u and %U have
1933 values which are under the control of files' owners but which cannot
1934 be used to send arbitrary data to the terminal, and so these are
1935 printed as-is. The directives %f, %h, %l, %p and %P are quoted. This
1936 quoting is performed in the same way as for GNU
1937 .BR ls .
1938 This is not the same quoting mechanism as the one used for
1939 .B \-ls
1940 and
1941 .BR \-fls .
1942 If you are able to decide what format to use for the output of
1943 .B find
1944 then it is normally better to use `\e0' as a terminator
1945 than to use newline, as file names can contain white space and newline
1946 characters. The setting of the
1947 .B LC_CTYPE
1948 environment variable is used to determine which characters need to be quoted.
1949
1950 .IP "\-print, \-fprint"
1951 Quoting is handled in the same way as for
1952 .B \-printf
1953 and
1954 .BR \-fprintf .
1955 If you are using
1956 .B find
1957 in a script or in a situation where the matched files might have
1958 arbitrary names, you should consider using
1959 .B \-print0
1960 instead of
1961 .BR \-print .
1962 .P
1963 The
1964 .B \-ok
1965 and
1966 .B \-okdir
1967 actions print the current filename as-is. This may change in a future release.
1968 .
1969 .SH "STANDARDS CONFORMANCE"
1970 For closest compliance to the POSIX standard, you should set the
1971 .B POSIXLY_CORRECT
1972 environment variable.
1973 The following options are specified in the POSIX standard
1974 (IEEE Std 1003.1-2008, 2016 Edition):
1975
1976 .IP \fB\-H\fR
1977 This option is supported.
1978
1979 .IP \fB\-L\fR
1980 This option is supported.
1981
1982 .IP \fB\-name\fR
1983 This option is supported, but POSIX conformance depends on the
1984 POSIX conformance of the system's
1985 .BR fnmatch (3)
1986 library function. As of findutils-4.2.2, shell metacharacters
1987 (`*', `?' or `[]' for example) match a leading `.', because
1988 IEEE PASC interpretation 126 requires this.
1989 This is a change from previous versions of findutils.
1990
1991 .IP \fB\-type\fR
1992 Supported.
1993 POSIX specifies `b', `c', `d', `l', `p', `f' and `s'.
1994 GNU find also supports `D', representing a Door, where the OS provides these.
1995 Furthermore, GNU find allows multiple types to be specified at once in a
1996 comma-separated list.
1997
1998 .IP \fB\-ok\fR
1999 Supported.
2000 Interpretation of the response is according to the `yes' and `no'
2001 patterns selected by setting the
2002 .B LC_MESSAGES
2003 environment variable.
2004 When the
2005 .B POSIXLY_CORRECT
2006 environment variable is set, these patterns are taken system's definition
2007 of a positive (yes) or negative (no) response.
2008 See the system's documentation for
2009 .BR nl_langinfo (3),
2010 in particular YESEXPR and NOEXPR.
2011 When
2012 .B POSIXLY_CORRECT
2013 is not set, the patterns are instead taken from
2014 .BR find 's
2015 own message catalogue.
2016
2017 .IP \fB\-newer\fR
2018 Supported. If the file specified is a symbolic link, it is always
2019 dereferenced. This is a change from previous behaviour, which used to
2020 take the relevant time from the symbolic link; see the HISTORY section
2021 below.
2022
2023 .IP \fB\-perm\fR
2024 Supported. If the
2025 .B POSIXLY_CORRECT
2026 environment variable is not set,
2027 some mode arguments (for example +a+x) which are not valid in POSIX
2028 are supported for backward-compatibility.
2029
2030 .IP "Other primaries"
2031 The primaries
2032 .BR \-atime ,
2033 .BR \-ctime ,
2034 .BR \-depth ,
2035 .BR \-exec ,
2036 .BR \-group ,
2037 .BR \-links ,
2038 .BR \-mtime ,
2039 .BR \-nogroup ,
2040 .BR \-nouser ,
2041 .BR \-ok ,
2042 .BR \-path ,
2043 .BR \-print ,
2044 .BR \-prune ,
2045 .BR \-size ,
2046 .B \-user
2047 and
2048 .B \-xdev
2049 are all supported.
2050
2051 .P
2052 The POSIX standard specifies parentheses `(', `)', negation `!' and the
2053 logical AND/OR operators
2054 .B \-a
2055 and
2056 .BR \-o .
2057 .P
2058 All other options, predicates, expressions and so forth are extensions
2059 beyond the POSIX standard. Many of these extensions are not unique to
2060 GNU find, however.
2061 .P
2062 The POSIX standard requires that
2063 .B find
2064 detects loops:
2065 .IP
2066 The
2067 .B find
2068 utility shall detect infinite loops; that is, entering a
2069 previously visited directory that is an ancestor of the last file
2070 encountered.
2071 When it detects an infinite loop,
2072 .B find
2073 shall write a diagnostic message to standard error and shall either recover its
2074 position in the hierarchy or terminate.
2075 .P
2076 GNU
2077 .B find
2078 complies with these requirements. The link count of
2079 directories which contain entries which are hard links to an ancestor
2080 will often be lower than they otherwise should be. This can mean that
2081 GNU find will sometimes optimize away the visiting of a subdirectory
2082 which is actually a link to an ancestor. Since
2083 .B find
2084 does not actually enter such a subdirectory, it is allowed to avoid
2085 emitting a diagnostic message. Although this behaviour may be
2086 somewhat confusing, it is unlikely that anybody actually depends on
2087 this behaviour. If the leaf optimisation has been turned off with
2088 .BR \-noleaf ,
2089 the directory entry will always be examined and the diagnostic message
2090 will be issued where it is appropriate. Symbolic links cannot be used
2091 to create filesystem cycles as such, but if the
2092 .B \-L
2093 option or the
2094 .B \-follow
2095 option is in use, a diagnostic message is issued when
2096 .B find
2097 encounters a loop of symbolic links. As with loops containing hard
2098 links, the leaf optimisation will often mean that
2099 .B find
2100 knows that it doesn't need to call
2101 .I stat()
2102 or
2103 .I chdir()
2104 on the symbolic link, so this diagnostic is frequently not necessary.
2105 .P
2106 The
2107 .B \-d
2108 option is supported for compatibility with various BSD systems,
2109 but you should use the POSIX-compliant option
2110 .B \-depth
2111 instead.
2112 .P
2113 The
2114 .B POSIXLY_CORRECT
2115 environment variable does not affect the behaviour of the
2116 .B \-regex
2117 or
2118 .B \-iregex
2119 tests because those tests aren't specified in the POSIX standard.
2120 .
2121 .SH "ENVIRONMENT VARIABLES"
2122
2123 .IP LANG
2124 Provides a default value for the internationalization variables that
2125 are unset or null.
2126
2127 .IP LC_ALL
2128 If set to a non-empty string value, override the values of all the
2129 other internationalization variables.
2130
2131 .IP LC_COLLATE
2132 The POSIX standard specifies that this variable affects the pattern
2133 matching to be used for the
2134 .B \-name
2135 option.
2136 GNU find uses the
2137 .BR fnmatch (3)
2138 library function, and so support for
2139 .B LC_COLLATE
2140 depends on the system library.
2141 This variable also affects the interpretation of the response to
2142 .BR \-ok ;
2143 while the
2144 .B LC_MESSAGES
2145 variable selects the actual pattern used to interpret the response to
2146 .BR \-ok ,
2147 the interpretation of any bracket expressions in the pattern will be
2148 affected by
2149 .BR LC_COLLATE .
2150
2151 .IP LC_CTYPE
2152 This variable affects the treatment of character classes used in
2153 regular expressions and also with
2154 the
2155 .B \-name
2156 test, if the system's
2157 .BR fnmatch (3)
2158 library function supports this. This variable also affects the
2159 interpretation of any character classes in the regular expressions
2160 used to interpret the response to the prompt issued by
2161 .BR \-ok .
2162 The
2163 .B LC_CTYPE
2164 environment variable will also affect which characters are considered
2165 to be unprintable when filenames are printed;
2166 see the section UNUSUAL FILENAMES.
2167
2168 .IP LC_MESSAGES
2169 Determines the locale to be used for internationalised messages. If the
2170 .B POSIXLY_CORRECT
2171 environment variable is set, this also determines the interpretation of
2172 the response to the prompt made by the
2173 .B \-ok
2174 action.
2175
2176 .IP NLSPATH
2177 Determines the location of the internationalisation message catalogues.
2178
2179 .IP PATH
2180 Affects the directories which are searched to find the executables
2181 invoked by
2182 .BR \-exec ,
2183 .BR \-execdir ,
2184 .B \-ok
2185 and
2186 .BR \-okdir .
2187
2188 .IP POSIXLY_CORRECT
2189 Determines the block size used by
2190 .B \-ls
2191 and
2192 .BR \-fls .
2193 If
2194 .B POSIXLY_CORRECT
2195 is set, blocks are units of 512 bytes. Otherwise they are units of 1024 bytes.
2196 .IP
2197 Setting this variable also turns off
2198 warning messages (that is, implies
2199 .BR \-nowarn )
2200 by default, because POSIX requires that apart from
2201 the output for
2202 .BR \-ok ,
2203 all messages printed on stderr are diagnostics and must result in a
2204 non-zero exit status.
2205 .IP
2206 When
2207 .B POSIXLY_CORRECT
2208 is not set,
2209 .B "\-perm \fI+zzz\fR"
2210 is treated just like
2211 .B "\-perm \fI/zzz\fR"
2212 if
2213 \fI+zzz\fR is not a valid symbolic mode. When
2214 .B POSIXLY_CORRECT
2215 is set, such
2216 constructs are treated as an error.
2217 .IP
2218 When
2219 .B POSIXLY_CORRECT
2220 is set, the response to the prompt made by the
2221 .B \-ok
2222 action is interpreted according to the system's message catalogue, as
2223 opposed to according to
2224 .BR find 's
2225 own message translations.
2226
2227 .IP TZ
2228 Affects the time zone used for some of the time-related format
2229 directives of
2230 .B \-printf
2231 and
2232 .BR \-fprintf .
2233 .
2234 .SH "EXAMPLES"
2235 .\" A bulleted \[bu] list of examples.
2236 .SS Simple `find|xargs` approach
2237 .IP \[bu]
2238 Find files named
2239 .I core
2240 in or below the directory
2241 .I /tmp
2242 and delete them.
2243 .nf
2244 \&
2245 .in +4m
2246 .B $ find /tmp \-name core \-type f \-print | xargs /bin/rm \-f
2247 .in
2248 \&
2249 .fi
2250 Note that this will work incorrectly if there are
2251 any filenames containing newlines, single or double quotes, or spaces.
2252 .
2253 .SS Safer `find -print0 | xargs -0` approach
2254 .IP \[bu]
2255 Find files named \fIcore\fP in or below the directory \fI/tmp\fP
2256 and delete them, processing filenames in such a way that file or
2257 directory names containing single or double quotes, spaces or newlines
2258 are correctly handled.
2259 .nf
2260 \&
2261 .in +4m
2262 .B $ find /tmp \-name core \-type f \-print0 | xargs \-0 /bin/rm \-f
2263 .in
2264 \&
2265 .fi
2266 The
2267 .B \-name
2268 test comes before the
2269 .B \-type
2270 test in order to avoid having to call
2271 .BR stat (2)
2272 on every file.
2273 .PP
2274 Note that there is still a race between the time
2275 .B find
2276 traverses the hierarchy printing the matching filenames, and the time the
2277 process executed by
2278 .B xargs
2279 works with that file.
2280 .
2281 .SS Processing arbitrary starting points
2282 .IP \[bu]
2283 Given that another program \fIproggy\fR pre-filters and creates a huge
2284 NUL-separated list of files, process those as starting points, and find
2285 all regular, empty files among them:
2286 .nf
2287 \&
2288 .in +4m
2289 .B $ proggy | find \-files0\-from \- \-maxdepth 0 \-type f \-empty
2290 .in
2291 \&
2292 .fi
2293 The use of
2294 .B `\-files0\-from\ \-`
2295 means to read the names of the starting points from \fIstandard input\fR,
2296 i.e., from the pipe; and
2297 .B \-maxdepth\ 0
2298 ensures that only explicitly those entries are examined without recursing
2299 into directories (in the case one of the starting points is one).
2300 .
2301 .SS
2302 Executing a command for each file
2303 .IP \[bu]
2304 Run
2305 .I file
2306 on every file in or below the current directory.
2307 .nf
2308 \&
2309 .in +4m
2310 .B $ find . \-type f \-exec file \(aq{}\(aq \e;
2311 .in
2312 \&
2313 .fi
2314 Notice that the braces are enclosed in single quote marks to protect them
2315 from interpretation as shell script punctuation. The semicolon is
2316 similarly protected by the use of a backslash, though single quotes
2317 could have been used in that case also.
2318 .PP
2319 In many cases, one might prefer the
2320 .B `\-exec\ \&...\&\ +`
2321 or better the
2322 .B `\-execdir\ \&...\&\ +`
2323 syntax for performance and security reasons.
2324 .
2325 .SS Traversing the filesystem just once - for 2 different actions
2326 .IP \[bu]
2327 Traverse the filesystem just once, listing set-user-ID files and
2328 directories into
2329 .I /root/suid.txt
2330 and large files into
2331 .IR /root/big.txt .
2332 .nf
2333 \&
2334 .in +4m
2335 .B $ find / \e
2336 .in +4m
2337 .B \e( \-perm \-4000 \-fprintf /root/suid.txt \(aq%#m %u %p\en\(aq \e) , \e
2338 .br
2339 .B \e( \-size +100M \-fprintf /root/big.txt \(aq%\-10s %p\en\(aq \e)
2340 .in -4m
2341 .in -4m
2342 \&
2343 .fi
2344 This example uses the line-continuation character \(aq\e\(aq on the first two
2345 lines to instruct the shell to continue reading the command on the next line.
2346 .
2347 .SS
2348 Searching files by age
2349 .IP \[bu]
2350 Search for files in your home directory which have been modified in
2351 the last twenty-four hours.
2352 .nf
2353 \&
2354 .in +4m
2355 .B $ find $HOME \-mtime 0
2356 .in
2357 \&
2358 .fi
2359 This command works this way because the
2360 time since each file was last modified is divided by 24 hours and any
2361 remainder is discarded. That means that to match
2362 .B \-mtime
2363 .BR 0 ,
2364 a file will have to have a modification in the past which is less than
2365 24 hours ago.
2366 .
2367 .SS
2368 Searching files by permissions
2369 .IP \[bu]
2370 Search for files which are executable but not readable.
2371 .nf
2372 \&
2373 .in +4m
2374 .B $ find /sbin /usr/sbin \-executable \e! \-readable \-print
2375 .in
2376 \&
2377 .fi
2378 .
2379 .IP \[bu]
2380 Search for files which have read and write permission for their owner,
2381 and group, but which other users can read but not write to.
2382 .nf
2383 \&
2384 .in +4m
2385 .B $ find . \-perm 664
2386 .in
2387 \&
2388 .fi
2389 Files which meet these criteria but have other permissions bits set
2390 (for example if someone can execute the file) will not be matched.
2391 .
2392 .IP \[bu]
2393 Search for files which have read and write permission for their owner
2394 and group, and which other users can read, without regard to the
2395 presence of any extra permission bits (for example the executable
2396 bit).
2397 .nf
2398 \&
2399 .in +4m
2400 .B $ find . \-perm \-664
2401 .in
2402 \&
2403 .fi
2404 This will match a file which has mode
2405 .IR 0777 ,
2406 for example.
2407 .
2408 .IP \[bu]
2409 Search for files which are writable by somebody (their owner, or
2410 their group, or anybody else).
2411 .nf
2412 \&
2413 .in +4m
2414 .B $ find . \-perm /222
2415 .in
2416 \&
2417 .fi
2418 .
2419 .IP \[bu]
2420 Search for files which are writable by either their owner or their group.
2421 .nf
2422 \&
2423 .in +4m
2424 .B $ find . \-perm /220
2425 .B $ find . \-perm /u+w,g+w
2426 .B $ find . \-perm /u=w,g=w
2427 .in
2428 \&
2429 .fi
2430 All three of these commands do the same thing, but the first one uses
2431 the octal representation of the file mode, and the other two use the
2432 symbolic form.
2433 The files don't have to be writable by both the owner and group to be matched;
2434 either will do.
2435 .
2436 .IP \[bu]
2437 Search for files which are writable by both their owner and their group.
2438 .nf
2439 \&
2440 .in +4m
2441 .B $ find . \-perm \-220
2442 .B $ find . \-perm \-g+w,u+w
2443 .in
2444 \&
2445 .fi
2446 Both these commands do the same thing.
2447 .
2448 .IP \[bu]
2449 A more elaborate search on permissions.
2450 .nf
2451 \&
2452 .in +4m
2453 .B $ find . \-perm \-444 \-perm /222 \e! \-perm /111
2454 .B $ find . \-perm \-a+r \-perm /a+w \e! \-perm /a+x
2455 .in
2456 \&
2457 .fi
2458 These two commands both search for files that are readable for everybody
2459 .RB ( "\-perm \-444"
2460 or
2461 .BR "\-perm \-a+r" ),
2462 have at least one write bit
2463 set
2464 .RB ( "\-perm /222"
2465 or
2466 .BR "\-perm /a+w" )
2467 but are not executable for anybody
2468 .RB ( "! \-perm /111"
2469 or
2470 .B ! \-perm /a+x
2471 respectively).
2472 .
2473 .SS
2474 Pruning - omitting files and subdirectories
2475 .IP \[bu]
2476 Copy the contents of
2477 .I /source-dir
2478 to
2479 .IR /dest-dir ,
2480 but omit files and directories named
2481 .I .snapshot
2482 (and anything in them). It also omits files or directories whose name ends in
2483 `\(ti', but not their contents.
2484 .nf
2485 \&
2486 .in +4m
2487 .B $ cd /source-dir
2488 .B $ find . \-name .snapshot \-prune \-o \e( \e! \-name \(aq*~\(aq \-print0 \e) \e
2489 .br
2490 .in +4m
2491 .B | cpio \-pmd0 /dest-dir
2492 .in -4m
2493 .in -4m
2494 \&
2495 .fi
2496 The construct
2497 .B \-prune\ \-o\ \e(\ \&...\&\ \-print0\ \e)
2498 is quite common. The idea here is that the expression before
2499 .B \-prune
2500 matches things which are to be pruned. However, the
2501 .B \-prune
2502 action itself returns true, so the following
2503 .B \-o
2504 ensures that the right hand side is evaluated only for those
2505 directories which didn't get pruned (the contents of the pruned
2506 directories are not even visited, so their contents are irrelevant).
2507 The expression on the right hand side of the
2508 .B \-o
2509 is in parentheses only for clarity. It emphasises that the
2510 .B \-print0
2511 action takes place only for things that didn't have
2512 .B \-prune
2513 applied to them. Because the default `and' condition between tests
2514 binds more tightly than
2515 .BR \-o ,
2516 this is the default anyway, but the parentheses help to show
2517 what is going on.
2518 .
2519 .IP \[bu]
2520 Given the following directory of projects and their associated SCM
2521 administrative directories, perform an efficient search for the
2522 projects' roots:
2523 .nf
2524 \&
2525 .in +4m
2526 .B $ find repo/ \e
2527 .in +4m
2528 .B \e( \-exec test \-d \(aq{}/.svn\(aq \e; \e
2529 .B \-or \-exec test \-d \(aq{}/.git\(aq \e; \e
2530 .B \-or \-exec test \-d \(aq{}/CVS\(aq \e; \e
2531 .B \e) \-print \-prune
2532 .in -4m
2533 .in -4m
2534 \&
2535 .fi
2536 Sample output:
2537 .nf
2538 \&
2539 .in +4m
2540 .B repo/project1/CVS
2541 .B repo/gnu/project2/.svn
2542 .B repo/gnu/project3/.svn
2543 .B repo/gnu/project3/src/.svn
2544 .B repo/project4/.git
2545 .in
2546 \&
2547 .fi
2548 In this example,
2549 .B \-prune
2550 prevents unnecessary descent into directories that have already been
2551 discovered (for example we do not search
2552 .I project3/src
2553 because we already found
2554 .IR project3/.svn ),
2555 but ensures sibling directories
2556 .RI ( project2
2557 and
2558 .IR project3 )
2559 are found.
2560 .
2561 .SS
2562 Other useful examples
2563 .IP \[bu]
2564 Search for several file types.
2565 .nf
2566 \&
2567 .in +4m
2568 .B $ find /tmp \-type f,d,l
2569 .in
2570 \&
2571 .fi
2572 Search for files, directories, and symbolic links in the directory
2573 .I /tmp
2574 passing these types as a comma-separated list (GNU extension),
2575 which is otherwise equivalent to the longer, yet more portable:
2576 .nf
2577 \&
2578 .in +4m
2579 .B $ find /tmp \e( \-type f \-o \-type d \-o \-type l \e)
2580 .in
2581 \&
2582 .fi
2583 .
2584 .IP \[bu]
2585 Search for files with the particular name
2586 .I needle
2587 and stop immediately when we find the first one.
2588 .nf
2589 \&
2590 .in +4m
2591 .B $ find / -name needle -print -quit
2592 .in
2593 \&
2594 .fi
2595 .
2596 .IP \[bu]
2597 Demonstrate the interpretation of the
2598 .B %f
2599 and
2600 .B %h
2601 format directives of the
2602 .B \-printf
2603 action for some corner-cases.
2604 Here is an example including some output.
2605 .nf
2606 \&
2607 .in +4m
2608 .B $ find . .. / /tmp /tmp/TRACE compile compile/64/tests/find -maxdepth 0 -printf '[%h][%f]\en'
2609 .B [.][.]
2610 .B [.][..]
2611 .B [][/]
2612 .B [][tmp]
2613 .B [/tmp][TRACE]
2614 .B [.][compile]
2615 .B [compile/64/tests][find]
2616 .in
2617 \&
2618 .fi
2619 .
2620 .SH EXIT STATUS
2621 .B find
2622 exits with status 0 if all files are processed successfully, greater
2623 than 0 if errors occur.
2624 This is deliberately a very broad description,
2625 but if the return value is non-zero,
2626 you should not rely on the correctness of the results of
2627 .BR find .
2628
2629 When some error occurs,
2630 .B find
2631 may stop immediately, without completing all the actions specified.
2632 For example, some starting points may not have been examined or some
2633 pending program invocations for
2634 .B \-exec\ \&...\&\ {}\ +
2635 or
2636 .B "\-execdir\ \&...\&\ {}\ +
2637 may not have been performed.
2638 .
2639 .SH "HISTORY"
2640
2641 A
2642 .B find
2643 program appeared in Version 5 Unix as part of the
2644 Programmer's Workbench project and was written by Dick Haight. Doug
2645 McIlroy's
2646 .I A Research UNIX Reader: Annotated Excerpts from the Programmer’s Manual, 1971-1986
2647 provides some additional details; you can read it on-line at
2648 <https://www.cs.dartmouth.edu/~doug/reader.pdf>.
2649
2650 GNU
2651 .B find
2652 was originally written by Eric Decker, with
2653 enhancements by David MacKenzie, Jay Plett, and Tim Wood. The idea
2654 for
2655 .B find -print0
2656 and
2657 .B xargs -0
2658 came from Dan Bernstein.
2659 .
2660 .SH "COMPATIBILITY"
2661 As of findutils-4.2.2, shell metacharacters (`*', `?' or `[]' for
2662 example) used in filename patterns match a leading `.', because
2663 IEEE POSIX interpretation 126 requires this.
2664 .P
2665 As of findutils-4.3.3,
2666 .B \-perm\ /000
2667 now matches all files instead of none.
2668 .P
2669 Nanosecond-resolution
2670 timestamps were implemented in findutils-4.3.3.
2671 .P
2672 As of findutils-4.3.11, the
2673 .B \-delete
2674 action sets
2675 .BR find 's
2676 exit status to a nonzero value when it fails.
2677 However,
2678 .B find
2679 will not exit immediately. Previously,
2680 .BR find 's
2681 exit status was unaffected by the failure of
2682 .BR \-delete .
2683 .TS
2684 l l l .
2685 Feature Added in Also occurs in
2686 \-files0\-from 4.9.0
2687 \-newerXY 4.3.3 BSD
2688 \-D 4.3.1
2689 \-O 4.3.1
2690 \-readable 4.3.0
2691 \-writable 4.3.0
2692 \-executable 4.3.0
2693 \-regextype 4.2.24
2694 \-exec ... + 4.2.12 POSIX
2695 \-execdir 4.2.12 BSD
2696 \-okdir 4.2.12
2697 \-samefile 4.2.11
2698 \-H 4.2.5 POSIX
2699 \-L 4.2.5 POSIX
2700 \-P 4.2.5 BSD
2701 \-delete 4.2.3
2702 \-quit 4.2.3
2703 \-d 4.2.3 BSD
2704 \-wholename 4.2.0
2705 \-iwholename 4.2.0
2706 \-ignore_readdir_race 4.2.0
2707 \-fls 4.0
2708 \-ilname 3.8
2709 \-iname 3.8
2710 \-ipath 3.8
2711 \-iregex 3.8
2712 .TE
2713 .P
2714 The syntax
2715 \.B \-perm +MODE
2716 was removed in findutils-4.5.12, in favour of
2717 \.B \-perm
2718 .BR /MODE .
2719 The
2720 .B +MODE
2721 syntax had been deprecated since findutils-4.2.21
2722 which was released in 2005.
2723 .
2724 .SH "NON-BUGS"
2725 .SS Operator precedence surprises
2726 The command
2727 .B find . \-name afile \-o \-name bfile \-print
2728 will never print
2729 .I afile
2730 because this is actually equivalent to
2731 .BR "find . \-name afile \-o \e( \-name bfile \-a \-print \e)" .
2732 Remember that the precedence of
2733 .B \-a
2734 is higher than that of
2735 .B \-o
2736 and when there is no operator specified between tests,
2737 .B \-a
2738 is assumed.
2739 .SS \(lqpaths must precede expression\(rq error message
2740 .nf
2741 .B $ find . \-name *.c \-print
2742 find: paths must precede expression
2743 find: possible unquoted pattern after predicate `-name'?
2744 .fi
2745 .P
2746 This happens when the shell could expand the pattern
2747 .I *.c
2748 to more than one file name existing in the current directory,
2749 and passing the resulting file names in the command line to
2750 .B find
2751 like this:
2752 .nf
2753 .
2754 .B find . \-name frcode.c locate.c word_io.c \-print
2755 .
2756 .fi
2757 That command is of course not going to work, because the
2758 .B \-name
2759 predicate allows exactly only one pattern as argument. Instead of doing things
2760 this way, you should enclose the pattern in quotes or escape the wildcard, thus
2761 allowing
2762 .B find
2763 to use the pattern with the wildcard during the search for file name matching
2764 instead of file names expanded by the parent shell:
2765 .nf
2766 .B $ find . \-name \(aq*.c\(aq \-print
2767 .B $ find . \-name \e*.c \-print
2768 .fi
2769 .
2770 .SH "BUGS"
2771 There are security problems inherent in the behaviour that the POSIX
2772 standard specifies for
2773 .BR find ,
2774 which therefore cannot be fixed. For example, the
2775 .B \-exec
2776 action is
2777 inherently insecure, and
2778 .B \-execdir
2779 should be used instead.
2780 .
2781 .P
2782 The environment variable
2783 .B LC_COLLATE
2784 has no effect on the
2785 .B \-ok
2786 action.
2787 .
2788 .SH "REPORTING BUGS"
2789 GNU findutils online help: <https://www.gnu.org/software/findutils/#get-help>
2790 .br
2791 Report any translation bugs to <https://translationproject.org/team/>
2792 .PP
2793 Report any other issue via the form at the GNU Savannah bug tracker:
2794 .RS
2795 <https://savannah.gnu.org/bugs/?group=findutils>
2796 .RE
2797 General topics about the GNU findutils package are discussed at the
2798 .I bug\-findutils
2799 mailing list:
2800 .RS
2801 <https://lists.gnu.org/mailman/listinfo/bug-findutils>
2802 .RE
2803 .
2804 .SH COPYRIGHT
2805 Copyright \(co 1990\(en2024 Free Software Foundation, Inc.
2806 License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
2807 .br
2808 This is free software: you are free to change and redistribute it.
2809 There is NO WARRANTY, to the extent permitted by law.
2810 .
2811 .SH "SEE ALSO"
2812 .BR chmod (1),
2813 .BR locate (1),
2814 .BR ls (1),
2815 .BR updatedb (1),
2816 .BR xargs (1),
2817 .BR lstat (2),
2818 .BR stat (2),
2819 .BR ctime (3)
2820 .BR fnmatch (3),
2821 .BR printf (3),
2822 .BR strftime (3),
2823 .BR locatedb (5),
2824 .BR regex (7)
2825 .PP
2826 Full documentation <https://www.gnu.org/software/findutils/find>
2827 .br
2828 or available locally via:
2829 .B info find