1FIND(1) General Commands Manual FIND(1)
2
6 find - search for files in a directory hierarchy
7
9 find [-H] [-L] [-P] [-D debugopts] [-Olevel] [starting-point...] [ex‐
10 pression]
11
13 This manual page documents the GNU version of find. GNU find searches
14 the directory tree rooted at each given starting-point by evaluating
15 the given expression from left to right, according to the rules of
16 precedence (see section OPERATORS), until the outcome is known (the
17 left hand side is false for and operations, true for or), at which
18 point find moves on to the next file name. If no starting-point is
19 specified, `.' is assumed.
20 If you are using find in an environment where security is important
22 (for example if you are using it to search directories that are
23 writable by other users), you should read the `Security Considerations'
24 chapter of the findutils documentation, which is called Finding Files
25 and comes with findutils. That document also includes a lot more de‐
26 tail and discussion than this manual page, so you may find it a more
27 useful source of information.
28
30 The -H, -L and -P options control the treatment of symbolic links.
31 Command-line arguments following these are taken to be names of files
32 or directories to be examined, up to the first argument that begins
33 with `-', or the argument `(' or `!'. That argument and any following
34 arguments are taken to be the expression describing what is to be
35 searched for. If no paths are given, the current directory is used.
36 If no expression is given, the expression -print is used (but you
37 should probably consider using -print0 instead, anyway).
38 This manual page talks about `options' within the expression list.
40 These options control the behaviour of find but are specified immedi‐
41 ately after the last path name. The five `real' options -H, -L, -P, -D
42 and -O must appear before the first path name, if at all. A double
43 dash -- could theoretically be used to signal that any remaining argu‐
44 ments are not options, but this does not really work due to the way
45 find determines the end of the following path arguments: it does that
46 by reading until an expression argument comes (which also starts with a
47 `-'). Now, if a path argument would start with a `-', then find would
48 treat it as expression argument instead. Thus, to ensure that all
49 start points are taken as such, and especially to prevent that wildcard
50 patterns expanded by the calling shell are not mistakenly treated as
51 expression arguments, it is generally safer to prefix wildcards or du‐
52 bious path names with either `./' or to use absolute path names start‐
53 ing with '/'. Alternatively, it is generally safe though non-portable
54 to use the GNU option -files0-from to pass arbitrary starting points to
55 find.
56 -P Never follow symbolic links. This is the default behaviour.
59 When find examines or prints information about files, and the
60 file is a symbolic link, the information used shall be taken
61 from the properties of the symbolic link itself.
62 -L Follow symbolic links. When find examines or prints information
65 about files, the information used shall be taken from the prop‐
66 erties of the file to which the link points, not from the link
67 itself (unless it is a broken symbolic link or find is unable to
68 examine the file to which the link points). Use of this option
69 implies -noleaf. If you later use the -P option, -noleaf will
70 still be in effect. If -L is in effect and find discovers a
71 symbolic link to a subdirectory during its search, the subdirec‐
72 tory pointed to by the symbolic link will be searched.
73 When the -L option is in effect, the -type predicate will always
75 match against the type of the file that a symbolic link points
76 to rather than the link itself (unless the symbolic link is bro‐
77 ken). Actions that can cause symbolic links to become broken
78 while find is executing (for example -delete) can give rise to
79 confusing behaviour. Using -L causes the -lname and -ilname
80 predicates always to return false.
81 -H Do not follow symbolic links, except while processing the com‐
84 mand line arguments. When find examines or prints information
85 about files, the information used shall be taken from the prop‐
86 erties of the symbolic link itself. The only exception to this
87 behaviour is when a file specified on the command line is a sym‐
88 bolic link, and the link can be resolved. For that situation,
89 the information used is taken from whatever the link points to
90 (that is, the link is followed). The information about the link
91 itself is used as a fallback if the file pointed to by the sym‐
92 bolic link cannot be examined. If -H is in effect and one of
93 the paths specified on the command line is a symbolic link to a
94 directory, the contents of that directory will be examined
95 (though of course -maxdepth 0 would prevent this).
96 If more than one of -H, -L and -P is specified, each overrides the oth‐
98 ers; the last one appearing on the command line takes effect. Since it
99 is the default, the -P option should be considered to be in effect un‐
100 less either -H or -L is specified.
101 GNU find frequently stats files during the processing of the command
103 line itself, before any searching has begun. These options also affect
104 how those arguments are processed. Specifically, there are a number of
105 tests that compare files listed on the command line against a file we
106 are currently considering. In each case, the file specified on the
107 command line will have been examined and some of its properties will
108 have been saved. If the named file is in fact a symbolic link, and the
109 -P option is in effect (or if neither -H nor -L were specified), the
110 information used for the comparison will be taken from the properties
111 of the symbolic link. Otherwise, it will be taken from the properties
112 of the file the link points to. If find cannot follow the link (for
113 example because it has insufficient privileges or the link points to a
114 nonexistent file) the properties of the link itself will be used.
115 When the -H or -L options are in effect, any symbolic links listed as
117 the argument of -newer will be dereferenced, and the timestamp will be
118 taken from the file to which the symbolic link points. The same con‐
119 sideration applies to -newerXY, -anewer and -cnewer.
120 The -follow option has a similar effect to -L, though it takes effect
122 at the point where it appears (that is, if -L is not used but -follow
123 is, any symbolic links appearing after -follow on the command line will
124 be dereferenced, and those before it will not).
125 -D debugopts
128 Print diagnostic information; this can be helpful to diagnose
129 problems with why find is not doing what you want. The list of
130 debug options should be comma separated. Compatibility of the
131 debug options is not guaranteed between releases of findutils.
132 For a complete list of valid debug options, see the output of
133 find -D help. Valid debug options include
134 exec Show diagnostic information relating to -exec, -execdir,
136 -ok and -okdir
137 opt Prints diagnostic information relating to the optimisa‐
139 tion of the expression tree; see the -O option.
140 rates Prints a summary indicating how often each predicate suc‐
142 ceeded or failed.
143 search Navigate the directory tree verbosely.
145 stat Print messages as files are examined with the stat and
147 lstat system calls. The find program tries to minimise
148 such calls.
149 tree Show the expression tree in its original and optimised
151 form.
152 all Enable all of the other debug options (but help).
154 help Explain the debugging options.
156 -Olevel
158 Enables query optimisation. The find program reorders tests to
159 speed up execution while preserving the overall effect; that is,
160 predicates with side effects are not reordered relative to each
161 other. The optimisations performed at each optimisation level
162 are as follows.
163 0 Equivalent to optimisation level 1.
165 1 This is the default optimisation level and corresponds to
167 the traditional behaviour. Expressions are reordered so
168 that tests based only on the names of files (for example
169 -name and -regex) are performed first.
170 2 Any -type or -xtype tests are performed after any tests
172 based only on the names of files, but before any tests
173 that require information from the inode. On many modern
174 versions of Unix, file types are returned by readdir()
175 and so these predicates are faster to evaluate than pred‐
176 icates which need to stat the file first. If you use the
177 -fstype FOO predicate and specify a filesystem type FOO
178 which is not known (that is, present in `/etc/mtab') at
179 the time find starts, that predicate is equivalent to
180 -false.
181 3 At this optimisation level, the full cost-based query op‐
183 timiser is enabled. The order of tests is modified so
184 that cheap (i.e. fast) tests are performed first and more
185 expensive ones are performed later, if necessary. Within
186 each cost band, predicates are evaluated earlier or later
187 according to whether they are likely to succeed or not.
188 For -o, predicates which are likely to succeed are evalu‐
189 ated earlier, and for -a, predicates which are likely to
190 fail are evaluated earlier.
191 The cost-based optimiser has a fixed idea of how likely any
193 given test is to succeed. In some cases the probability takes
194 account of the specific nature of the test (for example, -type f
195 is assumed to be more likely to succeed than -type c). The
196 cost-based optimiser is currently being evaluated. If it does
197 not actually improve the performance of find, it will be removed
198 again. Conversely, optimisations that prove to be reliable, ro‐
199 bust and effective may be enabled at lower optimisation levels
200 over time. However, the default behaviour (i.e. optimisation
201 level 1) will not be changed in the 4.3.x release series. The
202 findutils test suite runs all the tests on find at each optimi‐
203 sation level and ensures that the result is the same.
204
206 The part of the command line after the list of starting points is the
207 expression. This is a kind of query specification describing how we
208 match files and what we do with the files that were matched. An ex‐
209 pression is composed of a sequence of things:
210 Tests Tests return a true or false value, usually on the basis of some
213 property of a file we are considering. The -empty test for ex‐
214 ample is true only when the current file is empty.
215 Actions
218 Actions have side effects (such as printing something on the
219 standard output) and return either true or false, usually based
220 on whether or not they are successful. The -print action for
221 example prints the name of the current file on the standard out‐
222 put.
223 Global options
226 Global options affect the operation of tests and actions speci‐
227 fied on any part of the command line. Global options always re‐
228 turn true. The -depth option for example makes find traverse
229 the file system in a depth-first order.
230 Positional options
233 Positional options affect only tests or actions which follow
234 them. Positional options always return true. The -regextype
235 option for example is positional, specifying the regular expres‐
236 sion dialect for regular expressions occurring later on the com‐
237 mand line.
238 Operators
241 Operators join together the other items within the expression.
242 They include for example -o (meaning logical OR) and -a (meaning
243 logical AND). Where an operator is missing, -a is assumed.
244 The -print action is performed on all files for which the whole expres‐
247 sion is true, unless it contains an action other than -prune or -quit.
248 Actions which inhibit the default -print are -delete, -exec, -execdir,
249 -ok, -okdir, -fls, -fprint, -fprintf, -ls, -print and -printf.
250 The -delete action also acts like an option (since it implies -depth).
253 POSITIONAL OPTIONS
256 Positional options always return true. They affect only tests occur‐
257 ring later on the command line.
258 -daystart
261 Measure times (for -amin, -atime, -cmin, -ctime, -mmin, and
262 -mtime) from the beginning of today rather than from 24 hours
263 ago. This option only affects tests which appear later on the
264 command line.
265 -follow
268 Deprecated; use the -L option instead. Dereference symbolic
269 links. Implies -noleaf. The -follow option affects only those
270 tests which appear after it on the command line. Unless the -H
271 or -L option has been specified, the position of the -follow op‐
272 tion changes the behaviour of the -newer predicate; any files
273 listed as the argument of -newer will be dereferenced if they
274 are symbolic links. The same consideration applies to -newerXY,
275 -anewer and -cnewer. Similarly, the -type predicate will always
276 match against the type of the file that a symbolic link points
277 to rather than the link itself. Using -follow causes the -lname
278 and -ilname predicates always to return false.
279 -regextype type
282 Changes the regular expression syntax understood by -regex and
283 -iregex tests which occur later on the command line. To see
284 which regular expression types are known, use -regextype help.
285 The Texinfo documentation (see SEE ALSO) explains the meaning of
286 and differences between the various types of regular expression.
287 -warn, -nowarn
290 Turn warning messages on or off. These warnings apply only to
291 the command line usage, not to any conditions that find might
292 encounter when it searches directories. The default behaviour
293 corresponds to -warn if standard input is a tty, and to -nowarn
294 otherwise. If a warning message relating to command-line usage
295 is produced, the exit status of find is not affected. If the
296 POSIXLY_CORRECT environment variable is set, and -warn is also
297 used, it is not specified which, if any, warnings will be ac‐
298 tive.
299 GLOBAL OPTIONS
302 Global options always return true. Global options take effect even for
303 tests which occur earlier on the command line. To prevent confusion,
304 global options should specified on the command-line after the list of
305 start points, just before the first test, positional option or action.
306 If you specify a global option in some other place, find will issue a
307 warning message explaining that this can be confusing.
308 The global options occur after the list of start points, and so are not
310 the same kind of option as -L, for example.
311 -d A synonym for -depth, for compatibility with FreeBSD, NetBSD,
314 MacOS X and OpenBSD.
315 -depth Process each directory's contents before the directory itself.
318 The -delete action also implies -depth.
319 -files0-from file
322 Read the starting points from file instead of getting them on
323 the command line. In contrast to the known limitations of pass‐
324 ing starting points via arguments on the command line, namely
325 the limitation of the amount of file names, and the inherent am‐
326 biguity of file names clashing with option names, using this op‐
327 tion allows to safely pass an arbitrary number of starting
328 points to find.
329 Using this option and passing starting points on the command
331 line is mutually exclusive, and is therefore not allowed at the
332 same time.
333 The file argument is mandatory. One can use -files0-from - to
335 read the list of starting points from the standard input stream,
336 and e.g. from a pipe. In this case, the actions -ok and -okdir
337 are not allowed, because they would obviously interfere with
338 reading from standard input in order to get a user confirmation.
339 The starting points in file have to be separated by ASCII NUL
341 characters. Two consecutive NUL characters, i.e., a starting
342 point with a Zero-length file name is not allowed and will lead
343 to an error diagnostic followed by a non-Zero exit code later.
344 In the case the given file is empty, find does not process any
346 starting point and therefore will exit immediately after parsing
347 the program arguments. This is unlike the standard invocation
348 where find assumes the current directory as starting point if no
349 path argument is passed.
350 The processing of the starting points is otherwise as usual,
352 e.g. find will recurse into subdirectories unless otherwise
353 prevented. To process only the starting points, one can addi‐
354 tionally pass -maxdepth 0.
355 Further notes: if a file is listed more than once in the input
357 file, it is unspecified whether it is visited more than once.
358 If the file is mutated during the operation of find, the result
359 is unspecified as well. Finally, the seek position within the
360 named file at the time find exits, be it with -quit or in any
361 other way, is also unspecified. By "unspecified" here is meant
362 that it may or may not work or do any specific thing, and that
363 the behavior may change from platform to platform, or from find‐
364 utils release to release.
365 -help, --help
368 Print a summary of the command-line usage of find and exit.
369 -ignore_readdir_race
372 Normally, find will emit an error message when it fails to stat
373 a file. If you give this option and a file is deleted between
374 the time find reads the name of the file from the directory and
375 the time it tries to stat the file, no error message will be is‐
376 sued. This also applies to files or directories whose names are
377 given on the command line. This option takes effect at the time
378 the command line is read, which means that you cannot search one
379 part of the filesystem with this option on and part of it with
380 this option off (if you need to do that, you will need to issue
381 two find commands instead, one with the option and one without
382 it).
383 Furthermore, find with the -ignore_readdir_race option will ig‐
385 nore errors of the -delete action in the case the file has dis‐
386 appeared since the parent directory was read: it will not output
387 an error diagnostic, and the return code of the -delete action
388 will be true.
389 -maxdepth levels
392 Descend at most levels (a non-negative integer) levels of direc‐
393 tories below the starting-points. Using -maxdepth 0 means only
394 apply the tests and actions to the starting-points themselves.
395 -mindepth levels
398 Do not apply any tests or actions at levels less than levels (a
399 non-negative integer). Using -mindepth 1 means process all
400 files except the starting-points.
401 -mount Don't descend directories on other filesystems. An alternate
404 name for -xdev, for compatibility with some other versions of
405 find.
406 -noignore_readdir_race
409 Turns off the effect of -ignore_readdir_race.
410 -noleaf
413 Do not optimize by assuming that directories contain 2 fewer
414 subdirectories than their hard link count. This option is
415 needed when searching filesystems that do not follow the Unix
416 directory-link convention, such as CD-ROM or MS-DOS filesystems
417 or AFS volume mount points. Each directory on a normal Unix
418 filesystem has at least 2 hard links: its name and its `.' en‐
419 try. Additionally, its subdirectories (if any) each have a `..'
420 entry linked to that directory. When find is examining a direc‐
421 tory, after it has statted 2 fewer subdirectories than the di‐
422 rectory's link count, it knows that the rest of the entries in
423 the directory are non-directories (`leaf' files in the directory
424 tree). If only the files' names need to be examined, there is
425 no need to stat them; this gives a significant increase in
426 search speed.
427 -version, --version
430 Print the find version number and exit.
431 -xautofs
434 Don't descend directories on autofs filesystems.
435 -xdev Don't descend directories on other filesystems.
438 TESTS
441 Some tests, for example -newerXY and -samefile, allow comparison be‐
442 tween the file currently being examined and some reference file speci‐
443 fied on the command line. When these tests are used, the interpreta‐
444 tion of the reference file is determined by the options -H, -L and -P
445 and any previous -follow, but the reference file is only examined once,
446 at the time the command line is parsed. If the reference file cannot
447 be examined (for example, the stat(2) system call fails for it), an er‐
448 ror message is issued, and find exits with a nonzero status.
449 A numeric argument n can be specified to tests (like -amin, -mtime,
451 -gid, -inum, -links, -size, -uid and -used) as
452 +n for greater than n,
454 -n for less than n,
456 n for exactly n.
458 Supported tests:
460 -amin n
463 File was last accessed less than, more than or exactly n minutes
464 ago.
465 -anewer reference
468 Time of the last access of the current file is more recent than
469 that of the last data modification of the reference file. If
470 reference is a symbolic link and the -H option or the -L option
471 is in effect, then the time of the last data modification of the
472 file it points to is always used.
473 -atime n
476 File was last accessed less than, more than or exactly n*24
477 hours ago. When find figures out how many 24-hour periods ago
478 the file was last accessed, any fractional part is ignored, so
479 to match -atime +1, a file has to have been accessed at least
480 two days ago.
481 -cmin n
484 File's status was last changed less than, more than or exactly n
485 minutes ago.
486 -cnewer reference
489 Time of the last status change of the current file is more re‐
490 cent than that of the last data modification of the reference
491 file. If reference is a symbolic link and the -H option or the
492 -L option is in effect, then the time of the last data modifica‐
493 tion of the file it points to is always used.
494 -ctime n
497 File's status was last changed less than, more than or exactly
498 n*24 hours ago. See the comments for -atime to understand how
499 rounding affects the interpretation of file status change times.
500 -empty File is empty and is either a regular file or a directory.
503 -executable
506 Matches files which are executable and directories which are
507 searchable (in a file name resolution sense) by the current
508 user. This takes into account access control lists and other
509 permissions artefacts which the -perm test ignores. This test
510 makes use of the access(2) system call, and so can be fooled by
511 NFS servers which do UID mapping (or root-squashing), since many
512 systems implement access(2) in the client's kernel and so cannot
513 make use of the UID mapping information held on the server. Be‐
514 cause this test is based only on the result of the access(2)
515 system call, there is no guarantee that a file for which this
516 test succeeds can actually be executed.
517 -false Always false.
520 -fstype type
523 File is on a filesystem of type type. The valid filesystem
524 types vary among different versions of Unix; an incomplete list
525 of filesystem types that are accepted on some version of Unix or
526 another is: ufs, 4.2, 4.3, nfs, tmp, mfs, S51K, S52K. You can
527 use -printf with the %F directive to see the types of your
528 filesystems.
529 -gid n File's numeric group ID is less than, more than or exactly n.
532 -group gname
535 File belongs to group gname (numeric group ID allowed).
536 -ilname pattern
539 Like -lname, but the match is case insensitive. If the -L op‐
540 tion or the -follow option is in effect, this test returns false
541 unless the symbolic link is broken.
542 -iname pattern
546 Like -name, but the match is case insensitive. For example, the
547 patterns `fo*' and `F??' match the file names `Foo', `FOO',
548 `foo', `fOo', etc. The pattern `*foo*` will also match a file
549 called '.foobar'.
550 -inum n
553 File has inode number smaller than, greater than or exactly n.
554 It is normally easier to use the -samefile test instead.
555 -ipath pattern
558 Like -path. but the match is case insensitive.
559 -iregex pattern
562 Like -regex, but the match is case insensitive.
563 -iwholename pattern
566 See -ipath. This alternative is less portable than -ipath.
567 -links n
570 File has less than, more than or exactly n hard links.
571 -lname pattern
574 File is a symbolic link whose contents match shell pattern pat‐
575 tern. The metacharacters do not treat `/' or `.' specially. If
576 the -L option or the -follow option is in effect, this test re‐
577 turns false unless the symbolic link is broken.
578 -mmin n
581 File's data was last modified less than, more than or exactly n
582 minutes ago.
583 -mtime n
586 File's data was last modified less than, more than or exactly
587 n*24 hours ago. See the comments for -atime to understand how
588 rounding affects the interpretation of file modification times.
589 -name pattern
592 Base of file name (the path with the leading directories re‐
593 moved) matches shell pattern pattern. Because the leading di‐
594 rectories are removed, the file names considered for a match
595 with -name will never include a slash, so `-name a/b' will never
596 match anything (you probably need to use -path instead). A
597 warning is issued if you try to do this, unless the environment
598 variable POSIXLY_CORRECT is set. The metacharacters (`*', `?',
599 and `[]') match a `.' at the start of the base name (this is a
600 change in findutils-4.2.2; see section STANDARDS CONFORMANCE be‐
601 low). To ignore a directory and the files under it, use -prune
602 rather than checking every file in the tree; see an example in
603 the description of that action. Braces are not recognised as
604 being special, despite the fact that some shells including Bash
605 imbue braces with a special meaning in shell patterns. The
606 filename matching is performed with the use of the fnmatch(3)
607 library function. Don't forget to enclose the pattern in quotes
608 in order to protect it from expansion by the shell.
609 -newer reference
612 Time of the last data modification of the current file is more
613 recent than that of the last data modification of the reference
614 file. If reference is a symbolic link and the -H option or the
615 -L option is in effect, then the time of the last data modifica‐
616 tion of the file it points to is always used.
617 -newerXY reference
620 Succeeds if timestamp X of the file being considered is newer
621 than timestamp Y of the file reference. The letters X and Y can
622 be any of the following letters:
623 a The access time of the file reference
626 B The birth time of the file reference
627 c The inode status change time of reference
628 m The modification time of the file reference
629 t reference is interpreted directly as a time
630 Some combinations are invalid; for example, it is invalid for X
632 to be t. Some combinations are not implemented on all systems;
633 for example B is not supported on all systems. If an invalid or
634 unsupported combination of XY is specified, a fatal error re‐
635 sults. Time specifications are interpreted as for the argument
636 to the -d option of GNU date. If you try to use the birth time
637 of a reference file, and the birth time cannot be determined, a
638 fatal error message results. If you specify a test which refers
639 to the birth time of files being examined, this test will fail
640 for any files where the birth time is unknown.
641 -nogroup
644 No group corresponds to file's numeric group ID.
645 -nouser
648 No user corresponds to file's numeric user ID.
649 -path pattern
652 File name matches shell pattern pattern. The metacharacters do
653 not treat `/' or `.' specially; so, for example,
654 find . -path "./sr*sc"
655 will print an entry for a directory called ./src/misc (if one
656 exists). To ignore a whole directory tree, use -prune rather
657 than checking every file in the tree. Note that the pattern
658 match test applies to the whole file name, starting from one of
659 the start points named on the command line. It would only make
660 sense to use an absolute path name here if the relevant start
661 point is also an absolute path. This means that this command
662 will never match anything:
663 find bar -path /foo/bar/myfile -print
664 Find compares the -path argument with the concatenation of a di‐
665 rectory name and the base name of the file it's examining.
666 Since the concatenation will never end with a slash, -path argu‐
667 ments ending in a slash will match nothing (except perhaps a
668 start point specified on the command line). The predicate -path
669 is also supported by HP-UX find and is part of the POSIX 2008
670 standard.
671 -perm mode
674 File's permission bits are exactly mode (octal or symbolic).
675 Since an exact match is required, if you want to use this form
676 for symbolic modes, you may have to specify a rather complex
677 mode string. For example `-perm g=w' will only match files
678 which have mode 0020 (that is, ones for which group write per‐
679 mission is the only permission set). It is more likely that you
680 will want to use the `/' or `-' forms, for example `-perm -g=w',
681 which matches any file with group write permission. See the EX‐
682 AMPLES section for some illustrative examples.
683 -perm -mode
686 All of the permission bits mode are set for the file. Symbolic
687 modes are accepted in this form, and this is usually the way in
688 which you would want to use them. You must specify `u', `g' or
689 `o' if you use a symbolic mode. See the EXAMPLES section for
690 some illustrative examples.
691 -perm /mode
694 Any of the permission bits mode are set for the file. Symbolic
695 modes are accepted in this form. You must specify `u', `g' or
696 `o' if you use a symbolic mode. See the EXAMPLES section for
697 some illustrative examples. If no permission bits in mode are
698 set, this test matches any file (the idea here is to be consis‐
699 tent with the behaviour of -perm -000).
700 -perm +mode
703 This is no longer supported (and has been deprecated since
704 2005). Use -perm /mode instead.
705 -readable
708 Matches files which are readable by the current user. This
709 takes into account access control lists and other permissions
710 artefacts which the -perm test ignores. This test makes use of
711 the access(2) system call, and so can be fooled by NFS servers
712 which do UID mapping (or root-squashing), since many systems im‐
713 plement access(2) in the client's kernel and so cannot make use
714 of the UID mapping information held on the server.
715 -regex pattern
718 File name matches regular expression pattern. This is a match
719 on the whole path, not a search. For example, to match a file
720 named ./fubar3, you can use the regular expression `.*bar.' or
721 `.*b.*3', but not `f.*r3'. The regular expressions understood
722 by find are by default Emacs Regular Expressions (except that
723 `.' matches newline), but this can be changed with the -regex‐
724 type option.
725 -samefile name
728 File refers to the same inode as name. When -L is in effect,
729 this can include symbolic links.
730 -size n[cwbkMG]
733 File uses less than, more than or exactly n units of space,
734 rounding up. The following suffixes can be used:
735 `b' for 512-byte blocks (this is the default if no suffix is
737 used)
738 `c' for bytes
740 `w' for two-byte words
742 `k' for kibibytes (KiB, units of 1024 bytes)
744 `M' for mebibytes (MiB, units of 1024 * 1024 = 1048576 bytes)
746 `G' for gibibytes (GiB, units of 1024 * 1024 * 1024 =
748 1073741824 bytes)
749 The size is simply the st_size member of the struct stat popu‐
751 lated by the lstat (or stat) system call, rounded up as shown
752 above. In other words, it's consistent with the result you get
753 for ls -l. Bear in mind that the `%k' and `%b' format speci‐
754 fiers of -printf handle sparse files differently. The `b' suf‐
755 fix always denotes 512-byte blocks and never 1024-byte blocks,
756 which is different to the behaviour of -ls.
757 The + and - prefixes signify greater than and less than, as
759 usual; i.e., an exact size of n units does not match. Bear in
760 mind that the size is rounded up to the next unit. Therefore
761 -size -1M is not equivalent to -size -1048576c. The former only
762 matches empty files, the latter matches files from 0 to
763 1,048,575 bytes.
764 -true Always true.
766 -type c
769 File is of type c:
770 b block (buffered) special
772 c character (unbuffered) special
774 d directory
776 p named pipe (FIFO)
778 f regular file
780 l symbolic link; this is never true if the -L option or the
782 -follow option is in effect, unless the symbolic link is
783 broken. If you want to search for symbolic links when -L
784 is in effect, use -xtype.
785 s socket
787 D door (Solaris)
789 To search for more than one type at once, you can supply the
791 combined list of type letters separated by a comma `,' (GNU ex‐
792 tension).
793 -uid n File's numeric user ID is less than, more than or exactly n.
795 -used n
798 File was last accessed less than, more than or exactly n days
799 after its status was last changed.
800 -user uname
803 File is owned by user uname (numeric user ID allowed).
804 -wholename pattern
807 See -path. This alternative is less portable than -path.
808 -writable
811 Matches files which are writable by the current user. This
812 takes into account access control lists and other permissions
813 artefacts which the -perm test ignores. This test makes use of
814 the access(2) system call, and so can be fooled by NFS servers
815 which do UID mapping (or root-squashing), since many systems im‐
816 plement access(2) in the client's kernel and so cannot make use
817 of the UID mapping information held on the server.
818 -xtype c
821 The same as -type unless the file is a symbolic link. For sym‐
822 bolic links: if the -H or -P option was specified, true if the
823 file is a link to a file of type c; if the -L option has been
824 given, true if c is `l'. In other words, for symbolic links,
825 -xtype checks the type of the file that -type does not check.
826 -context pattern
828 (SELinux only) Security context of the file matches glob pat‐
829 tern.
830 ACTIONS
833 -delete
834 Delete files or directories; true if removal succeeded. If the
835 removal failed, an error message is issued and find's exit sta‐
836 tus will be nonzero (when it eventually exits).
837 Warning: Don't forget that find evaluates the command line as an
839 expression, so putting -delete first will make find try to
840 delete everything below the starting points you specified.
841 The use of the -delete action on the command line automatically
843 turns on the -depth option. As in turn -depth makes -prune in‐
844 effective, the -delete action cannot usefully be combined with
845 -prune.
846 Often, the user might want to test a find command line with
848 -print prior to adding -delete for the actual removal run. To
849 avoid surprising results, it is usually best to remember to use
850 -depth explicitly during those earlier test runs.
851 The -delete action will fail to remove a directory unless it is
853 empty.
854 Together with the -ignore_readdir_race option, find will ignore
856 errors of the -delete action in the case the file has disap‐
857 peared since the parent directory was read: it will not output
858 an error diagnostic, not change the exit code to nonzero, and
859 the return code of the -delete action will be true.
860 -exec command ;
864 Execute command; true if 0 status is returned. All following
865 arguments to find are taken to be arguments to the command until
866 an argument consisting of `;' is encountered. The string `{}'
867 is replaced by the current file name being processed everywhere
868 it occurs in the arguments to the command, not just in arguments
869 where it is alone, as in some versions of find. Both of these
870 constructions might need to be escaped (with a `\') or quoted to
871 protect them from expansion by the shell. See the EXAMPLES sec‐
872 tion for examples of the use of the -exec option. The specified
873 command is run once for each matched file. The command is exe‐
874 cuted in the starting directory. There are unavoidable security
875 problems surrounding use of the -exec action; you should use the
876 -execdir option instead.
877 -exec command {} +
880 This variant of the -exec action runs the specified command on
881 the selected files, but the command line is built by appending
882 each selected file name at the end; the total number of invoca‐
883 tions of the command will be much less than the number of
884 matched files. The command line is built in much the same way
885 that xargs builds its command lines. Only one instance of `{}'
886 is allowed within the command, and it must appear at the end,
887 immediately before the `+'; it needs to be escaped (with a `\')
888 or quoted to protect it from interpretation by the shell. The
889 command is executed in the starting directory. If any invoca‐
890 tion with the `+' form returns a non-zero value as exit status,
891 then find returns a non-zero exit status. If find encounters an
892 error, this can sometimes cause an immediate exit, so some pend‐
893 ing commands may not be run at all. For this reason -exec my-
894 command ... {} + -quit may not result in my-command actually be‐
895 ing run. This variant of -exec always returns true.
896 -execdir command ;
899 -execdir command {} +
901 Like -exec, but the specified command is run from the subdirec‐
902 tory containing the matched file, which is not normally the di‐
903 rectory in which you started find. As with -exec, the {} should
904 be quoted if find is being invoked from a shell. This a much
905 more secure method for invoking commands, as it avoids race con‐
906 ditions during resolution of the paths to the matched files. As
907 with the -exec action, the `+' form of -execdir will build a
908 command line to process more than one matched file, but any
909 given invocation of command will only list files that exist in
910 the same subdirectory. If you use this option, you must ensure
911 that your PATH environment variable does not reference `.'; oth‐
912 erwise, an attacker can run any commands they like by leaving an
913 appropriately-named file in a directory in which you will run
914 -execdir. The same applies to having entries in PATH which are
915 empty or which are not absolute directory names. If any invoca‐
916 tion with the `+' form returns a non-zero value as exit status,
917 then find returns a non-zero exit status. If find encounters an
918 error, this can sometimes cause an immediate exit, so some pend‐
919 ing commands may not be run at all. The result of the action
920 depends on whether the + or the ; variant is being used; -ex‐
921 ecdir command {} + always returns true, while -execdir com‐
922 mand {} ; returns true only if command returns 0.
923 -fls file
927 True; like -ls but write to file like -fprint. The output file
928 is always created, even if the predicate is never matched. See
929 the UNUSUAL FILENAMES section for information about how unusual
930 characters in filenames are handled.
931 -fprint file
934 True; print the full file name into file file. If file does not
935 exist when find is run, it is created; if it does exist, it is
936 truncated. The file names /dev/stdout and /dev/stderr are han‐
937 dled specially; they refer to the standard output and standard
938 error output, respectively. The output file is always created,
939 even if the predicate is never matched. See the UNUSUAL FILE‐
940 NAMES section for information about how unusual characters in
941 filenames are handled.
942 -fprint0 file
945 True; like -print0 but write to file like -fprint. The output
946 file is always created, even if the predicate is never matched.
947 See the UNUSUAL FILENAMES section for information about how un‐
948 usual characters in filenames are handled.
949 -fprintf file format
952 True; like -printf but write to file like -fprint. The output
953 file is always created, even if the predicate is never matched.
954 See the UNUSUAL FILENAMES section for information about how un‐
955 usual characters in filenames are handled.
956 -ls True; list current file in ls -dils format on standard output.
959 The block counts are of 1 KB blocks, unless the environment
960 variable POSIXLY_CORRECT is set, in which case 512-byte blocks
961 are used. See the UNUSUAL FILENAMES section for information
962 about how unusual characters in filenames are handled.
963 -ok command ;
966 Like -exec but ask the user first. If the user agrees, run the
967 command. Otherwise just return false. If the command is run,
968 its standard input is redirected from /dev/null. This action
969 may not be specified together with the -files0-from option.
970 The response to the prompt is matched against a pair of regular
973 expressions to determine if it is an affirmative or negative re‐
974 sponse. This regular expression is obtained from the system if
975 the POSIXLY_CORRECT environment variable is set, or otherwise
976 from find's message translations. If the system has no suitable
977 definition, find's own definition will be used. In either case,
978 the interpretation of the regular expression itself will be af‐
979 fected by the environment variables LC_CTYPE (character classes)
980 and LC_COLLATE (character ranges and equivalence classes).
981 -okdir command ;
986 Like -execdir but ask the user first in the same way as for -ok.
987 If the user does not agree, just return false. If the command
988 is run, its standard input is redirected from /dev/null. This
989 action may not be specified together with the -files0-from op‐
990 tion.
991 -print True; print the full file name on the standard output, followed
995 by a newline. If you are piping the output of find into another
996 program and there is the faintest possibility that the files
997 which you are searching for might contain a newline, then you
998 should seriously consider using the -print0 option instead of
999 -print. See the UNUSUAL FILENAMES section for information about
1000 how unusual characters in filenames are handled.
1001 -print0
1004 True; print the full file name on the standard output, followed
1005 by a null character (instead of the newline character that
1006 -print uses). This allows file names that contain newlines or
1007 other types of white space to be correctly interpreted by pro‐
1008 grams that process the find output. This option corresponds to
1009 the -0 option of xargs.
1010 -printf format
1013 True; print format on the standard output, interpreting `\' es‐
1014 capes and `%' directives. Field widths and precisions can be
1015 specified as with the printf(3) C function. Please note that
1016 many of the fields are printed as %s rather than %d, and this
1017 may mean that flags don't work as you might expect. This also
1018 means that the `-' flag does work (it forces fields to be left-
1019 aligned). Unlike -print, -printf does not add a newline at the
1020 end of the string. The escapes and directives are:
1021 \a Alarm bell.
1023 \b Backspace.
1025 \c Stop printing from this format immediately and flush the
1027 output.
1028 \f Form feed.
1030 \n Newline.
1032 \r Carriage return.
1034 \t Horizontal tab.
1036 \v Vertical tab.
1038 \0 ASCII NUL.
1040 \\ A literal backslash (`\').
1042 \NNN The character whose ASCII code is NNN (octal).
1044 A `\' character followed by any other character is treated as an
1046 ordinary character, so they both are printed.
1047 %% A literal percent sign.
1049 %a File's last access time in the format returned by the C
1051 ctime(3) function.
1052 %Ak File's last access time in the format specified by k,
1054 which is either `@' or a directive for the C strftime(3)
1055 function. The following shows an incomplete list of pos‐
1056 sible values for k. Please refer to the documentation of
1057 strftime(3) for the full list. Some of the conversion
1058 specification characters might not be available on all
1059 systems, due to differences in the implementation of the
1060 strftime(3) library function.
1061 @ seconds since Jan. 1, 1970, 00:00 GMT, with frac‐
1063 tional part.
1064 Time fields:
1066 H hour (00..23)
1068 I hour (01..12)
1070 k hour ( 0..23)
1072 l hour ( 1..12)
1074 M minute (00..59)
1076 p locale's AM or PM
1078 r time, 12-hour (hh:mm:ss [AP]M)
1080 S Second (00.00 .. 61.00). There is a fractional
1082 part.
1083 T time, 24-hour (hh:mm:ss.xxxxxxxxxx)
1085 + Date and time, separated by `+', for example
1087 `2004-04-28+22:22:05.0'. This is a GNU extension.
1088 The time is given in the current timezone (which
1089 may be affected by setting the TZ environment
1090 variable). The seconds field includes a frac‐
1091 tional part.
1092 X locale's time representation (H:M:S). The seconds
1094 field includes a fractional part.
1095 Z time zone (e.g., EDT), or nothing if no time zone
1097 is determinable
1098 Date fields:
1100 a locale's abbreviated weekday name (Sun..Sat)
1102 A locale's full weekday name, variable length (Sun‐
1104 day..Saturday)
1105 b locale's abbreviated month name (Jan..Dec)
1107 B locale's full month name, variable length (Janu‐
1109 ary..December)
1110 c locale's date and time (Sat Nov 04 12:02:33 EST
1112 1989). The format is the same as for ctime(3) and
1113 so to preserve compatibility with that format,
1114 there is no fractional part in the seconds field.
1115 d day of month (01..31)
1117 D date (mm/dd/yy)
1119 F date (yyyy-mm-dd)
1121 h same as b
1123 j day of year (001..366)
1125 m month (01..12)
1127 U week number of year with Sunday as first day of
1129 week (00..53)
1130 w day of week (0..6)
1132 W week number of year with Monday as first day of
1134 week (00..53)
1135 x locale's date representation (mm/dd/yy)
1137 y last two digits of year (00..99)
1139 Y year (1970...)
1141 %b The amount of disk space used for this file in 512-byte
1143 blocks. Since disk space is allocated in multiples of
1144 the filesystem block size this is usually greater than
1145 %s/512, but it can also be smaller if the file is a
1146 sparse file.
1147 %Bk File's birth time, i.e., its creation time, in the format
1150 specified by k, which is the same as for %A. This direc‐
1151 tive produces an empty string if the underlying operating
1152 system or filesystem does not support birth times.
1153 %c File's last status change time in the format returned by
1156 the C ctime(3) function.
1157 %Ck File's last status change time in the format specified by
1159 k, which is the same as for %A.
1160 %d File's depth in the directory tree; 0 means the file is a
1162 starting-point.
1163 %D The device number on which the file exists (the st_dev
1165 field of struct stat), in decimal.
1166 %f Print the basename; the file's name with any leading di‐
1168 rectories removed (only the last element). For /, the
1169 result is `/'. See the EXAMPLES section for an example.
1170 %F Type of the filesystem the file is on; this value can be
1173 used for -fstype.
1174 %g File's group name, or numeric group ID if the group has
1176 no name.
1177 %G File's numeric group ID.
1179 %h Dirname; the Leading directories of the file's name (all
1181 but the last element). If the file name contains no
1182 slashes (since it is in the current directory) the %h
1183 specifier expands to `.'. For files which are themselves
1184 directories and contain a slash (including /), %h expands
1185 to the empty string. See the EXAMPLES section for an ex‐
1186 ample.
1187 %H Starting-point under which file was found.
1189 %i File's inode number (in decimal).
1191 %k The amount of disk space used for this file in 1 KB
1193 blocks. Since disk space is allocated in multiples of
1194 the filesystem block size this is usually greater than
1195 %s/1024, but it can also be smaller if the file is a
1196 sparse file.
1197 %l Object of symbolic link (empty string if file is not a
1199 symbolic link).
1200 %m File's permission bits (in octal). This option uses the
1202 `traditional' numbers which most Unix implementations
1203 use, but if your particular implementation uses an un‐
1204 usual ordering of octal permissions bits, you will see a
1205 difference between the actual value of the file's mode
1206 and the output of %m. Normally you will want to have a
1207 leading zero on this number, and to do this, you should
1208 use the # flag (as in, for example, `%#m').
1209 %M File's permissions (in symbolic form, as for ls). This
1211 directive is supported in findutils 4.2.5 and later.
1212 %n Number of hard links to file.
1214 %p File's name.
1216 %P File's name with the name of the starting-point under
1218 which it was found removed.
1219 %s File's size in bytes.
1221 %S File's sparseness. This is calculated as (BLOCK‐
1223 SIZE*st_blocks / st_size). The exact value you will get
1224 for an ordinary file of a certain length is system-depen‐
1225 dent. However, normally sparse files will have values
1226 less than 1.0, and files which use indirect blocks may
1227 have a value which is greater than 1.0. In general the
1228 number of blocks used by a file is file system dependent.
1229 The value used for BLOCKSIZE is system-dependent, but is
1230 usually 512 bytes. If the file size is zero, the value
1231 printed is undefined. On systems which lack support for
1232 st_blocks, a file's sparseness is assumed to be 1.0.
1233 %t File's last modification time in the format returned by
1235 the C ctime(3) function.
1236 %Tk File's last modification time in the format specified by
1238 k, which is the same as for %A.
1239 %u File's user name, or numeric user ID if the user has no
1241 name.
1242 %U File's numeric user ID.
1244 %y File's type (like in ls -l), U=unknown type (shouldn't
1246 happen)
1247 %Y File's type (like %y), plus follow symbolic links:
1249 `L'=loop, `N'=nonexistent, `?' for any other error when
1250 determining the type of the target of a symbolic link.
1251 %Z (SELinux only) file's security context.
1253 %{ %[ %(
1255 Reserved for future use.
1256 A `%' character followed by any other character is discarded,
1258 but the other character is printed (don't rely on this, as fur‐
1259 ther format characters may be introduced). A `%' at the end of
1260 the format argument causes undefined behaviour since there is no
1261 following character. In some locales, it may hide your door
1262 keys, while in others it may remove the final page from the
1263 novel you are reading.
1264 The %m and %d directives support the #, 0 and + flags, but the
1266 other directives do not, even if they print numbers. Numeric
1267 directives that do not support these flags include G, U, b, D, k
1268 and n. The `-' format flag is supported and changes the align‐
1269 ment of a field from right-justified (which is the default) to
1270 left-justified.
1271 See the UNUSUAL FILENAMES section for information about how un‐
1273 usual characters in filenames are handled.
1274 -prune True; if the file is a directory, do not descend into it. If
1278 -depth is given, then -prune has no effect. Because -delete im‐
1279 plies -depth, you cannot usefully use -prune and -delete to‐
1280 gether. For example, to skip the directory src/emacs and all
1281 files and directories under it, and print the names of the other
1282 files found, do something like this:
1283 find . -path ./src/emacs -prune -o -print
1284 -quit Exit immediately (with return value zero if no errors have oc‐
1288 curred). This is different to -prune because -prune only ap‐
1289 plies to the contents of pruned directories, while -quit simply
1290 makes find stop immediately. No child processes will be left
1291 running. Any command lines which have been built by -exec ... +
1292 or -execdir ... + are invoked before the program is exited. Af‐
1293 ter -quit is executed, no more files specified on the command
1294 line will be processed. For example,
1295 `find /tmp/foo /tmp/bar -print -quit` will print only
1296 `/tmp/foo`.
1297 One common use of -quit is to stop searching the file system
1298 once we have found what we want. For example, if we want to
1299 find just a single file we can do this:
1300 find / -name needle -print -quit
1301 OPERATORS
1304 Listed in order of decreasing precedence:
1305 ( expr )
1308 Force precedence. Since parentheses are special to the shell,
1309 you will normally need to quote them. Many of the examples in
1310 this manual page use backslashes for this purpose: `\(...\)' in‐
1311 stead of `(...)'.
1312 ! expr True if expr is false. This character will also usually need
1315 protection from interpretation by the shell.
1316 -not expr
1319 Same as ! expr, but not POSIX compliant.
1320 expr1 expr2
1323 Two expressions in a row are taken to be joined with an implied
1324 -a; expr2 is not evaluated if expr1 is false.
1325 expr1 -a expr2
1328 Same as expr1 expr2.
1329 expr1 -and expr2
1332 Same as expr1 expr2, but not POSIX compliant.
1333 expr1 -o expr2
1336 Or; expr2 is not evaluated if expr1 is true.
1337 expr1 -or expr2
1340 Same as expr1 -o expr2, but not POSIX compliant.
1341 expr1 , expr2
1344 List; both expr1 and expr2 are always evaluated. The value of
1345 expr1 is discarded; the value of the list is the value of expr2.
1346 The comma operator can be useful for searching for several dif‐
1347 ferent types of thing, but traversing the filesystem hierarchy
1348 only once. The -fprintf action can be used to list the various
1349 matched items into several different output files.
1350 Please note that -a when specified implicitly (for example by two tests
1352 appearing without an explicit operator between them) or explicitly has
1353 higher precedence than -o. This means that find . -name afile -o -name
1354 bfile -print will never print afile.
1355
1357 Many of the actions of find result in the printing of data which is un‐
1358 der the control of other users. This includes file names, sizes, modi‐
1359 fication times and so forth. File names are a potential problem since
1360 they can contain any character except `\0' and `/'. Unusual characters
1361 in file names can do unexpected and often undesirable things to your
1362 terminal (for example, changing the settings of your function keys on
1363 some terminals). Unusual characters are handled differently by various
1364 actions, as described below.
1365 -print0, -fprint0
1368 Always print the exact filename, unchanged, even if the output
1369 is going to a terminal.
1370 -ls, -fls
1373 Unusual characters are always escaped. White space, backslash,
1374 and double quote characters are printed using C-style escaping
1375 (for example `\f', `\"'). Other unusual characters are printed
1376 using an octal escape. Other printable characters (for -ls and
1377 -fls these are the characters between octal 041 and 0176) are
1378 printed as-is.
1379 -printf, -fprintf
1382 If the output is not going to a terminal, it is printed as-is.
1383 Otherwise, the result depends on which directive is in use. The
1384 directives %D, %F, %g, %G, %H, %Y, and %y expand to values which
1385 are not under control of files' owners, and so are printed as-
1386 is. The directives %a, %b, %c, %d, %i, %k, %m, %M, %n, %s, %t,
1387 %u and %U have values which are under the control of files' own‐
1388 ers but which cannot be used to send arbitrary data to the ter‐
1389 minal, and so these are printed as-is. The directives %f, %h,
1390 %l, %p and %P are quoted. This quoting is performed in the same
1391 way as for GNU ls. This is not the same quoting mechanism as
1392 the one used for -ls and -fls. If you are able to decide what
1393 format to use for the output of find then it is normally better
1394 to use `\0' as a terminator than to use newline, as file names
1395 can contain white space and newline characters. The setting of
1396 the LC_CTYPE environment variable is used to determine which
1397 characters need to be quoted.
1398 -print, -fprint
1401 Quoting is handled in the same way as for -printf and -fprintf.
1402 If you are using find in a script or in a situation where the
1403 matched files might have arbitrary names, you should consider
1404 using -print0 instead of -print.
1405 The -ok and -okdir actions print the current filename as-is. This may
1407 change in a future release.
1408
1410 For closest compliance to the POSIX standard, you should set the
1411 POSIXLY_CORRECT environment variable. The following options are speci‐
1412 fied in the POSIX standard (IEEE Std 1003.1-2008, 2016 Edition):
1413 -H This option is supported.
1416 -L This option is supported.
1419 -name This option is supported, but POSIX conformance depends on the
1422 POSIX conformance of the system's fnmatch(3) library function.
1423 As of findutils-4.2.2, shell metacharacters (`*', `?' or `[]'
1424 for example) match a leading `.', because IEEE PASC interpreta‐
1425 tion 126 requires this. This is a change from previous versions
1426 of findutils.
1427 -type Supported. POSIX specifies `b', `c', `d', `l', `p', `f' and
1430 `s'. GNU find also supports `D', representing a Door, where the
1431 OS provides these. Furthermore, GNU find allows multiple types
1432 to be specified at once in a comma-separated list.
1433 -ok Supported. Interpretation of the response is according to the
1436 `yes' and `no' patterns selected by setting the LC_MESSAGES en‐
1437 vironment variable. When the POSIXLY_CORRECT environment vari‐
1438 able is set, these patterns are taken system's definition of a
1439 positive (yes) or negative (no) response. See the system's doc‐
1440 umentation for nl_langinfo(3), in particular YESEXPR and NOEXPR.
1441 When POSIXLY_CORRECT is not set, the patterns are instead taken
1442 from find's own message catalogue.
1443 -newer Supported. If the file specified is a symbolic link, it is al‐
1446 ways dereferenced. This is a change from previous behaviour,
1447 which used to take the relevant time from the symbolic link; see
1448 the HISTORY section below.
1449 -perm Supported. If the POSIXLY_CORRECT environment variable is not
1452 set, some mode arguments (for example +a+x) which are not valid
1453 in POSIX are supported for backward-compatibility.
1454 Other primaries
1457 The primaries -atime, -ctime, -depth, -exec, -group, -links,
1458 -mtime, -nogroup, -nouser, -ok, -path, -print, -prune, -size,
1459 -user and -xdev are all supported.
1460 The POSIX standard specifies parentheses `(', `)', negation `!' and the
1463 logical AND/OR operators -a and -o.
1464 All other options, predicates, expressions and so forth are extensions
1466 beyond the POSIX standard. Many of these extensions are not unique to
1467 GNU find, however.
1468 The POSIX standard requires that find detects loops:
1470 The find utility shall detect infinite loops; that is, entering
1472 a previously visited directory that is an ancestor of the last
1473 file encountered. When it detects an infinite loop, find shall
1474 write a diagnostic message to standard error and shall either
1475 recover its position in the hierarchy or terminate.
1476 GNU find complies with these requirements. The link count of directo‐
1478 ries which contain entries which are hard links to an ancestor will of‐
1479 ten be lower than they otherwise should be. This can mean that GNU
1480 find will sometimes optimise away the visiting of a subdirectory which
1481 is actually a link to an ancestor. Since find does not actually enter
1482 such a subdirectory, it is allowed to avoid emitting a diagnostic mes‐
1483 sage. Although this behaviour may be somewhat confusing, it is un‐
1484 likely that anybody actually depends on this behaviour. If the leaf
1485 optimisation has been turned off with -noleaf, the directory entry will
1486 always be examined and the diagnostic message will be issued where it
1487 is appropriate. Symbolic links cannot be used to create filesystem cy‐
1488 cles as such, but if the -L option or the -follow option is in use, a
1489 diagnostic message is issued when find encounters a loop of symbolic
1490 links. As with loops containing hard links, the leaf optimisation will
1491 often mean that find knows that it doesn't need to call stat() or
1492 chdir() on the symbolic link, so this diagnostic is frequently not nec‐
1493 essary.
1494 The -d option is supported for compatibility with various BSD systems,
1496 but you should use the POSIX-compliant option -depth instead.
1497 The POSIXLY_CORRECT environment variable does not affect the behaviour
1499 of the -regex or -iregex tests because those tests aren't specified in
1500 the POSIX standard.
1501
1503 LANG Provides a default value for the internationalization variables
1504 that are unset or null.
1505 LC_ALL If set to a non-empty string value, override the values of all
1508 the other internationalization variables.
1509 LC_COLLATE
1512 The POSIX standard specifies that this variable affects the pat‐
1513 tern matching to be used for the -name option. GNU find uses
1514 the fnmatch(3) library function, and so support for LC_COLLATE
1515 depends on the system library. This variable also affects the
1516 interpretation of the response to -ok; while the LC_MESSAGES
1517 variable selects the actual pattern used to interpret the re‐
1518 sponse to -ok, the interpretation of any bracket expressions in
1519 the pattern will be affected by LC_COLLATE.
1520 LC_CTYPE
1523 This variable affects the treatment of character classes used in
1524 regular expressions and also with the -name test, if the sys‐
1525 tem's fnmatch(3) library function supports this. This variable
1526 also affects the interpretation of any character classes in the
1527 regular expressions used to interpret the response to the prompt
1528 issued by -ok. The LC_CTYPE environment variable will also af‐
1529 fect which characters are considered to be unprintable when
1530 filenames are printed; see the section UNUSUAL FILENAMES.
1531 LC_MESSAGES
1534 Determines the locale to be used for internationalised messages.
1535 If the POSIXLY_CORRECT environment variable is set, this also
1536 determines the interpretation of the response to the prompt made
1537 by the -ok action.
1538 NLSPATH
1541 Determines the location of the internationalisation message cat‐
1542 alogues.
1543 PATH Affects the directories which are searched to find the executa‐
1546 bles invoked by -exec, -execdir, -ok and -okdir.
1547 POSIXLY_CORRECT
1550 Determines the block size used by -ls and -fls. If POSIXLY_COR‐
1551 RECT is set, blocks are units of 512 bytes. Otherwise they are
1552 units of 1024 bytes.
1553 Setting this variable also turns off warning messages (that is,
1555 implies -nowarn) by default, because POSIX requires that apart
1556 from the output for -ok, all messages printed on stderr are di‐
1557 agnostics and must result in a non-zero exit status.
1558 When POSIXLY_CORRECT is not set, -perm +zzz is treated just like
1560 -perm /zzz if +zzz is not a valid symbolic mode. When
1561 POSIXLY_CORRECT is set, such constructs are treated as an error.
1562 When POSIXLY_CORRECT is set, the response to the prompt made by
1564 the -ok action is interpreted according to the system's message
1565 catalogue, as opposed to according to find's own message trans‐
1566 lations.
1567 TZ Affects the time zone used for some of the time-related format
1570 directives of -printf and -fprintf.
1571
1573 Simple `find|xargs` approach
1574 • Find files named core in or below the directory /tmp and delete
1575 them.
1576 $ find /tmp -name core -type f -print | xargs /bin/rm -f
1578 Note that this will work incorrectly if there are any filenames
1580 containing newlines, single or double quotes, or spaces.
1581 Safer `find -print0 | xargs -0` approach
1583 • Find files named core in or below the directory /tmp and delete
1584 them, processing filenames in such a way that file or directory
1585 names containing single or double quotes, spaces or newlines are
1586 correctly handled.
1587 $ find /tmp -name core -type f -print0 | xargs -0 /bin/rm -f
1589 The -name test comes before the -type test in order to avoid
1591 having to call stat(2) on every file.
1592 Note that there is still a race between the time find traverses the hi‐
1594 erarchy printing the matching filenames, and the time the process exe‐
1595 cuted by xargs works with that file.
1596 Processing arbitrary starting points
1598 • Given that another program proggy pre-filters and creates a huge
1599 NUL-separated list of files, process those as starting points,
1600 and find all regular, empty files among them:
1601 $ proggy | find -files0-from - -maxdepth 0 -type f -empty
1603 The use of `-files0-from -` means to read the names of the
1605 starting points from standard input, i.e., from the pipe; and
1606 -maxdepth 0 ensures that only explicitly those entries are exam‐
1607 ined without recursing into directories (in the case one of the
1608 starting points is one).
1609 Executing a command for each file
1611 • Run file on every file in or below the current directory.
1612 $ find . -type f -exec file '{}' \;
1614 Notice that the braces are enclosed in single quote marks to
1616 protect them from interpretation as shell script punctuation.
1617 The semicolon is similarly protected by the use of a backslash,
1618 though single quotes could have been used in that case also.
1619 In many cases, one might prefer the `-exec ... +` or better the `-ex‐
1621 ecdir ... +` syntax for performance and security reasons.
1622 Traversing the filesystem just once - for 2 different actions
1624 • Traverse the filesystem just once, listing set-user-ID files and
1625 directories into /root/suid.txt and large files into
1626 /root/big.txt.
1627 $ find / \
1629 \( -perm -4000 -fprintf /root/suid.txt '%#m %u %p\n' \) , \
1630 \( -size +100M -fprintf /root/big.txt '%-10s %p\n' \)
1631 This example uses the line-continuation character '\' on the
1633 first two lines to instruct the shell to continue reading the
1634 command on the next line.
1635 Searching files by age
1637 • Search for files in your home directory which have been modified
1638 in the last twenty-four hours.
1639 $ find $HOME -mtime 0
1641 This command works this way because the time since each file was
1643 last modified is divided by 24 hours and any remainder is dis‐
1644 carded. That means that to match -mtime 0, a file will have to
1645 have a modification in the past which is less than 24 hours ago.
1646 Searching files by permissions
1648 • Search for files which are executable but not readable.
1649 $ find /sbin /usr/sbin -executable \! -readable -print
1651 • Search for files which have read and write permission for their
1654 owner, and group, but which other users can read but not write
1655 to.
1656 $ find . -perm 664
1658 Files which meet these criteria but have other permissions bits
1660 set (for example if someone can execute the file) will not be
1661 matched.
1662 • Search for files which have read and write permission for their
1664 owner and group, and which other users can read, without regard
1665 to the presence of any extra permission bits (for example the
1666 executable bit).
1667 $ find . -perm -664
1669 This will match a file which has mode 0777, for example.
1671 • Search for files which are writable by somebody (their owner, or
1673 their group, or anybody else).
1674 $ find . -perm /222
1676 • Search for files which are writable by either their owner or
1679 their group.
1680 $ find . -perm /220
1682 $ find . -perm /u+w,g+w
1683 $ find . -perm /u=w,g=w
1684 All three of these commands do the same thing, but the first one
1686 uses the octal representation of the file mode, and the other
1687 two use the symbolic form. The files don't have to be writable
1688 by both the owner and group to be matched; either will do.
1689 • Search for files which are writable by both their owner and
1691 their group.
1692 $ find . -perm -220
1694 $ find . -perm -g+w,u+w
1695 Both these commands do the same thing.
1697 • A more elaborate search on permissions.
1699 $ find . -perm -444 -perm /222 \! -perm /111
1701 $ find . -perm -a+r -perm /a+w \! -perm /a+x
1702 These two commands both search for files that are readable for
1704 everybody (-perm -444 or -perm -a+r), have at least one write
1705 bit set (-perm /222 or -perm /a+w) but are not executable for
1706 anybody (! -perm /111 or ! -perm /a+x respectively).
1707 Pruning - omitting files and subdirectories
1709 • Copy the contents of /source-dir to /dest-dir, but omit files
1710 and directories named .snapshot (and anything in them). It also
1711 omits files or directories whose name ends in `~', but not their
1712 contents.
1713 $ cd /source-dir
1715 $ find . -name .snapshot -prune -o \( \! -name '*~' -print0 \) \
1716 | cpio -pmd0 /dest-dir
1717 The construct -prune -o \( ... -print0 \) is quite common. The
1719 idea here is that the expression before -prune matches things
1720 which are to be pruned. However, the -prune action itself re‐
1721 turns true, so the following -o ensures that the right hand side
1722 is evaluated only for those directories which didn't get pruned
1723 (the contents of the pruned directories are not even visited, so
1724 their contents are irrelevant). The expression on the right
1725 hand side of the -o is in parentheses only for clarity. It em‐
1726 phasises that the -print0 action takes place only for things
1727 that didn't have -prune applied to them. Because the default
1728 `and' condition between tests binds more tightly than -o, this
1729 is the default anyway, but the parentheses help to show what is
1730 going on.
1731 • Given the following directory of projects and their associated
1733 SCM administrative directories, perform an efficient search for
1734 the projects' roots:
1735 $ find repo/ \
1737 \( -exec test -d '{}/.svn' \; \
1738 -or -exec test -d '{}/.git' \; \
1739 -or -exec test -d '{}/CVS' \; \
1740 \) -print -prune
1741 Sample output:
1743 repo/project1/CVS
1745 repo/gnu/project2/.svn
1746 repo/gnu/project3/.svn
1747 repo/gnu/project3/src/.svn
1748 repo/project4/.git
1749 In this example, -prune prevents unnecessary descent into direc‐
1751 tories that have already been discovered (for example we do not
1752 search project3/src because we already found project3/.svn), but
1753 ensures sibling directories (project2 and project3) are found.
1754 Other useful examples
1756 • Search for several file types.
1757 $ find /tmp -type f,d,l
1759 Search for files, directories, and symbolic links in the direc‐
1761 tory /tmp passing these types as a comma-separated list (GNU ex‐
1762 tension), which is otherwise equivalent to the longer, yet more
1763 portable:
1764 $ find /tmp \( -type f -o -type d -o -type l \)
1766 • Search for files with the particular name needle and stop imme‐
1769 diately when we find the first one.
1770 $ find / -name needle -print -quit
1772 • Demonstrate the interpretation of the %f and %h format direc‐
1775 tives of the -printf action for some corner-cases. Here is an
1776 example including some output.
1777 $ find . .. / /tmp /tmp/TRACE compile compile/64/tests/find -maxdepth 0 -printf '[%h][%f]\n'
1779 [.][.]
1780 [.][..]
1781 [][/]
1782 [][tmp]
1783 [/tmp][TRACE]
1784 [.][compile]
1785 [compile/64/tests][find]
1786
1789 find exits with status 0 if all files are processed successfully,
1790 greater than 0 if errors occur. This is deliberately a very broad de‐
1791 scription, but if the return value is non-zero, you should not rely on
1792 the correctness of the results of find.
1793 When some error occurs, find may stop immediately, without completing
1795 all the actions specified. For example, some starting points may not
1796 have been examined or some pending program invocations for
1797 -exec ... {} + or -execdir ... {} + may not have been performed.
1798
1800 As of findutils-4.2.2, shell metacharacters (`*', `?' or `[]' for exam‐
1801 ple) used in filename patterns match a leading `.', because IEEE POSIX
1802 interpretation 126 requires this.
1803 As of findutils-4.3.3, -perm /000 now matches all files instead of
1805 none.
1806 Nanosecond-resolution timestamps were implemented in findutils-4.3.3.
1808 As of findutils-4.3.11, the -delete action sets find's exit status to a
1810 nonzero value when it fails. However, find will not exit immediately.
1811 Previously, find's exit status was unaffected by the failure of
1812 -delete.
1813 Feature Added in Also occurs in
1815 -files0-from 4.9.0
1816 -newerXY 4.3.3 BSD
1817 -D 4.3.1
1818 -O 4.3.1
1819 -readable 4.3.0
1820 -writable 4.3.0
1821 -executable 4.3.0
1822 -regextype 4.2.24
1823 -exec ... + 4.2.12 POSIX
1824 -execdir 4.2.12 BSD
1825 -okdir 4.2.12
1826 -samefile 4.2.11
1827 -H 4.2.5 POSIX
1828 -L 4.2.5 POSIX
1829 -P 4.2.5 BSD
1830 -delete 4.2.3
1831 -quit 4.2.3
1832 -d 4.2.3 BSD
1833 -wholename 4.2.0
1834 -iwholename 4.2.0
1835 -ignore_readdir_race 4.2.0
1836 -fls 4.0
1837 -ilname 3.8
1838 -iname 3.8
1839 -ipath 3.8
1840 -iregex 3.8
1841 The syntax -perm +MODE was removed in findutils-4.5.12, in favour of
1843 -perm /MODE. The +MODE syntax had been deprecated since findu‐
1844 tils-4.2.21 which was released in 2005.
1845
1847 Operator precedence surprises
1848 The command find . -name afile -o -name bfile -print will never print
1849 afile because this is actually equivalent to find . -name afile -o \(
1850 -name bfile -a -print \). Remember that the precedence of -a is higher
1851 than that of -o and when there is no operator specified between tests,
1852 -a is assumed.
1853 “paths must precede expression” error message
1855 $ find . -name *.c -print
1856 find: paths must precede expression
1857 find: possible unquoted pattern after predicate `-name'?
1858 This happens when the shell could expand the pattern *.c to more than
1860 one file name existing in the current directory, and passing the re‐
1861 sulting file names in the command line to find like this:
1862 find . -name frcode.c locate.c word_io.c -print
1863 That command is of course not going to work, because the -name predi‐
1864 cate allows exactly only one pattern as argument. Instead of doing
1865 things this way, you should enclose the pattern in quotes or escape the
1866 wildcard, thus allowing find to use the pattern with the wildcard dur‐
1867 ing the search for file name matching instead of file names expanded by
1868 the parent shell:
1869 $ find . -name '*.c' -print
1870 $ find . -name \*.c -print
1871
1873 There are security problems inherent in the behaviour that the POSIX
1874 standard specifies for find, which therefore cannot be fixed. For ex‐
1875 ample, the -exec action is inherently insecure, and -execdir should be
1876 used instead.
1877 The environment variable LC_COLLATE has no effect on the -ok action.
1879
1881 GNU findutils online help: <https://www.gnu.org/software/findu‐
1882 tils/#get-help>
1883 Report any translation bugs to <https://translationproject.org/team/>
1884 Report any other issue via the form at the GNU Savannah bug tracker:
1886 <https://savannah.gnu.org/bugs/?group=findutils>
1887 General topics about the GNU findutils package are discussed at the
1888 bug-findutils mailing list:
1889 <https://lists.gnu.org/mailman/listinfo/bug-findutils>
1890
1892 Copyright © 1990-2022 Free Software Foundation, Inc. License GPLv3+:
1893 GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
1894 This is free software: you are free to change and redistribute it.
1895 There is NO WARRANTY, to the extent permitted by law.
1896
1898 chmod(1), locate(1), ls(1), updatedb(1), xargs(1), lstat(2), stat(2),
1899 ctime(3) fnmatch(3), printf(3), strftime(3), locatedb(5), regex(7)
1900 Full documentation <https://www.gnu.org/software/findutils/find>
1902 or available locally via: info find
1903 FIND(1)