Debian Codegraph @

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