1FIND(1) General Commands Manual FIND(1)
2
3
4
6 find - search for files in a directory hierarchy
7
9 find [-H] [-L] [-P] [-D debugopts] [-Olevel] [starting-point...]
10 [expression]
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
21 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
26 detail 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
39 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 -- can also be used to signal that any remaining arguments are not
44 options (though ensuring that all start points begin with either `./'
45 or `/' is generally safer if you use wildcards in the list of start
46 points).
47
48 -P Never follow symbolic links. This is the default behaviour.
49 When find examines or prints information a file, and the file is
50 a symbolic link, the information used shall be taken from the
51 properties of the symbolic link itself.
52
53
54 -L Follow symbolic links. When find examines or prints information
55 about files, the information used shall be taken from the prop‐
56 erties of the file to which the link points, not from the link
57 itself (unless it is a broken symbolic link or find is unable to
58 examine the file to which the link points). Use of this option
59 implies -noleaf. If you later use the -P option, -noleaf will
60 still be in effect. If -L is in effect and find discovers a
61 symbolic link to a subdirectory during its search, the subdirec‐
62 tory pointed to by the symbolic link will be searched.
63
64 When the -L option is in effect, the -type predicate will always
65 match against the type of the file that a symbolic link points
66 to rather than the link itself (unless the symbolic link is bro‐
67 ken). Actions that can cause symbolic links to become broken
68 while find is executing (for example -delete) can give rise to
69 confusing behaviour. Using -L causes the -lname and -ilname
70 predicates always to return false.
71
72
73 -H Do not follow symbolic links, except while processing the com‐
74 mand line arguments. When find examines or prints information
75 about files, the information used shall be taken from the prop‐
76 erties of the symbolic link itself. The only exception to this
77 behaviour is when a file specified on the command line is a sym‐
78 bolic link, and the link can be resolved. For that situation,
79 the information used is taken from whatever the link points to
80 (that is, the link is followed). The information about the link
81 itself is used as a fallback if the file pointed to by the sym‐
82 bolic link cannot be examined. If -H is in effect and one of
83 the paths specified on the command line is a symbolic link to a
84 directory, the contents of that directory will be examined
85 (though of course -maxdepth 0 would prevent this).
86
87 If more than one of -H, -L and -P is specified, each overrides the oth‐
88 ers; the last one appearing on the command line takes effect. Since it
89 is the default, the -P option should be considered to be in effect
90 unless either -H or -L is specified.
91
92 GNU find frequently stats files during the processing of the command
93 line itself, before any searching has begun. These options also affect
94 how those arguments are processed. Specifically, there are a number of
95 tests that compare files listed on the command line against a file we
96 are currently considering. In each case, the file specified on the
97 command line will have been examined and some of its properties will
98 have been saved. If the named file is in fact a symbolic link, and the
99 -P option is in effect (or if neither -H nor -L were specified), the
100 information used for the comparison will be taken from the properties
101 of the symbolic link. Otherwise, it will be taken from the properties
102 of the file the link points to. If find cannot follow the link (for
103 example because it has insufficient privileges or the link points to a
104 nonexistent file) the properties of the link itself will be used.
105
106 When the -H or -L options are in effect, any symbolic links listed as
107 the argument of -newer will be dereferenced, and the timestamp will be
108 taken from the file to which the symbolic link points. The same con‐
109 sideration applies to -newerXY, -anewer and -cnewer.
110
111 The -follow option has a similar effect to -L, though it takes effect
112 at the point where it appears (that is, if -L is not used but -follow
113 is, any symbolic links appearing after -follow on the command line will
114 be dereferenced, and those before it will not).
115
116
117 -D debugopts
118 Print diagnostic information; this can be helpful to diagnose
119 problems with why find is not doing what you want. The list of
120 debug options should be comma separated. Compatibility of the
121 debug options is not guaranteed between releases of findutils.
122 For a complete list of valid debug options, see the output of
123 find -D help. Valid debug options include
124
125 exec Show diagnostic information relating to -exec, -execdir,
126 -ok and -okdir
127
128 opt Prints diagnostic information relating to the optimisa‐
129 tion of the expression tree; see the -O option.
130
131 rates Prints a summary indicating how often each predicate suc‐
132 ceeded or failed.
133
134 search Navigate the directory tree verbosely.
135
136 stat Print messages as files are examined with the stat and
137 lstat system calls. The find program tries to minimise
138 such calls.
139
140 tree Show the expression tree in its original and optimised
141 form.
142
143 all Enable all of the other debug options (but help).
144
145 help Explain the debugging options.
146
147 -Olevel
148 Enables query optimisation. The find program reorders tests to
149 speed up execution while preserving the overall effect; that is,
150 predicates with side effects are not reordered relative to each
151 other. The optimisations performed at each optimisation level
152 are as follows.
153
154 0 Equivalent to optimisation level 1.
155
156 1 This is the default optimisation level and corresponds to
157 the traditional behaviour. Expressions are reordered so
158 that tests based only on the names of files (for example
159 -name and -regex) are performed first.
160
161 2 Any -type or -xtype tests are performed after any tests
162 based only on the names of files, but before any tests
163 that require information from the inode. On many modern
164 versions of Unix, file types are returned by readdir()
165 and so these predicates are faster to evaluate than pred‐
166 icates which need to stat the file first. If you use the
167 -fstype FOO predicate and specify a filesystem type FOO
168 which is not known (that is, present in `/etc/mtab') at
169 the time find starts, that predicate is equivalent to
170 -false.
171
172 3 At this optimisation level, the full cost-based query
173 optimiser is enabled. The order of tests is modified so
174 that cheap (i.e. fast) tests are performed first and more
175 expensive ones are performed later, if necessary. Within
176 each cost band, predicates are evaluated earlier or later
177 according to whether they are likely to succeed or not.
178 For -o, predicates which are likely to succeed are evalu‐
179 ated earlier, and for -a, predicates which are likely to
180 fail are evaluated earlier.
181
182 The cost-based optimiser has a fixed idea of how likely any
183 given test is to succeed. In some cases the probability takes
184 account of the specific nature of the test (for example, -type f
185 is assumed to be more likely to succeed than -type c). The
186 cost-based optimiser is currently being evaluated. If it does
187 not actually improve the performance of find, it will be removed
188 again. Conversely, optimisations that prove to be reliable,
189 robust and effective may be enabled at lower optimisation levels
190 over time. However, the default behaviour (i.e. optimisation
191 level 1) will not be changed in the 4.3.x release series. The
192 findutils test suite runs all the tests on find at each optimi‐
193 sation level and ensures that the result is the same.
194
196 The part of the command line after the list of starting points is the
197 expression. This is a kind of query specification describing how we
198 match files and what we do with the files that were matched. An
199 expression is composed of a sequence of things:
200
201
202 Tests Tests return a true or false value, usually on the basis of some
203 property of a file we are considering. The -empty test for
204 example is true only when the current file is empty.
205
206
207 Actions
208 Actions have side effects (such as printing something on the
209 standard output) and return either true or false, usually based
210 on whether or not they are successful. The -print action for
211 example prints the name of the current file on the standard out‐
212 put.
213
214
215 Global options
216 Global options affect the operation of tests and actions speci‐
217 fied on any part of the command line. Global options always
218 return true. The -depth option for example makes find traverse
219 the file system in a depth-first order.
220
221
222 Positional options
223 Positional options affect only tests or actions which follow
224 them. Positional options always return true. The -regextype
225 option for example is positional, specifying the regular expres‐
226 sion dialect for regular expressions occurring later on the com‐
227 mand line.
228
229
230 Operators
231 Operators join together the other items within the expression.
232 They include for example -o (meaning logical OR) and -a (meaning
233 logical AND). Where an operator is missing, -a is assumed.
234
235
236 The -print action is performed on all files for which the whole expres‐
237 sion is true, unless it contains an action other than -prune or -quit.
238 Actions which inhibit the default -print are -delete, -exec, -execdir,
239 -ok, -okdir, -fls, -fprint, -fprintf, -ls, -print and -printf.
240
241
242 The -delete action also acts like an option (since it implies -depth).
243
244
245 POSITIONAL OPTIONS
246 Positional options always return true. They affect only tests occur‐
247 ring later on the command line.
248
249
250 -daystart
251 Measure times (for -amin, -atime, -cmin, -ctime, -mmin, and
252 -mtime) from the beginning of today rather than from 24 hours
253 ago. This option only affects tests which appear later on the
254 command line.
255
256
257 -follow
258 Deprecated; use the -L option instead. Dereference symbolic
259 links. Implies -noleaf. The -follow option affects only those
260 tests which appear after it on the command line. Unless the -H
261 or -L option has been specified, the position of the -follow
262 option changes the behaviour of the -newer predicate; any files
263 listed as the argument of -newer will be dereferenced if they
264 are symbolic links. The same consideration applies to -newerXY,
265 -anewer and -cnewer. Similarly, the -type predicate will always
266 match against the type of the file that a symbolic link points
267 to rather than the link itself. Using -follow causes the -lname
268 and -ilname predicates always to return false.
269
270
271 -regextype type
272 Changes the regular expression syntax understood by -regex and
273 -iregex tests which occur later on the command line. To see
274 which regular expression types are known, use -regextype help.
275 The Texinfo documentation (see SEE ALSO) explains the meaning of
276 and differences between the various types of regular expression.
277
278
279 -warn, -nowarn
280 Turn warning messages on or off. These warnings apply only to
281 the command line usage, not to any conditions that find might
282 encounter when it searches directories. The default behaviour
283 corresponds to -warn if standard input is a tty, and to -nowarn
284 otherwise. If a warning message relating to command-line usage
285 is produced, the exit status of find is not affected. If the
286 POSIXLY_CORRECT environment variable is set, and -warn is also
287 used, it is not specified which, if any, warnings will be
288 active.
289
290
291 GLOBAL OPTIONS
292 Global options always return true. Global options take effect even for
293 tests which occur earlier on the command line. To prevent confusion,
294 global options should specified on the command-line after the list of
295 start points, just before the first test, positional option or action.
296 If you specify a global option in some other place, find will issue a
297 warning message explaining that this can be confusing.
298
299 The global options occur after the list of start points, and so are not
300 the same kind of option as -L, for example.
301
302
303 -d A synonym for -depth, for compatibility with FreeBSD, NetBSD,
304 MacOS X and OpenBSD.
305
306
307 -depth Process each directory's contents before the directory itself.
308 The -delete action also implies -depth.
309
310
311 -help, --help
312 Print a summary of the command-line usage of find and exit.
313
314
315 -ignore_readdir_race
316 Normally, find will emit an error message when it fails to stat
317 a file. If you give this option and a file is deleted between
318 the time find reads the name of the file from the directory and
319 the time it tries to stat the file, no error message will be
320 issued. This also applies to files or directories whose names
321 are given on the command line. This option takes effect at the
322 time the command line is read, which means that you cannot
323 search one part of the filesystem with this option on and part
324 of it with this option off (if you need to do that, you will
325 need to issue two find commands instead, one with the option and
326 one without it).
327
328 Furthermore, find with the -ignore_readdir_race option will
329 ignore errors of the -delete action in the case the file has
330 disappeared since the parent directory was read: it will not
331 output an error diagnostic, and the return code of the -delete
332 action will be true.
333
334
335 -maxdepth levels
336 Descend at most levels (a non-negative integer) levels of direc‐
337 tories below the starting-points. -maxdepth 0 means only apply
338 the tests and actions to the starting-points themselves.
339
340
341 -mindepth levels
342 Do not apply any tests or actions at levels less than levels (a
343 non-negative integer). -mindepth 1 means process all files
344 except the starting-points.
345
346
347 -mount Don't descend directories on other filesystems. An alternate
348 name for -xdev, for compatibility with some other versions of
349 find.
350
351
352 -noignore_readdir_race
353 Turns off the effect of -ignore_readdir_race.
354
355
356 -noleaf
357 Do not optimize by assuming that directories contain 2 fewer
358 subdirectories than their hard link count. This option is
359 needed when searching filesystems that do not follow the Unix
360 directory-link convention, such as CD-ROM or MS-DOS filesystems
361 or AFS volume mount points. Each directory on a normal Unix
362 filesystem has at least 2 hard links: its name and its `.'
363 entry. Additionally, its subdirectories (if any) each have a
364 `..' entry linked to that directory. When find is examining a
365 directory, after it has statted 2 fewer subdirectories than the
366 directory's link count, it knows that the rest of the entries in
367 the directory are non-directories (`leaf' files in the directory
368 tree). If only the files' names need to be examined, there is
369 no need to stat them; this gives a significant increase in
370 search speed.
371
372
373 -version, --version
374 Print the find version number and exit.
375
376
377 -xautofs
378 Don't descend directories on autofs filesystems.
379
380
381 -xdev Don't descend directories on other filesystems.
382
383
384 TESTS
385 Some tests, for example -newerXY and -samefile, allow comparison
386 between the file currently being examined and some reference file spec‐
387 ified on the command line. When these tests are used, the interpreta‐
388 tion of the reference file is determined by the options -H, -L and -P
389 and any previous -follow, but the reference file is only examined once,
390 at the time the command line is parsed. If the reference file cannot
391 be examined (for example, the stat(2) system call fails for it), an
392 error message is issued, and find exits with a nonzero status.
393
394 Numeric arguments can be specified as
395
396 +n for greater than n,
397
398 -n for less than n,
399
400 n for exactly n.
401
402 -amin n
403 File was last accessed n minutes ago.
404
405
406 -anewer reference
407 Time of the last access of the current file is more recent than
408 that of the last data modification of the reference file. If
409 reference is a symbolic link and the -H option or the -L option
410 is in effect, then the time of the last data modification of the
411 file it points to is always used.
412
413
414 -atime n
415 File was last accessed n*24 hours ago. When find figures out
416 how many 24-hour periods ago the file was last accessed, any
417 fractional part is ignored, so to match -atime +1, a file has to
418 have been accessed at least two days ago.
419
420
421 -cmin n
422 File's status was last changed n minutes ago.
423
424
425 -cnewer reference
426 Time of the last status change of the current file is more
427 recent than that of the last data modification of the reference
428 file. If reference is a symbolic link and the -H option or the
429 -L option is in effect, then the time of the last data modifica‐
430 tion of the file it points to is always used.
431
432
433 -ctime n
434 File's status was last changed n*24 hours ago. See the comments
435 for -atime to understand how rounding affects the interpretation
436 of file status change times.
437
438
439 -empty File is empty and is either a regular file or a directory.
440
441
442 -executable
443 Matches files which are executable and directories which are
444 searchable (in a file name resolution sense) by the current
445 user. This takes into account access control lists and other
446 permissions artefacts which the -perm test ignores. This test
447 makes use of the access(2) system call, and so can be fooled by
448 NFS servers which do UID mapping (or root-squashing), since many
449 systems implement access(2) in the client's kernel and so cannot
450 make use of the UID mapping information held on the server.
451 Because this test is based only on the result of the access(2)
452 system call, there is no guarantee that a file for which this
453 test succeeds can actually be executed.
454
455
456 -false Always false.
457
458
459 -fstype type
460 File is on a filesystem of type type. The valid filesystem
461 types vary among different versions of Unix; an incomplete list
462 of filesystem types that are accepted on some version of Unix or
463 another is: ufs, 4.2, 4.3, nfs, tmp, mfs, S51K, S52K. You can
464 use -printf with the %F directive to see the types of your
465 filesystems.
466
467
468 -gid n File's numeric group ID is n.
469
470
471 -group gname
472 File belongs to group gname (numeric group ID allowed).
473
474
475 -ilname pattern
476 Like -lname, but the match is case insensitive. If the -L
477 option or the -follow option is in effect, this test returns
478 false unless the symbolic link is broken.
479
480
481
482 -iname pattern
483 Like -name, but the match is case insensitive. For example, the
484 patterns `fo*' and `F??' match the file names `Foo', `FOO',
485 `foo', `fOo', etc. The pattern `*foo*` will also match a file
486 called '.foobar'.
487
488
489 -inum n
490 File has inode number n. It is normally easier to use the
491 -samefile test instead.
492
493
494 -ipath pattern
495 Like -path. but the match is case insensitive.
496
497
498 -iregex pattern
499 Like -regex, but the match is case insensitive.
500
501
502 -iwholename pattern
503 See -ipath. This alternative is less portable than -ipath.
504
505
506 -links n
507 File has n hard links.
508
509
510 -lname pattern
511 File is a symbolic link whose contents match shell pattern pat‐
512 tern. The metacharacters do not treat `/' or `.' specially. If
513 the -L option or the -follow option is in effect, this test
514 returns false unless the symbolic link is broken.
515
516
517 -mmin n
518 File's data was last modified n minutes ago.
519
520
521 -mtime n
522 File's data was last modified n*24 hours ago. See the comments
523 for -atime to understand how rounding affects the interpretation
524 of file modification times.
525
526
527 -name pattern
528 Base of file name (the path with the leading directories
529 removed) matches shell pattern pattern. Because the leading
530 directories are removed, the file names considered for a match
531 with -name will never include a slash, so `-name a/b' will never
532 match anything (you probably need to use -path instead). A
533 warning is issued if you try to do this, unless the environment
534 variable POSIXLY_CORRECT is set. The metacharacters (`*', `?',
535 and `[]') match a `.' at the start of the base name (this is a
536 change in findutils-4.2.2; see section STANDARDS CONFORMANCE
537 below). To ignore a directory and the files under it, use
538 -prune rather than checking every file in the tree; see an exam‐
539 ple in the description of that action. Braces are not recog‐
540 nised as being special, despite the fact that some shells
541 including Bash imbue braces with a special meaning in shell pat‐
542 terns. The filename matching is performed with the use of the
543 fnmatch(3) library function. Don't forget to enclose the pat‐
544 tern in quotes in order to protect it from expansion by the
545 shell.
546
547
548 -newer reference
549 Time of the last data modification of the current file is more
550 recent than that of the last data modification of the reference
551 file. If reference is a symbolic link and the -H option or the
552 -L option is in effect, then the time of the last data modifica‐
553 tion of the file it points to is always used.
554
555
556 -newerXY reference
557 Succeeds if timestamp X of the file being considered is newer
558 than timestamp Y of the file reference. The letters X and Y can
559 be any of the following letters:
560
561
562 a The access time of the file reference
563 B The birth time of the file reference
564 c The inode status change time of reference
565 m The modification time of the file reference
566 t reference is interpreted directly as a time
567
568 Some combinations are invalid; for example, it is invalid for X
569 to be t. Some combinations are not implemented on all systems;
570 for example B is not supported on all systems. If an invalid or
571 unsupported combination of XY is specified, a fatal error
572 results. Time specifications are interpreted as for the argu‐
573 ment to the -d option of GNU date. If you try to use the birth
574 time of a reference file, and the birth time cannot be deter‐
575 mined, a fatal error message results. If you specify a test
576 which refers to the birth time of files being examined, this
577 test will fail for any files where the birth time is unknown.
578
579
580 -nogroup
581 No group corresponds to file's numeric group ID.
582
583
584 -nouser
585 No user corresponds to file's numeric user ID.
586
587
588 -path pattern
589 File name matches shell pattern pattern. The metacharacters do
590 not treat `/' or `.' specially; so, for example,
591 find . -path "./sr*sc"
592 will print an entry for a directory called `./src/misc' (if one
593 exists). To ignore a whole directory tree, use -prune rather
594 than checking every file in the tree. Note that the pattern
595 match test applies to the whole file name, starting from one of
596 the start points named on the command line. It would only make
597 sense to use an absolute path name here if the relevant start
598 point is also an absolute path. This means that this command
599 will never match anything:
600 find bar -path /foo/bar/myfile -print
601 Find compares the -path argument with the concatenation of a
602 directory name and the base name of the file it's examining.
603 Since the concatenation will never end with a slash, -path argu‐
604 ments ending in a slash will match nothing (except perhaps a
605 start point specified on the command line). The predicate -path
606 is also supported by HP-UX find and is part of the POSIX 2008
607 standard.
608
609
610 -perm mode
611 File's permission bits are exactly mode (octal or symbolic).
612 Since an exact match is required, if you want to use this form
613 for symbolic modes, you may have to specify a rather complex
614 mode string. For example `-perm g=w' will only match files
615 which have mode 0020 (that is, ones for which group write per‐
616 mission is the only permission set). It is more likely that you
617 will want to use the `/' or `-' forms, for example `-perm -g=w',
618 which matches any file with group write permission. See the
619 EXAMPLES section for some illustrative examples.
620
621
622 -perm -mode
623 All of the permission bits mode are set for the file. Symbolic
624 modes are accepted in this form, and this is usually the way in
625 which you would want to use them. You must specify `u', `g' or
626 `o' if you use a symbolic mode. See the EXAMPLES section for
627 some illustrative examples.
628
629
630 -perm /mode
631 Any of the permission bits mode are set for the file. Symbolic
632 modes are accepted in this form. You must specify `u', `g' or
633 `o' if you use a symbolic mode. See the EXAMPLES section for
634 some illustrative examples. If no permission bits in mode are
635 set, this test matches any file (the idea here is to be consis‐
636 tent with the behaviour of -perm -000).
637
638
639 -perm +mode
640 This is no longer supported (and has been deprecated since
641 2005). Use -perm /mode instead.
642
643
644 -readable
645 Matches files which are readable by the current user. This
646 takes into account access control lists and other permissions
647 artefacts which the -perm test ignores. This test makes use of
648 the access(2) system call, and so can be fooled by NFS servers
649 which do UID mapping (or root-squashing), since many systems
650 implement access(2) in the client's kernel and so cannot make
651 use of the UID mapping information held on the server.
652
653
654 -regex pattern
655 File name matches regular expression pattern. This is a match
656 on the whole path, not a search. For example, to match a file
657 named `./fubar3', you can use the regular expression `.*bar.' or
658 `.*b.*3', but not `f.*r3'. The regular expressions understood
659 by find are by default Emacs Regular Expressions (except that
660 `.' matches newline), but this can be changed with the -regex‐
661 type option.
662
663
664 -samefile name
665 File refers to the same inode as name. When -L is in effect,
666 this can include symbolic links.
667
668
669 -size n[cwbkMG]
670 File uses n units of space, rounding up. The following suffixes
671 can be used:
672
673 `b' for 512-byte blocks (this is the default if no suffix is
674 used)
675
676 `c' for bytes
677
678 `w' for two-byte words
679
680 `k' for kibibytes (KiB, units of 1024 bytes)
681
682 `M' for mebibytes (MiB, units of 1024 * 1024 = 1048576 bytes)
683
684 `G' for gibibytes (GiB, units of 1024 * 1024 * 1024 =
685 1073741824 bytes)
686
687 The size is simply the st_size member of the struct stat popu‐
688 lated by the lstat (or stat) system call, rounded up as shown
689 above. In other words, it's consistent with the result you get
690 for ls -l. Bear in mind that the `%k' and `%b' format speci‐
691 fiers of -printf handle sparse files differently. The `b' suf‐
692 fix always denotes 512-byte blocks and never 1024-byte blocks,
693 which is different to the behaviour of -ls.
694
695 The + and - prefixes signify greater than and less than, as
696 usual; i.e., an exact size of n units does not match. Bear in
697 mind that the size is rounded up to the next unit. Therefore
698 -size -1M is not equivalent to -size -1048576c. The former only
699 matches empty files, the latter matches files from 0 to
700 1,048,575 bytes.
701
702 -true Always true.
703
704
705 -type c
706 File is of type c:
707
708 b block (buffered) special
709
710 c character (unbuffered) special
711
712 d directory
713
714 p named pipe (FIFO)
715
716 f regular file
717
718 l symbolic link; this is never true if the -L option or the
719 -follow option is in effect, unless the symbolic link is
720 broken. If you want to search for symbolic links when -L
721 is in effect, use -xtype.
722
723 s socket
724
725 D door (Solaris)
726
727 To search for more than one type at once, you can supply the
728 combined list of type letters separated by a comma `,' (GNU
729 extension).
730
731 -uid n File's numeric user ID is n.
732
733
734 -used n
735 File was last accessed n days after its status was last changed.
736
737
738 -user uname
739 File is owned by user uname (numeric user ID allowed).
740
741
742 -wholename pattern
743 See -path. This alternative is less portable than -path.
744
745
746 -writable
747 Matches files which are writable by the current user. This
748 takes into account access control lists and other permissions
749 artefacts which the -perm test ignores. This test makes use of
750 the access(2) system call, and so can be fooled by NFS servers
751 which do UID mapping (or root-squashing), since many systems
752 implement access(2) in the client's kernel and so cannot make
753 use of the UID mapping information held on the server.
754
755
756 -xtype c
757 The same as -type unless the file is a symbolic link. For sym‐
758 bolic links: if the -H or -P option was specified, true if the
759 file is a link to a file of type c; if the -L option has been
760 given, true if c is `l'. In other words, for symbolic links,
761 -xtype checks the type of the file that -type does not check.
762
763 -context pattern
764 (SELinux only) Security context of the file matches glob pat‐
765 tern.
766
767
768 ACTIONS
769 -delete
770 Delete files; true if removal succeeded. If the removal failed,
771 an error message is issued. If -delete fails, find's exit sta‐
772 tus will be nonzero (when it eventually exits). Use of -delete
773 automatically turns on the `-depth' option.
774
775 Warnings: Don't forget that the find command line is evaluated
776 as an expression, so putting -delete first will make find try to
777 delete everything below the starting points you specified. When
778 testing a find command line that you later intend to use with
779 -delete, you should explicitly specify -depth in order to avoid
780 later surprises. Because -delete implies -depth, you cannot
781 usefully use -prune and -delete together.
782
783 Together with the -ignore_readdir_race option, find will ignore
784 errors of the -delete action in the case the file has disap‐
785 peared since the parent directory was read: it will not output
786 an error diagnostic, and the return code of the -delete action
787 will be true.
788
789
790 -exec command ;
791 Execute command; true if 0 status is returned. All following
792 arguments to find are taken to be arguments to the command until
793 an argument consisting of `;' is encountered. The string `{}'
794 is replaced by the current file name being processed everywhere
795 it occurs in the arguments to the command, not just in arguments
796 where it is alone, as in some versions of find. Both of these
797 constructions might need to be escaped (with a `\') or quoted to
798 protect them from expansion by the shell. See the EXAMPLES sec‐
799 tion for examples of the use of the -exec option. The specified
800 command is run once for each matched file. The command is exe‐
801 cuted in the starting directory. There are unavoidable security
802 problems surrounding use of the -exec action; you should use the
803 -execdir option instead.
804
805
806 -exec command {} +
807 This variant of the -exec action runs the specified command on
808 the selected files, but the command line is built by appending
809 each selected file name at the end; the total number of invoca‐
810 tions of the command will be much less than the number of
811 matched files. The command line is built in much the same way
812 that xargs builds its command lines. Only one instance of `{}'
813 is allowed within the command, and (when find is being invoked
814 from a shell) it should be quoted (for example, '{}') to protect
815 it from interpretation by shells. The command is executed in
816 the starting directory. If any invocation with the `+' form
817 returns a non-zero value as exit status, then find returns a
818 non-zero exit status. If find encounters an error, this can
819 sometimes cause an immediate exit, so some pending commands may
820 not be run at all. This variant of -exec always returns true.
821
822
823 -execdir command ;
824
825 -execdir command {} +
826 Like -exec, but the specified command is run from the subdirec‐
827 tory containing the matched file, which is not normally the
828 directory in which you started find. As with -exec, the {}
829 should be quoted if find is being invoked from a shell. This a
830 much more secure method for invoking commands, as it avoids race
831 conditions during resolution of the paths to the matched files.
832 As with the -exec action, the `+' form of -execdir will build a
833 command line to process more than one matched file, but any
834 given invocation of command will only list files that exist in
835 the same subdirectory. If you use this option, you must ensure
836 that your $PATH environment variable does not reference `.';
837 otherwise, an attacker can run any commands they like by leaving
838 an appropriately-named file in a directory in which you will run
839 -execdir. The same applies to having entries in $PATH which are
840 empty or which are not absolute directory names. If any invoca‐
841 tion with the `+' form returns a non-zero value as exit status,
842 then find returns a non-zero exit status. If find encounters an
843 error, this can sometimes cause an immediate exit, so some pend‐
844 ing commands may not be run at all. The result of the action
845 depends on whether the + or the ; variant is being used;
846 -execdir command {} + always returns true, while -execdir com‐
847 mand {} ; returns true only if command returns 0.
848
849
850
851 -fls file
852 True; like -ls but write to file like -fprint. The output file
853 is always created, even if the predicate is never matched. See
854 the UNUSUAL FILENAMES section for information about how unusual
855 characters in filenames are handled.
856
857
858 -fprint file
859 True; print the full file name into file file. If file does not
860 exist when find is run, it is created; if it does exist, it is
861 truncated. The file names `/dev/stdout' and `/dev/stderr' are
862 handled specially; they refer to the standard output and stan‐
863 dard error output, respectively. The output file is always cre‐
864 ated, even if the predicate is never matched. See the UNUSUAL
865 FILENAMES section for information about how unusual characters
866 in filenames are handled.
867
868
869 -fprint0 file
870 True; like -print0 but write to file like -fprint. The output
871 file is always created, even if the predicate is never matched.
872 See the UNUSUAL FILENAMES section for information about how
873 unusual characters in filenames are handled.
874
875
876 -fprintf file format
877 True; like -printf but write to file like -fprint. The output
878 file is always created, even if the predicate is never matched.
879 See the UNUSUAL FILENAMES section for information about how
880 unusual characters in filenames are handled.
881
882
883 -ls True; list current file in ls -dils format on standard output.
884 The block counts are of 1 KB blocks, unless the environment
885 variable POSIXLY_CORRECT is set, in which case 512-byte blocks
886 are used. See the UNUSUAL FILENAMES section for information
887 about how unusual characters in filenames are handled.
888
889
890 -ok command ;
891 Like -exec but ask the user first. If the user agrees, run the
892 command. Otherwise just return false. If the command is run,
893 its standard input is redirected from /dev/null.
894
895
896 The response to the prompt is matched against a pair of regular
897 expressions to determine if it is an affirmative or negative
898 response. This regular expression is obtained from the system
899 if the `POSIXLY_CORRECT' environment variable is set, or other‐
900 wise from find's message translations. If the system has no
901 suitable definition, find's own definition will be used. In
902 either case, the interpretation of the regular expression itself
903 will be affected by the environment variables 'LC_CTYPE' (char‐
904 acter classes) and 'LC_COLLATE' (character ranges and equiva‐
905 lence classes).
906
907
908
909
910 -okdir command ;
911 Like -execdir but ask the user first in the same way as for -ok.
912 If the user does not agree, just return false. If the command
913 is run, its standard input is redirected from /dev/null.
914
915
916 -print True; print the full file name on the standard output, followed
917 by a newline. If you are piping the output of find into another
918 program and there is the faintest possibility that the files
919 which you are searching for might contain a newline, then you
920 should seriously consider using the -print0 option instead of
921 -print. See the UNUSUAL FILENAMES section for information about
922 how unusual characters in filenames are handled.
923
924
925 -print0
926 True; print the full file name on the standard output, followed
927 by a null character (instead of the newline character that
928 -print uses). This allows file names that contain newlines or
929 other types of white space to be correctly interpreted by pro‐
930 grams that process the find output. This option corresponds to
931 the -0 option of xargs.
932
933
934 -printf format
935 True; print format on the standard output, interpreting `\'
936 escapes and `%' directives. Field widths and precisions can be
937 specified as with the `printf' C function. Please note that
938 many of the fields are printed as %s rather than %d, and this
939 may mean that flags don't work as you might expect. This also
940 means that the `-' flag does work (it forces fields to be left-
941 aligned). Unlike -print, -printf does not add a newline at the
942 end of the string. The escapes and directives are:
943
944 \a Alarm bell.
945
946 \b Backspace.
947
948 \c Stop printing from this format immediately and flush the
949 output.
950
951 \f Form feed.
952
953 \n Newline.
954
955 \r Carriage return.
956
957 \t Horizontal tab.
958
959 \v Vertical tab.
960
961 \0 ASCII NUL.
962
963 \\ A literal backslash (`\').
964
965 \NNN The character whose ASCII code is NNN (octal).
966
967 A `\' character followed by any other character is treated as an
968 ordinary character, so they both are printed.
969
970 %% A literal percent sign.
971
972 %a File's last access time in the format returned by the C
973 `ctime' function.
974
975 %Ak File's last access time in the format specified by k,
976 which is either `@' or a directive for the C `strftime'
977 function. The possible values for k are listed below;
978 some of them might not be available on all systems, due
979 to differences in `strftime' between systems.
980
981 @ seconds since Jan. 1, 1970, 00:00 GMT, with frac‐
982 tional part.
983
984 Time fields:
985
986 H hour (00..23)
987
988 I hour (01..12)
989
990 k hour ( 0..23)
991
992 l hour ( 1..12)
993
994 M minute (00..59)
995
996 p locale's AM or PM
997
998 r time, 12-hour (hh:mm:ss [AP]M)
999
1000 S Second (00.00 .. 61.00). There is a fractional
1001 part.
1002
1003 T time, 24-hour (hh:mm:ss.xxxxxxxxxx)
1004
1005 + Date and time, separated by `+', for example
1006 `2004-04-28+22:22:05.0'. This is a GNU extension.
1007 The time is given in the current timezone (which
1008 may be affected by setting the TZ environment
1009 variable). The seconds field includes a frac‐
1010 tional part.
1011
1012 X locale's time representation (H:M:S). The seconds
1013 field includes a fractional part.
1014
1015 Z time zone (e.g., EDT), or nothing if no time zone
1016 is determinable
1017
1018 Date fields:
1019
1020 a locale's abbreviated weekday name (Sun..Sat)
1021
1022 A locale's full weekday name, variable length (Sun‐
1023 day..Saturday)
1024
1025 b locale's abbreviated month name (Jan..Dec)
1026
1027 B locale's full month name, variable length (Janu‐
1028 ary..December)
1029
1030 c locale's date and time (Sat Nov 04 12:02:33 EST
1031 1989). The format is the same as for ctime(3) and
1032 so to preserve compatibility with that format,
1033 there is no fractional part in the seconds field.
1034
1035 d day of month (01..31)
1036
1037 D date (mm/dd/yy)
1038
1039 h same as b
1040
1041 j day of year (001..366)
1042
1043 m month (01..12)
1044
1045 U week number of year with Sunday as first day of
1046 week (00..53)
1047
1048 w day of week (0..6)
1049
1050 W week number of year with Monday as first day of
1051 week (00..53)
1052
1053 x locale's date representation (mm/dd/yy)
1054
1055 y last two digits of year (00..99)
1056
1057 Y year (1970...)
1058
1059 %b The amount of disk space used for this file in 512-byte
1060 blocks. Since disk space is allocated in multiples of
1061 the filesystem block size this is usually greater than
1062 %s/512, but it can also be smaller if the file is a
1063 sparse file.
1064
1065 %c File's last status change time in the format returned by
1066 the C `ctime' function.
1067
1068 %Ck File's last status change time in the format specified by
1069 k, which is the same as for %A.
1070
1071 %d File's depth in the directory tree; 0 means the file is a
1072 starting-point.
1073
1074 %D The device number on which the file exists (the st_dev
1075 field of struct stat), in decimal.
1076
1077 %f File's name with any leading directories removed (only
1078 the last element).
1079
1080 %F Type of the filesystem the file is on; this value can be
1081 used for -fstype.
1082
1083 %g File's group name, or numeric group ID if the group has
1084 no name.
1085
1086 %G File's numeric group ID.
1087
1088 %h Leading directories of file's name (all but the last ele‐
1089 ment). If the file name contains no slashes (since it is
1090 in the current directory) the %h specifier expands to
1091 `.'.
1092
1093 %H Starting-point under which file was found.
1094
1095 %i File's inode number (in decimal).
1096
1097 %k The amount of disk space used for this file in 1 KB
1098 blocks. Since disk space is allocated in multiples of
1099 the filesystem block size this is usually greater than
1100 %s/1024, but it can also be smaller if the file is a
1101 sparse file.
1102
1103 %l Object of symbolic link (empty string if file is not a
1104 symbolic link).
1105
1106 %m File's permission bits (in octal). This option uses the
1107 `traditional' numbers which most Unix implementations
1108 use, but if your particular implementation uses an
1109 unusual ordering of octal permissions bits, you will see
1110 a difference between the actual value of the file's mode
1111 and the output of %m. Normally you will want to have a
1112 leading zero on this number, and to do this, you should
1113 use the # flag (as in, for example, `%#m').
1114
1115 %M File's permissions (in symbolic form, as for ls). This
1116 directive is supported in findutils 4.2.5 and later.
1117
1118 %n Number of hard links to file.
1119
1120 %p File's name.
1121
1122 %P File's name with the name of the starting-point under
1123 which it was found removed.
1124
1125 %s File's size in bytes.
1126
1127 %S File's sparseness. This is calculated as (BLOCK‐
1128 SIZE*st_blocks / st_size). The exact value you will get
1129 for an ordinary file of a certain length is system-depen‐
1130 dent. However, normally sparse files will have values
1131 less than 1.0, and files which use indirect blocks may
1132 have a value which is greater than 1.0. In general the
1133 number of blocks used by a file is file system dependent.
1134 The value used for BLOCKSIZE is system-dependent, but is
1135 usually 512 bytes. If the file size is zero, the value
1136 printed is undefined. On systems which lack support for
1137 st_blocks, a file's sparseness is assumed to be 1.0.
1138
1139 %t File's last modification time in the format returned by
1140 the C `ctime' function.
1141
1142 %Tk File's last modification time in the format specified by
1143 k, which is the same as for %A.
1144
1145 %u File's user name, or numeric user ID if the user has no
1146 name.
1147
1148 %U File's numeric user ID.
1149
1150 %y File's type (like in ls -l), U=unknown type (shouldn't
1151 happen)
1152
1153 %Y File's type (like %y), plus follow symlinks: `L'=loop,
1154 `N'=nonexistent, `?' for any other error when determining
1155 the type of the symlink target.
1156
1157 %Z (SELinux only) file's security context.
1158
1159 %{ %[ %(
1160 Reserved for future use.
1161
1162 A `%' character followed by any other character is discarded,
1163 but the other character is printed (don't rely on this, as fur‐
1164 ther format characters may be introduced). A `%' at the end of
1165 the format argument causes undefined behaviour since there is no
1166 following character. In some locales, it may hide your door
1167 keys, while in others it may remove the final page from the
1168 novel you are reading.
1169
1170 The %m and %d directives support the # , 0 and + flags, but the
1171 other directives do not, even if they print numbers. Numeric
1172 directives that do not support these flags include G, U, b, D, k
1173 and n. The `-' format flag is supported and changes the align‐
1174 ment of a field from right-justified (which is the default) to
1175 left-justified.
1176
1177 See the UNUSUAL FILENAMES section for information about how
1178 unusual characters in filenames are handled.
1179
1180
1181
1182 -prune True; if the file is a directory, do not descend into it. If
1183 -depth is given, then -prune has no effect. Because -delete
1184 implies -depth, you cannot usefully use -prune and -delete
1185 together.
1186 For example, to skip the directory `src/emacs' and all files
1187 and directories under it, and print the names of the other files
1188 found, do something like this:
1189 find . -path ./src/emacs -prune -o -print
1190
1191
1192
1193 -quit Exit immediately. No child processes will be left running, but
1194 no more paths specified on the command line will be processed.
1195 For example, find /tmp/foo /tmp/bar -print -quit will print only
1196 /tmp/foo. Any command lines which have been built up with
1197 -execdir ... {} + will be invoked before find exits. The exit
1198 status may or may not be zero, depending on whether an error has
1199 already occurred.
1200
1201
1202 OPERATORS
1203 Listed in order of decreasing precedence:
1204
1205
1206 ( expr )
1207 Force precedence. Since parentheses are special to the shell,
1208 you will normally need to quote them. Many of the examples in
1209 this manual page use backslashes for this purpose: `\(...\)'
1210 instead of `(...)'.
1211
1212
1213 ! expr True if expr is false. This character will also usually need
1214 protection from interpretation by the shell.
1215
1216
1217 -not expr
1218 Same as ! expr, but not POSIX compliant.
1219
1220
1221 expr1 expr2
1222 Two expressions in a row are taken to be joined with an implied
1223 -a; expr2 is not evaluated if expr1 is false.
1224
1225
1226 expr1 -a expr2
1227 Same as expr1 expr2.
1228
1229
1230 expr1 -and expr2
1231 Same as expr1 expr2, but not POSIX compliant.
1232
1233
1234 expr1 -o expr2
1235 Or; expr2 is not evaluated if expr1 is true.
1236
1237
1238 expr1 -or expr2
1239 Same as expr1 -o expr2, but not POSIX compliant.
1240
1241
1242 expr1 , expr2
1243 List; both expr1 and expr2 are always evaluated. The value of
1244 expr1 is discarded; the value of the list is the value of expr2.
1245 The comma operator can be useful for searching for several dif‐
1246 ferent types of thing, but traversing the filesystem hierarchy
1247 only once. The -fprintf action can be used to list the various
1248 matched items into several different output files.
1249
1250 Please note that -a when specified implicitly (for example by two tests
1251 appearing without an explicit operator between them) or explicitly has
1252 higher precedence than -o. This means that find . -name afile -o -name
1253 bfile -print will never print afile.
1254
1255
1256
1258 Many of the actions of find result in the printing of data which is
1259 under the control of other users. This includes file names, sizes,
1260 modification times and so forth. File names are a potential problem
1261 since they can contain any character except `\0' and `/'. Unusual
1262 characters in file names can do unexpected and often undesirable things
1263 to your terminal (for example, changing the settings of your function
1264 keys on some terminals). Unusual characters are handled differently by
1265 various actions, as described below.
1266
1267
1268 -print0, -fprint0
1269 Always print the exact filename, unchanged, even if the output
1270 is going to a terminal.
1271
1272
1273 -ls, -fls
1274 Unusual characters are always escaped. White space, backslash,
1275 and double quote characters are printed using C-style escaping
1276 (for example `\f', `\"'). Other unusual characters are printed
1277 using an octal escape. Other printable characters (for -ls and
1278 -fls these are the characters between octal 041 and 0176) are
1279 printed as-is.
1280
1281
1282 -printf, -fprintf
1283 If the output is not going to a terminal, it is printed as-is.
1284 Otherwise, the result depends on which directive is in use. The
1285 directives %D, %F, %g, %G, %H, %Y, and %y expand to values which
1286 are not under control of files' owners, and so are printed as-
1287 is. The directives %a, %b, %c, %d, %i, %k, %m, %M, %n, %s, %t,
1288 %u and %U have values which are under the control of files' own‐
1289 ers but which cannot be used to send arbitrary data to the ter‐
1290 minal, and so these are printed as-is. The directives %f, %h,
1291 %l, %p and %P are quoted. This quoting is performed in the same
1292 way as for GNU ls. This is not the same quoting mechanism as
1293 the one used for -ls and -fls. If you are able to decide what
1294 format to use for the output of find then it is normally better
1295 to use `\0' as a terminator than to use newline, as file names
1296 can contain white space and newline characters. The setting of
1297 the `LC_CTYPE' environment variable is used to determine which
1298 characters need to be quoted.
1299
1300
1301 -print, -fprint
1302 Quoting is handled in the same way as for -printf and -fprintf.
1303 If you are using find in a script or in a situation where the
1304 matched files might have arbitrary names, you should consider
1305 using -print0 instead of -print.
1306
1307 The -ok and -okdir actions print the current filename as-is. This may
1308 change in a future release.
1309
1310
1312 For closest compliance to the POSIX standard, you should set the
1313 POSIXLY_CORRECT environment variable. The following options are speci‐
1314 fied in the POSIX standard (IEEE Std 1003.1-2008, 2016 Edition):
1315
1316
1317 -H This option is supported.
1318
1319
1320 -L This option is supported.
1321
1322
1323 -name This option is supported, but POSIX conformance depends on the
1324 POSIX conformance of the system's fnmatch(3) library function.
1325 As of findutils-4.2.2, shell metacharacters (`*', `?' or `[]'
1326 for example) will match a leading `.', because IEEE PASC inter‐
1327 pretation 126 requires this. This is a change from previous
1328 versions of findutils.
1329
1330
1331 -type Supported. POSIX specifies `b', `c', `d', `l', `p', `f' and
1332 `s'. GNU find also supports `D', representing a Door, where the
1333 OS provides these. Furthermore, GNU find allows multiple types
1334 to be specified at once in a comma-separated list.
1335
1336
1337 -ok Supported. Interpretation of the response is according to the
1338 `yes' and `no' patterns selected by setting the `LC_MESSAGES'
1339 environment variable. When the `POSIXLY_CORRECT' environment
1340 variable is set, these patterns are taken system's definition of
1341 a positive (yes) or negative (no) response. See the system's
1342 documentation for nl_langinfo(3), in particular YESEXPR and
1343 NOEXPR. When `POSIXLY_CORRECT' is not set, the patterns are
1344 instead taken from find's own message catalogue.
1345
1346
1347 -newer Supported. If the file specified is a symbolic link, it is
1348 always dereferenced. This is a change from previous behaviour,
1349 which used to take the relevant time from the symbolic link; see
1350 the HISTORY section below.
1351
1352
1353 -perm Supported. If the POSIXLY_CORRECT environment variable is not
1354 set, some mode arguments (for example +a+x) which are not valid
1355 in POSIX are supported for backward-compatibility.
1356
1357
1358 Other primaries
1359 The primaries -atime, -ctime, -depth, -exec, -group, -links,
1360 -mtime, -nogroup, -nouser, -ok, -path, -print, -prune, -size,
1361 -user and -xdev are all supported.
1362
1363
1364 The POSIX standard specifies parentheses `(', `)', negation `!' and the
1365 `and' and `or' operators ( -a, -o).
1366
1367 All other options, predicates, expressions and so forth are extensions
1368 beyond the POSIX standard. Many of these extensions are not unique to
1369 GNU find, however.
1370
1371 The POSIX standard requires that find detects loops:
1372
1373 The find utility shall detect infinite loops; that is, entering
1374 a previously visited directory that is an ancestor of the last
1375 file encountered. When it detects an infinite loop, find shall
1376 write a diagnostic message to standard error and shall either
1377 recover its position in the hierarchy or terminate.
1378
1379 GNU find complies with these requirements. The link count of directo‐
1380 ries which contain entries which are hard links to an ancestor will
1381 often be lower than they otherwise should be. This can mean that GNU
1382 find will sometimes optimise away the visiting of a subdirectory which
1383 is actually a link to an ancestor. Since find does not actually enter
1384 such a subdirectory, it is allowed to avoid emitting a diagnostic mes‐
1385 sage. Although this behaviour may be somewhat confusing, it is
1386 unlikely that anybody actually depends on this behaviour. If the leaf
1387 optimisation has been turned off with -noleaf, the directory entry will
1388 always be examined and the diagnostic message will be issued where it
1389 is appropriate. Symbolic links cannot be used to create filesystem
1390 cycles as such, but if the -L option or the -follow option is in use, a
1391 diagnostic message is issued when find encounters a loop of symbolic
1392 links. As with loops containing hard links, the leaf optimisation will
1393 often mean that find knows that it doesn't need to call stat() or
1394 chdir() on the symbolic link, so this diagnostic is frequently not nec‐
1395 essary.
1396
1397 The -d option is supported for compatibility with various BSD systems,
1398 but you should use the POSIX-compliant option -depth instead.
1399
1400 The POSIXLY_CORRECT environment variable does not affect the behaviour
1401 of the -regex or -iregex tests because those tests aren't specified in
1402 the POSIX standard.
1403
1405 LANG Provides a default value for the internationalization variables
1406 that are unset or null.
1407
1408
1409 LC_ALL If set to a non-empty string value, override the values of all
1410 the other internationalization variables.
1411
1412
1413 LC_COLLATE
1414 The POSIX standard specifies that this variable affects the pat‐
1415 tern matching to be used for the -name option. GNU find uses
1416 the fnmatch(3) library function, and so support for `LC_COLLATE'
1417 depends on the system library. This variable also affects the
1418 interpretation of the response to -ok; while the `LC_MESSAGES'
1419 variable selects the actual pattern used to interpret the
1420 response to -ok, the interpretation of any bracket expressions
1421 in the pattern will be affected by `LC_COLLATE'.
1422
1423
1424 LC_CTYPE
1425 This variable affects the treatment of character classes used in
1426 regular expressions and also with the -name test, if the sys‐
1427 tem's fnmatch(3) library function supports this. This variable
1428 also affects the interpretation of any character classes in the
1429 regular expressions used to interpret the response to the prompt
1430 issued by -ok. The `LC_CTYPE' environment variable will also
1431 affect which characters are considered to be unprintable when
1432 filenames are printed; see the section UNUSUAL FILENAMES.
1433
1434
1435 LC_MESSAGES
1436 Determines the locale to be used for internationalised messages.
1437 If the `POSIXLY_CORRECT' environment variable is set, this also
1438 determines the interpretation of the response to the prompt made
1439 by the -ok action.
1440
1441
1442 NLSPATH
1443 Determines the location of the internationalisation message cat‐
1444 alogues.
1445
1446
1447 PATH Affects the directories which are searched to find the executa‐
1448 bles invoked by -exec, -execdir, -ok and -okdir.
1449
1450
1451 POSIXLY_CORRECT
1452 Determines the block size used by -ls and -fls. If POSIXLY_COR‐
1453 RECT is set, blocks are units of 512 bytes. Otherwise they are
1454 units of 1024 bytes.
1455
1456 Setting this variable also turns off warning messages (that is,
1457 implies -nowarn) by default, because POSIX requires that apart
1458 from the output for -ok, all messages printed on stderr are
1459 diagnostics and must result in a non-zero exit status.
1460
1461 When POSIXLY_CORRECT is not set, -perm +zzz is treated just like
1462 -perm /zzz if +zzz is not a valid symbolic mode. When
1463 POSIXLY_CORRECT is set, such constructs are treated as an error.
1464
1465 When POSIXLY_CORRECT is set, the response to the prompt made by
1466 the -ok action is interpreted according to the system's message
1467 catalogue, as opposed to according to find's own message trans‐
1468 lations.
1469
1470
1471 TZ Affects the time zone used for some of the time-related format
1472 directives of -printf and -fprintf.
1473
1475 find /tmp -name core -type f -print | xargs /bin/rm -f
1476
1477 Find files named core in or below the directory /tmp and delete them.
1478 Note that this will work incorrectly if there are any filenames con‐
1479 taining newlines, single or double quotes, or spaces.
1480
1481 find /tmp -name core -type f -print0 | xargs -0 /bin/rm -f
1482
1483 Find files named core in or below the directory /tmp and delete them,
1484 processing filenames in such a way that file or directory names con‐
1485 taining single or double quotes, spaces or newlines are correctly han‐
1486 dled. The -name test comes before the -type test in order to avoid
1487 having to call stat(2) on every file.
1488
1489
1490 find . -type f -exec file '{}' \;
1491
1492 Runs `file' on every file in or below the current directory. Notice
1493 that the braces are enclosed in single quote marks to protect them from
1494 interpretation as shell script punctuation. The semicolon is similarly
1495 protected by the use of a backslash, though single quotes could have
1496 been used in that case also.
1497
1498
1499 find / \( -perm -4000 -fprintf /root/suid.txt '%#m %u %p\n' \) , \
1500 \( -size +100M -fprintf /root/big.txt '%-10s %p\n' \)
1501
1502 Traverse the filesystem just once, listing setuid files and directories
1503 into /root/suid.txt and large files into /root/big.txt.
1504
1505
1506 find $HOME -mtime 0
1507
1508 Search for files in your home directory which have been modified in the
1509 last twenty-four hours. This command works this way because the time
1510 since each file was last modified is divided by 24 hours and any
1511 remainder is discarded. That means that to match -mtime 0, a file will
1512 have to have a modification in the past which is less than 24 hours
1513 ago.
1514
1515
1516 find /sbin /usr/sbin -executable \! -readable -print
1517
1518 Search for files which are executable but not readable.
1519
1520
1521 find . -perm 664
1522
1523 Search for files which have read and write permission for their owner,
1524 and group, but which other users can read but not write to. Files
1525 which meet these criteria but have other permissions bits set (for
1526 example if someone can execute the file) will not be matched.
1527
1528
1529 find . -perm -664
1530
1531 Search for files which have read and write permission for their owner
1532 and group, and which other users can read, without regard to the pres‐
1533 ence of any extra permission bits (for example the executable bit).
1534 This will match a file which has mode 0777, for example.
1535
1536
1537 find . -perm /222
1538
1539 Search for files which are writable by somebody (their owner, or their
1540 group, or anybody else).
1541
1542
1543 find . -perm /220
1544 find . -perm /u+w,g+w
1545 find . -perm /u=w,g=w
1546
1547 All three of these commands do the same thing, but the first one uses
1548 the octal representation of the file mode, and the other two use the
1549 symbolic form. These commands all search for files which are writable
1550 by either their owner or their group. The files don't have to be
1551 writable by both the owner and group to be matched; either will do.
1552
1553
1554 find . -perm -220
1555 find . -perm -g+w,u+w
1556
1557 Both these commands do the same thing; search for files which are
1558 writable by both their owner and their group.
1559
1560
1561 find . -perm -444 -perm /222 \! -perm /111
1562 find . -perm -a+r -perm /a+w \! -perm /a+x
1563
1564 These two commands both search for files that are readable for every‐
1565 body ( -perm -444 or -perm -a+r), have at least one write bit set (
1566 -perm /222 or -perm /a+w) but are not executable for anybody ( ! -perm
1567 /111 and ! -perm /a+x respectively).
1568
1569
1570 cd /source-dir
1571 find . -name .snapshot -prune -o \( \! -name '*~' -print0 \)|
1572 cpio -pmd0 /dest-dir
1573
1574 This command copies the contents of /source-dir to /dest-dir, but omits
1575 files and directories named .snapshot (and anything in them). It also
1576 omits files or directories whose name ends in ~, but not their con‐
1577 tents. The construct -prune -o \( ... -print0 \) is quite common. The
1578 idea here is that the expression before -prune matches things which are
1579 to be pruned. However, the -prune action itself returns true, so the
1580 following -o ensures that the right hand side is evaluated only for
1581 those directories which didn't get pruned (the contents of the pruned
1582 directories are not even visited, so their contents are irrelevant).
1583 The expression on the right hand side of the -o is in parentheses only
1584 for clarity. It emphasises that the -print0 action takes place only
1585 for things that didn't have -prune applied to them. Because the
1586 default `and' condition between tests binds more tightly than -o, this
1587 is the default anyway, but the parentheses help to show what is going
1588 on.
1589
1590
1591 find repo/ \( -exec test -d '{}'/.svn \; -or \
1592 -exec test -d {}/.git \; -or -exec test -d {}/CVS \; \) \
1593 -print -prune
1594
1595 Given the following directory of projects and their associated SCM
1596 administrative directories, perform an efficient search for the
1597 projects' roots:
1598
1599 repo/project1/CVS
1600 repo/gnu/project2/.svn
1601 repo/gnu/project3/.svn
1602 repo/gnu/project3/src/.svn
1603 repo/project4/.git
1604
1605 In this example, -prune prevents unnecessary descent into directories
1606 that have already been discovered (for example we do not search
1607 project3/src because we already found project3/.svn), but ensures sib‐
1608 ling directories (project2 and project3) are found.
1609
1610
1611 find /tmp -type f,d,l
1612
1613 Search for files, directories, and symbolic links in the directory /tmp
1614 passing these types as a comma-separated list (GNU extension), which is
1615 otherwise equivalent to the longer, yet more portable:
1616
1617 find /tmp \( -type f -o -type d -o -type l \)
1618
1619
1621 find exits with status 0 if all files are processed successfully,
1622 greater than 0 if errors occur. This is deliberately a very broad
1623 description, but if the return value is non-zero, you should not rely
1624 on the correctness of the results of find.
1625
1626 When some error occurs, find may stop immediately, without completing
1627 all the actions specified. For example, some starting points may not
1628 have been examined or some pending program invocations for -exec ... {}
1629 + or -execdir ... {} + may not have been performed.
1630
1631
1632
1634 locate(1), locatedb(5), updatedb(1), xargs(1), chmod(1), fnmatch(3),
1635 regex(7), stat(2), lstat(2), ls(1), printf(3), strftime(3), ctime(3)
1636
1637 The full documentation for find is maintained as a Texinfo manual. If
1638 the info and find programs are properly installed at your site, the
1639 command info find should give you access to the complete manual.
1640
1641
1643 As of findutils-4.2.2, shell metacharacters (`*', `?' or `[]' for exam‐
1644 ple) used in filename patterns will match a leading `.', because IEEE
1645 POSIX interpretation 126 requires this.
1646
1647 As of findutils-4.3.3, -perm /000 now matches all files instead of
1648 none.
1649
1650 Nanosecond-resolution timestamps were implemented in findutils-4.3.3.
1651
1652 As of findutils-4.3.11, the -delete action sets find's exit status to a
1653 nonzero value when it fails. However, find will not exit immediately.
1654 Previously, find's exit status was unaffected by the failure of
1655 -delete.
1656
1657 Feature Added in Also occurs in
1658 -newerXY 4.3.3 BSD
1659 -D 4.3.1
1660 -O 4.3.1
1661 -readable 4.3.0
1662 -writable 4.3.0
1663 -executable 4.3.0
1664 -regextype 4.2.24
1665 -exec ... + 4.2.12 POSIX
1666 -execdir 4.2.12 BSD
1667 -okdir 4.2.12
1668 -samefile 4.2.11
1669 -H 4.2.5 POSIX
1670 -L 4.2.5 POSIX
1671 -P 4.2.5 BSD
1672 -delete 4.2.3
1673 -quit 4.2.3
1674 -d 4.2.3 BSD
1675 -wholename 4.2.0
1676 -iwholename 4.2.0
1677 -ignore_readdir_race 4.2.0
1678
1679 -fls 4.0
1680 -ilname 3.8
1681 -iname 3.8
1682 -ipath 3.8
1683 -iregex 3.8
1684
1685 The syntax -perm +MODE was removed in findutils-4.5.12, in favour of
1686 -perm /MODE. The +MODE syntax had been deprecated since findu‐
1687 tils-4.2.21 which was released in 2005.
1688
1690 Operator precedence surprises
1691 The command find . -name afile -o -name bfile -print will never print
1692 afile because this is actually equivalent to find . -name afile -o \(
1693 -name bfile -a -print \). Remember that the precedence of -a is higher
1694 than that of -o and when there is no operator specified between tests,
1695 -a is assumed.
1696
1697 “paths must precede expression” error message
1698 $ find . -name *.c -print
1699 find: paths must precede expression
1700 find: possible unquoted pattern after predicate `-name'?
1701
1702 This happens when the shell could expand the pattern *.c to more than
1703 one file name existing in the current directory, and passing the
1704 resulting file names in the command line to find like this:
1705 find . -name frcode.c locate.c word_io.c -print
1706 That command is of course not going to work, because the -name predi‐
1707 cate allows exactly only one pattern as argument. Instead of doing
1708 things this way, you should enclose the pattern in quotes or escape the
1709 wildcard, thus allowing find to use the pattern with the wildcard dur‐
1710 ing the search for file name matching instead of file names expanded by
1711 the parent shell:
1712 $ find . -name '*.c' -print
1713 $ find . -name \*.c -print
1714
1715
1717 Copyright © 1990-2019 Free Software Foundation, Inc. License GPLv3+:
1718 GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
1719 This is free software: you are free to change and redistribute it.
1720 There is NO WARRANTY, to the extent permitted by law.
1721
1722
1724 There are security problems inherent in the behaviour that the POSIX
1725 standard specifies for find, which therefore cannot be fixed. For
1726 example, the -exec action is inherently insecure, and -execdir should
1727 be used instead. Please see Finding Files for more information.
1728
1729 The environment variable LC_COLLATE has no effect on the -ok action.
1730
1731 The best way to report a bug is to use the form at https://savan‐
1732 nah.gnu.org/bugs/?group=findutils. The reason for this is that you
1733 will then be able to track progress in fixing the problem. Other com‐
1734 ments about find(1) and about the findutils package in general can be
1735 sent to the bug-findutils mailing list. To join the list, send email
1736 to bug-findutils-request@gnu.org.
1737
1738
1739
1740 FIND(1)