1 .TH FIND 1 \" -*- nroff -*-
3 find \- search for files in a directory hierarchy
6 [\-H] [\-L] [\-P] [\-D debugopts] [\-Olevel] [path...] [expression]
9 documents the GNU version of
13 searches the directory tree rooted at each given file name by
14 evaluating the given expression from left to right, according to the
15 rules of precedence (see section OPERATORS), until the outcome is
16 known (the left hand side is false for \fIand\fR operations, true for
17 \fIor\fR), at which point
19 moves on to the next file name.
23 in an environment where security is important (for example if you are
24 using it to seach directories that are writable by other users), you
25 should read the "Security Considerations" chapter of the findutils
26 documentation, which is called \fBFinding Files\fP and comes with
27 findutils. That document also includes a lot more detail
28 and discussion than this manual page, so you may find it a more useful
29 source of information.
36 options control the treatment of symbolic
37 links. Command-line arguments following these are taken to be names
38 of files or directories to be examined, up to the first argument that
39 begins with `\-', or the argument `(' or `!'. That argument and any
40 following arguments are taken to be the expression describing what is
41 to be searched for. If no paths are given, the current directory is
42 used. If no expression is given, the expression
45 (but you should probably consider using
49 This manual page talks about `options' within the expression list.
50 These options control the behaviour of
52 but are specified immediately after the last path name. The five
61 the first path name, if at all. A double dash
64 to signal that any remaining arguments are not options (though
65 ensuring that all start points begin with either `./' or `/' is
66 generally safer if you use wildcards in the list of start points).
68 Never follow symbolic links. This is the default behaviour. When
70 examines or prints information a file, and the file is a symbolic
71 link, the information used shall be taken from the properties of the
75 Follow symbolic links. When
77 examines or prints information about files, the information used shall
78 be taken from the properties of the file to which the link points, not
79 from the link itself (unless it is a broken symbolic link or
81 is unable to examine the file to which the link points). Use of this
88 will still be in effect. If
92 discovers a symbolic link to a subdirectory during its search,
93 the subdirectory pointed to by the symbolic link will be searched.
97 option is in effect, the
100 match against the type of the file that a symbolic link points to
101 rather than the link itself (unless the symbolic link is broken).
108 predicates always to return
112 Do not follow symbolic links, except while processing the command
115 examines or prints information about files, the information used
116 shall be taken from the properties of the symbolic link itself. The
117 only exception to this behaviour is when a file specified on the
118 command line is a symbolic link, and the link can be resolved. For
119 that situation, the information used is taken from whatever the link
120 points to (that is, the link is followed). The information about the
121 link itself is used as a fallback if the file pointed to by the
122 symbolic link cannot be examined. If
124 is in effect and one of the
125 paths specified on the command line is a symbolic link to a directory,
126 the contents of that directory will be examined (though of course
127 \-maxdepth 0 would prevent this).
134 is specified, each overrides the
135 others; the last one appearing on the command line takes effect.
136 Since it is the default, the
138 option should be considered to be in
147 frequently stats files during the processing of the command line
148 itself, before any searching has begun. These options also affect how
149 those arguments are processed. Specifically, there are a number of
150 tests that compare files listed on the command line against a file we
151 are currently considering. In each case, the file specified on the
152 command line will have been examined and some of its properties will
153 have been saved. If the named file is in fact a symbolic link, and
156 option is in effect (or if neither
160 were specified), the information used for the comparison will be taken from
161 the properties of the symbolic link. Otherwise, it will be taken from
162 the properties of the file the link points to. If
164 cannot follow the link (for example because it has insufficient
165 privileges or the link points to a nonexistent file) the properties of
166 the link itself will be used.
171 .B \-L options are in effect, any symbolic links listed
174 will be dereferenced, and the timestamp
175 will be taken from the file to which the symbolic link points. The
176 same consideration applies to
184 option has a similar effect to
187 effect at the point where it appears (that is, if
191 is, any symbolic links appearing after
194 command line will be dereferenced, and those before it will not).
196 .IP "\-D debugoptions"
197 Print diagnostic information; this can be helpful to diagnose problems
200 is not doing what you want. The list of debug options should be comma
201 separated. Compatibility of the debug options is not guaranteed
202 between releases of findutils. For a complete list of valid debug
203 options, see the output of
206 Valid debug options include
209 Explain the debugging options
211 Show the expression tree in its original and optimised form.
213 Print messages as files are examined with the
219 program tries to minimise such calls.
221 Prints diagnostic information relating to the optimisation of the
222 expression tree; see the \-O option.
224 Prints a summary indicating how often each predicate succeeded or
228 Enables query optimisation. The
230 program reorders tests to speed up execution while preserving the
231 overall effect; that is, predicates with side effects are not
232 reordered relative to each other. The optimisations performed at each
233 optimisation level are as follows.
236 Equivalent to optimisation level 1.
238 This is the default optimisation level and corresponds to the
239 traditional behaviour. Expressions are reordered so that tests based
240 only on the names of files (for example
250 tests are performed after any tests based only on the names of files,
251 but before any tests that require information from the inode. On many
252 modern versions of Unix, file types are returned by
254 and so these predicates are faster to evaluate than predicates which
255 need to stat the file first.
257 At this optimisation level, the full cost-based query optimiser is
258 enabled. The order of tests is modified so that cheap (i.e. fast)
259 tests are performed first and more expensive ones are performed later,
260 if necessary. Within each cost band, predicates are evaluated earlier
261 or later according to whether they are likely to succeed or not. For
263 predicates which are likely to succeed are evaluated earlier, and for
265 predicates which are likely to fail are evaluated earlier.
268 The cost-based optimiser has a fixed idea of how likely any given test
269 is to succeed. In some cases the probability takes account of the
270 specific nature of the test (for example,
272 is assumed to be more likely to succeed than
274 The cost-based optimiser is currently being evaluated. If it does
275 not actually improve the performance of
277 it will be removed again. Conversely, optimisations that prove to be
278 reliable, robust and effective may be enabled at lower optimisation
279 levels over time. However, the default behaviour (i.e. optimisation
280 level 1) will not be changed in the 4.3.x release series. The
281 findutils test suite runs all the tests on
283 at each optimisation level and ensures that the result is the same.
286 The expression is made up of options (which affect overall operation
287 rather than the processing of a specific file, and always return
288 true), tests (which return a true or false value), and actions (which
289 have side effects and return a true or false value), all separated by
292 is assumed where the operator is omitted.
294 If the expression contains no actions other than
298 performed on all files for which the expression is true.
302 All options always return true. Except for
307 the options affect all tests, including tests specified
308 before the option. This is because the options are processed when the
309 command line is parsed, while the tests don't do anything until files
315 options are different in this respect, and have an effect only on tests which
316 appear later in the command line. Therefore, for clarity, it is best
317 to place them at the beginning of the expression. A warning is issued
318 if you don't do this.
321 A synonym for \-depth, for compatibility with FreeBSD, NetBSD, MacOS X and OpenBSD.
332 from the beginning of today rather than from 24 hours ago. This
333 option only affects tests which appear later on the command line.
336 Process each directory's contents before the directory itself. The
337 \-delete action also implies
343 option instead. Dereference symbolic links.
348 option affects only those tests which
349 appear after it on the command line. Unless the
354 been specified, the position of the
356 option changes the behaviour of the
358 predicate; any files listed as the argument
361 will be dereferenced if they are symbolic links. The same
362 consideration applies to
369 predicate will always match against the type of the file
370 that a symbolic link points to rather than the link itself. Using
375 predicates always to return false.
377 .IP "\-help, \-\-help"
378 Print a summary of the command-line usage of
382 .IP \-ignore_readdir_race
383 Normally, \fBfind\fR will emit an error message when it fails to stat a file.
384 If you give this option and a file is deleted between the time \fBfind\fR
385 reads the name of the file from the directory and the time it tries to stat
386 the file, no error message will be issued. This also applies to files
387 or directories whose names are given on the command line. This option takes
388 effect at the time the command line is read, which means that you cannot search
389 one part of the filesystem with this option on and part of it with this option
390 off (if you need to do that, you will need to issue two \fBfind\fR commands
391 instead, one with the option and one without it).
393 .IP "\-maxdepth \fIlevels\fR"
394 Descend at most \fIlevels\fR (a non-negative integer) levels of
395 directories below the command line arguments.
397 means only apply the tests and actions to the command line arguments.
399 .IP "\-mindepth \fIlevels\fR"
400 Do not apply any tests or actions at levels less than \fIlevels\fR (a
401 non-negative integer).
403 means process all files except the command line arguments.
406 Don't descend directories on other filesystems. An alternate name for
408 for compatibility with some other versions of
411 .IP \-noignore_readdir_race
412 Turns off the effect of
413 .BR \-ignore_readdir_race .
416 Do not optimize by assuming that directories contain 2 fewer
417 subdirectories than their hard link count. This option is needed when
418 searching filesystems that do not follow the Unix directory-link
419 convention, such as CD-ROM or MS-DOS filesystems or AFS volume mount
420 points. Each directory on a normal Unix filesystem has at least 2
421 hard links: its name and its `.' entry. Additionally, its
422 subdirectories (if any) each have a `..' entry linked to that
425 is examining a directory, after it has statted 2 fewer subdirectories
426 than the directory's link count, it knows that the rest of the entries
427 in the directory are non-directories (`leaf' files in the directory
428 tree). If only the files' names need to be examined, there is no need
429 to stat them; this gives a significant increase in search speed.
431 .IP "\-regextype \fItype\fR"
432 Changes the regular expression syntax understood by
436 tests which occur later on the command line. Currently-implemented
437 types are emacs (this is the default), posix-awk, posix-basic,
438 posix-egrep and posix-extended.
440 .IP "\-version, \-\-version"
441 Print the \fBfind\fR version number and exit.
443 .IP "\-warn, \-nowarn"
444 Turn warning messages on or off. These warnings apply only to the
445 command line usage, not to any conditions that
447 might encounter when it searches directories. The default behaviour
450 if standard input is a tty, and to
455 Don't descend directories on other filesystems.
458 Some tests, for example
462 allow comparison between the file currently being examined and some
463 reference file specified on the command line. When these tests are
464 used, the interpretation of the reference file is determined by the
472 but the reference file is only examined once, at the time the command
473 line is parsed. If the reference file cannot be examined (for
476 system call fails for it), an error message is issued, and
478 exits with a nonzero status.
480 Numeric arguments can be specified as
493 File was last accessed \fIn\fR minutes ago.
495 .IP "\-anewer \fIfile\fR"
496 File was last accessed more recently than \fIfile\fR was modified. If
497 \fIfile\fR is a symbolic link and the
501 option is in effect, the access time of the file it points to is
504 .IP "\-atime \fIn\fR"
505 File was last accessed \fIn\fR*24 hours ago.
506 When find figures out how many 24-hour periods ago the file
507 was last accessed, any fractional part is ignored, so to match
510 a file has to have been accessed at least
515 File's status was last changed \fIn\fR minutes ago.
517 .IP "\-cnewer \fIfile\fR"
518 File's status was last changed more recently than \fIfile\fR was
519 modified. If \fIfile\fR is a symbolic link and the
523 option is in effect, the status-change time of the file it points
526 .IP "\-ctime \fIn\fR"
527 File's status was last changed \fIn\fR*24 hours ago.
530 to understand how rounding affects the interpretation of file status
534 File is empty and is either a regular file or a directory.
537 Matches files which are executable and directories which are
538 searchable (in a file name resolution sense). This takes into account
539 access control lists and other permissions artefacts which the
541 test ignores. This test makes use of the
543 system call, and so can be fooled by NFS servers which do UID
544 mapping (or root-squashing), since many systems implement
546 in the client's kernel and so cannot make use of the UID mapping
547 information held on the server. Because this test is based only on
550 system call, there is no guarantee that a file for which this test
551 succeeds can actually be executed.
556 .IP "\-fstype \fItype\fR"
557 File is on a filesystem of type \fItype\fR. The valid filesystem
558 types vary among different versions of Unix; an incomplete list of
559 filesystem types that are accepted on some version of Unix or another
560 is: ufs, 4.2, 4.3, nfs, tmp, mfs, S51K, S52K. You can use
562 with the %F directive to see the types of your filesystems.
565 File's numeric group ID is \fIn\fR.
567 .IP "\-group \fIgname\fR"
568 File belongs to group \fIgname\fR (numeric group ID allowed).
570 .IP "\-ilname \fIpattern\fR"
573 but the match is case insensitive.
578 option is in effect, this test returns false unless the symbolic link
581 .IP "\-iname \fIpattern\fR"
584 but the match is case insensitive. For example, the
585 patterns `fo*' and `F??' match the file names `Foo', `FOO', `foo',
586 `fOo', etc. In these patterns, unlike filename expansion by the
587 shell, an initial '.' can be matched by `*'. That is,
589 will match the file `.foobar'. Please note that you should quote
590 patterns as a matter of course, otherwise the shell will expand any
591 wildcard characters in them.
594 File has inode number \fIn\fR. It is normally easier to use the
598 .IP "\-ipath \fIpattern\fR"
599 Behaves in the same way as
601 This option is deprecated, so please do not use it.
603 .IP "\-iregex \fIpattern\fR"
606 but the match is case insensitive.
608 .IP "\-iwholename \fIpattern\fR"
611 but the match is case insensitive.
613 .IP "\-links \fIn\fR"
614 File has \fIn\fR links.
616 .IP "\-lname \fIpattern\fR"
617 File is a symbolic link whose contents match shell pattern
618 \fIpattern\fR. The metacharacters do not treat `/' or `.' specially.
623 option is in effect, this test returns false unless the symbolic link
627 File's data was last modified \fIn\fR minutes ago.
629 .IP "\-mtime \fIn\fR"
630 File's data was last modified \fIn\fR*24 hours ago.
633 to understand how rounding affects the interpretation of file
636 .IP "\-name \fIpattern\fR"
637 Base of file name (the path with the leading directories removed)
638 matches shell pattern \fIpattern\fR. The metacharacters (`*', `?',
639 and `[]') match a `.' at the start of the base name (this is a change
640 in findutils-4.2.2; see section STANDARDS CONFORMANCE below). To ignore a
641 directory and the files under it, use
643 see an example in the
646 Braces are not recognised as being
647 special, despite the fact that some shells including Bash imbue braces
648 with a special meaning in shell patterns. The filename matching is
649 performed with the use of the
651 library function. Don't forget to enclose the pattern in quotes
652 in order to protect it from expansion by the shell.
654 .IP "\-newer \fIfile\fR"
655 File was modified more recently than \fIfile\fR. If \fIfile\fR is a
656 symbolic link and the
660 option is in effect, the
661 modification time of the file it points to is always used.
663 .IP "\-newerXY \fIreference\fR"
664 Compares the timestamp of the current file with \fIreference\fR.
667 argument is normally the name of a file (and one of its timestamps is
668 used for the comparison) but it may also be a string describing an
673 are placeholders for other letters, and these letters select which
677 is used for the comparison.
684 a The access time of the file \fIreference\fR
685 B The birth time of the file \fIreference\fR
686 c The inode status change time of \fIreference\fR
687 m The modification time of the file \fIreference\fR
688 t \fIreference\fR is interpreted directly as a time
691 Some combinations are invalid; for example, it is invalid for
695 Some combinations are not implemented on all systems; for example
697 is not supported on all systems. If an invalid or unsupported
700 is specified, a fatal error results. Time specifications are
701 interpreted as for the argument to the
705 If you try to use the birth time of a reference file, and the birth
706 time cannot be determined, a fatal error message results. If you
707 specify a test which refers to the birth time of files being examined,
708 this test will fail for any files where the birth time is unknown.
711 No group corresponds to file's numeric group ID.
714 No user corresponds to file's numeric user ID.
716 .IP "\-path \fIpattern\fR"
717 File name matches shell pattern \fIpattern\fR. The metacharacters do
718 not treat `/' or `.' specially; so, for example,
721 find . \-path "./sr*sc"
724 will print an entry for a directory called `./src/misc' (if one
725 exists). To ignore a whole directory tree, use
728 checking every file in the tree. For example, to skip the
729 directory `src/emacs' and all files and directories under it, and
730 print the names of the other files found, do something like this:
733 find . \-path ./src/emacs \-prune \-o \-print
736 Note that the pattern match test applies to the whole file name,
737 starting from one of the start points named on the command line. It
738 would only make sense to use an absolute path name here if the
739 relevant start point is also an absolute path. This means that this
740 command will never match anything:
743 find bar \-path /foo/bar/myfile \-print
748 is also supported by HP-UX
750 and will be in a forthcoming version of the POSIX standard.
752 .IP "\-perm \fImode\fR"
753 File's permission bits are exactly \fImode\fR (octal or symbolic).
754 Since an exact match is required, if you want to use this form for
755 symbolic modes, you may have to specify a rather complex mode string.
758 will only match files which have mode 0020
759 (that is, ones for which group write permission is the only permission
760 set). It is more likely that you will want to use the `/' or `-'
763 which matches any file with group write permission. See the
765 section for some illustrative examples.
767 .IP "\-perm \-\fImode\fR"
768 All of the permission bits \fImode\fR are set for the file.
769 Symbolic modes are accepted in this form, and this is usually the way
770 in which would want to use them. You must specify `u', `g' or `o' if
771 you use a symbolic mode. See the
773 section for some illustrative examples.
775 .IP "\-perm /\fImode\fR"
776 Any of the permission bits \fImode\fR are set for the file. Symbolic
777 modes are accepted in this form. You must specify `u', `g' or `o' if
778 you use a symbolic mode. See the
780 section for some illustrative examples. If no permission bits in
782 are set, this test currently matches no files. However, it will soon
783 be changed to match any file (the idea is to be more consistent with
788 .IP "\-perm +\fImode\fR"
789 Deprecated, old way of searching for files with any of the permission
790 bits in \fImode\fR set. You should use
791 .B \-perm \fI/mode\fR
792 instead. Trying to use the `+' syntax with symbolic modes will yield
793 surprising results. For example, `+u+x' is a valid symbolic mode
794 (equivalent to +u,+x, i.e. 0111) and will therefore not be evaluated
796 .B \-perm +\fImode\fR
797 but instead as the exact mode specifier
799 and so it matches files with exact permissions 0111 instead of files with any
800 execute bit set. If you found this paragraph confusing, you're not
802 .B \-perm /\fImode\fR.
805 test is deprecated because the POSIX specification requires the
806 interpretation of a leading `+' as being part of a symbolic mode, and
807 so we switched to using `/' instead.
810 Matches files which are readable. This takes into account access
811 control lists and other permissions artefacts which the
813 test ignores. This test makes use of the
815 system call, and so can be fooled by NFS servers which do UID
816 mapping (or root-squashing), since many systems implement
818 in the client's kernel and so cannot make use of the UID mapping
819 information held on the server.
821 .IP "\-regex \fIpattern\fR"
822 File name matches regular expression \fIpattern\fR. This is a match
823 on the whole path, not a search. For example, to match a file named
824 `./fubar3', you can use the regular expression `.*bar.' or `.*b.*3',
825 but not `f.*r3'. The regular expressions understood by
827 are by default Emacs Regular Expressions, but this can be
832 .IP "\-samefile \fIname\fR"
833 File refers to the same inode as \fIname\fR. When
835 is in effect, this can include symbolic links.
837 .IP "\-size \fIn\fR[cwbkMG]"
838 File uses \fIn\fP units of space. The following suffixes
842 for 512-byte blocks (this is the default if no suffix is used)
848 for Kilobytes (units of 1024 bytes)
850 for Megabytes (units of 1048576 bytes)
852 for Gigabytes (units of 1073741824 bytes)
855 The size does not count indirect blocks, but it does count blocks in
856 sparse files that are not actually allocated. Bear in mind that the
857 `%k' and `%b' format specifiers of
860 differently. The `b' suffix always denotes 512-byte blocks and never
861 1 Kilobyte blocks, which is different to the behaviour of
868 File is of type \fIc\fR:
871 block (buffered) special
873 character (unbuffered) special
881 symbolic link; this is never true if the
885 option is in effect, unless the symbolic link is broken. If you want
886 to search for symbolic links when
896 File's numeric user ID is \fIn\fR.
899 File was last accessed \fIn\fR days after its status was last changed.
901 .IP "\-user \fIuname\fR"
902 File is owned by user \fIuname\fR (numeric user ID allowed).
904 .IP "\-wholename \fIpattern\fR"
905 See \-path. This alternative is less portable than
909 Matches files which are writable. This takes into account access
910 control lists and other permissions artefacts which the
912 test ignores. This test makes use of the
914 system call, and so can be fooled by NFS servers which do UID
915 mapping (or root-squashing), since many systems implement
917 in the client's kernel and so cannot make use of the UID mapping
918 information held on the server.
920 .IP "\-xtype \fIc\fR"
923 unless the file is a symbolic link. For symbolic
928 option was specified, true if the file is a
929 link to a file of type \fIc\fR; if the
931 option has been given, true
932 if \fIc\fR is `l'. In other words, for symbolic links,
934 checks the type of the file that
940 Delete files; true if removal succeeded. If the removal failed, an
941 error message is issued.
946 exit status will be nonzero
947 (when it eventually exits).
950 automatically turns on the
955 Don't forget that the find command line is
956 evaluated as an expression, so putting
960 try to delete everything below the starting points you specified.
963 command line that you later intend to use with
965 you should explicitly specify
967 in order to avoid later surprises. Because
971 you cannot usefully use
977 .IP "\-exec \fIcommand\fR ;"
978 Execute \fIcommand\fR; true if 0 status is returned. All following
981 are taken to be arguments to the command until an argument consisting
982 of `;' is encountered. The string `{}' is replaced by the current
983 file name being processed everywhere it occurs in the arguments to the
984 command, not just in arguments where it is alone, as in some versions
987 Both of these constructions might need to be escaped (with a `\e') or
988 quoted to protect them from expansion by the shell. See the
990 section for examples of the use of the
992 option. The specified
993 command is run once for each matched file.
994 The command is executed in the starting directory. There are
995 unavoidable security problems surrounding use of the
1002 .IP "\-exec \fIcommand\fR {} +"
1005 action runs the specified command on the
1006 selected files, but the command line is built by appending each
1007 selected file name at the end; the total number of invocations of the
1008 command will be much less than the number of matched files. The
1009 command line is built in much the same way that
1011 builds its command lines. Only one instance of `{}' is allowed within
1012 the command. The command is executed in the starting directory.
1014 .IP "\-execdir \fIcommand\fR ;"
1015 .IP "\-execdir \fIcommand\fR {} +"
1018 but the specified command is run from the subdirectory
1019 containing the matched file, which is not normally the directory in
1022 This a much more secure method for invoking commands, as it avoids
1023 race conditions during resolution of the paths to the matched files.
1026 action, the `+' form of
1029 command line to process more than one matched file, but any given
1032 will only list files that exist in the same subdirectory. If you use
1033 this option, you must ensure that your
1035 environment variable does not reference `.';
1036 otherwise, an attacker can run any commands they like by leaving an
1037 appropriately-named file in a directory in which you will run
1039 The same applies to having entries in
1041 which are empty or which are not absolute directory names.
1043 .IP "\-fls \fIfile\fR"
1046 but write to \fIfile\fR like
1048 The output file is always created, even if the predicate is never
1051 .B UNUSUAL FILENAMES
1052 section for information about how unusual characters in filenames are handled.
1054 .IP "\-fprint \fIfile\fR"
1055 True; print the full file name into file \fIfile\fR. If \fIfile\fR
1056 does not exist when \fBfind\fR is run, it is created; if it does
1057 exist, it is truncated. The file names ``/dev/stdout'' and
1058 ``/dev/stderr'' are handled specially; they refer to the standard
1059 output and standard error output, respectively.
1060 The output file is always created, even if the predicate is never matched.
1062 .B UNUSUAL FILENAMES
1063 section for information about how unusual characters in filenames are handled.
1065 .IP "\-fprint0 \fIfile\fR"
1068 but write to \fIfile\fR like
1070 The output file is always created, even if the predicate is never matched.
1072 .B UNUSUAL FILENAMES
1073 section for information about how unusual characters in filenames are handled.
1075 .IP "\-fprintf \fIfile\fR \fIformat\fR"
1078 but write to \fIfile\fR like
1080 The output file is always created, even if the predicate is never matched.
1082 .B UNUSUAL FILENAMES
1083 section for information about how unusual characters in filenames are handled.
1086 True; list current file in
1088 format on standard output.
1089 The block counts are of 1K blocks, unless the environment variable
1090 POSIXLY_CORRECT is set, in which case 512-byte blocks are used.
1092 .B UNUSUAL FILENAMES
1093 section for information about how unusual characters in filenames are handled.
1095 .IP "\-ok \fIcommand\fR ;"
1098 but ask the user first (on the standard input); if the
1099 response does not start with `y' or `Y', do not run the command, and
1100 return false. If the command is run, its standard input is redirected
1104 .IP "\-okdir \fIcommand\fR ;"
1107 but ask the user first (on the standard input); if the
1108 response does not start with `y' or `Y', do not run the command, and
1109 return false. If the command is run, its standard input is redirected
1114 True; print the full file name on the standard output, followed by a
1115 newline. If you are piping the output of
1117 into another program and there is the faintest possibility that the files
1118 which you are searching for might contain a newline, then you should
1119 seriously consider using the
1124 .B UNUSUAL FILENAMES
1125 section for information about how unusual characters in filenames are handled.
1128 True; print the full file name on the standard output, followed by a
1129 null character (instead of the newline character that
1132 This allows file names that contain newlines or other types of white
1133 space to be correctly interpreted by programs that process the
1134 \fBfind\fR output. This option corresponds to the
1139 .IP "\-printf \fIformat\fR"
1140 True; print \fIformat\fR on the standard output, interpreting `\e'
1141 escapes and `%' directives. Field widths and precisions can be
1142 specified as with the `printf' C function. Please note that many of
1143 the fields are printed as %s rather than %d, and this may mean that
1144 flags don't work as you might expect. This also means that the `\-'
1145 flag does work (it forces fields to be left-aligned). Unlike
1148 does not add a newline at the end of the string. The escapes
1156 Stop printing from this format immediately and flush the output.
1170 A literal backslash (`\e').
1172 The character whose ASCII code is NNN (octal).
1174 A `\e' character followed by any other character is treated as an
1175 ordinary character, so they both are printed.
1177 A literal percent sign.
1179 File's last access time in the format returned by the C `ctime' function.
1181 File's last access time in the format specified by \fIk\fR, which is
1182 either `@' or a directive for the C `strftime' function. The possible
1183 values for \fIk\fR are listed below; some of them might not be
1184 available on all systems, due to differences in `strftime' between
1188 seconds since Jan. 1, 1970, 00:00 GMT, with fractional part.
1204 time, 12-hour (hh:mm:ss [AP]M)
1206 Second (00.00 .. 61.00). There is a fractional part.
1208 time, 24-hour (hh:mm:ss)
1210 Date and time, separated by `+', for example
1211 `2004\-04\-28+22:22:05.0'. This is a GNU extension. The time is
1212 given in the current timezone (which may be affected by setting the TZ
1213 environment variable). The seconds field includes a fractional part.
1215 locale's time representation (H:M:S)
1217 time zone (e.g., EDT), or nothing if no time zone is determinable
1221 locale's abbreviated weekday name (Sun..Sat)
1223 locale's full weekday name, variable length (Sunday..Saturday)
1225 locale's abbreviated month name (Jan..Dec)
1227 locale's full month name, variable length (January..December)
1229 locale's date and time (Sat Nov 04 12:02:33 EST 1989). The format is
1232 and so to preserve compatibility with that format, there is no fractional part
1233 in the seconds field.
1235 day of month (01..31)
1241 day of year (001..366)
1245 week number of year with Sunday as first day of week (00..53)
1249 week number of year with Monday as first day of week (00..53)
1251 locale's date representation (mm/dd/yy)
1253 last two digits of year (00..99)
1258 The amount of disk space used for this file in 512-byte blocks. Since disk
1259 space is allocated in multiples of the filesystem block size this is usually
1260 greater than %s/512, but it can also be smaller if the file is a sparse file.
1262 File's last status change time in the format returned by the C `ctime'
1265 File's last status change time in the format specified by \fIk\fR,
1266 which is the same as for %A.
1268 File's depth in the directory tree; 0 means the file is a command line
1271 The device number on which the file exists (the st_dev field of struct
1274 File's name with any leading directories removed (only the last element).
1276 Type of the filesystem the file is on; this value can be used for
1279 File's group name, or numeric group ID if the group has no name.
1281 File's numeric group ID.
1283 Leading directories of file's name (all but the last element).
1284 If the file name contains no slashes (since it is in the current
1285 directory) the %h specifier expands to ".".
1287 Command line argument under which file was found.
1289 File's inode number (in decimal).
1291 The amount of disk space used for this file in 1K blocks. Since disk space is
1292 allocated in multiples of the filesystem block size this is usually greater
1293 than %s/1024, but it can also be smaller if the file is a sparse file.
1295 Object of symbolic link (empty string if file is not a symbolic link).
1297 File's permission bits (in octal). This option uses the `traditional'
1298 numbers which most Unix implementations use, but if your particular
1299 implementation uses an unusual ordering of octal permissions bits, you
1300 will see a difference between the actual value of the file's mode and
1301 the output of %m. Normally you will want to have a leading
1302 zero on this number, and to do this, you should use the
1304 flag (as in, for example, `%#m').
1306 File's permissions (in symbolic form, as for
1308 This directive is supported in findutils 4.2.5 and later.
1310 Number of hard links to file.
1314 File's name with the name of the command line argument under which
1315 it was found removed.
1317 File's size in bytes.
1319 File's sparseness. This is calculated as (BLOCKSIZE*st_blocks /
1320 st_size). The exact value you will get for an ordinary file of a
1321 certain length is system-dependent. However, normally sparse files
1322 will have values less than 1.0, and files which use indirect blocks
1323 may have a value which is greater than 1.0. The value used for
1324 BLOCKSIZE is system-dependent, but is usually 512 bytes. If the file
1325 size is zero, the value printed is undefined. On systems which lack
1326 support for st_blocks, a file's sparseness is assumed to be 1.0.
1328 File's last modification time in the format returned by the C `ctime'
1331 File's last modification time in the format specified by \fIk\fR,
1332 which is the same as for %A.
1334 File's user name, or numeric user ID if the user has no name.
1336 File's numeric user ID.
1338 File's type (like in
1340 U=unknown type (shouldn't happen)
1342 File's type (like %y), plus follow symlinks: L=loop, N=nonexistent
1344 A `%' character followed by any other character is discarded, but the
1345 other character is printed (don't rely on this, as further format
1346 characters may be introduced). A `%' at the end of the format
1347 argument causes undefined behaviour since there is no following
1348 character. In some locales, it may hide your door keys, while in
1349 others it may remove the final page from the novel you are reading.
1351 The %m and %d directives support the
1357 flags, but the other directives do not, even if they
1358 print numbers. Numeric directives that do not support these flags
1367 The `\-' format flag is supported and changes the alignment of a field
1368 from right-justified (which is the default) to left-justified.
1371 .B UNUSUAL FILENAMES
1372 section for information about how unusual characters in filenames are handled.
1377 True; if the file is a directory, do not descend into it. If
1379 is given, false; no effect. Because
1383 you cannot usefully use
1386 .B \-delete together.
1389 Exit immediately. No child processes will be left running, but no more
1390 paths specified on the command line will be processed. For example,
1391 .B find /tmp/foo /tmp/bar \-print \-quit
1394 Any command lines which have been built up with
1395 .B \-execdir ... {} +
1396 will be invoked before
1398 exits. The exit status may or may not be zero, depending on whether
1399 an error has already occurred.
1401 .SS UNUSUAL FILENAMES
1402 Many of the actions of
1404 result in the printing of data which is under the control of other
1405 users. This includes file names, sizes, modification times and so
1406 forth. File names are a potential problem since they can contain any
1407 character except `\e0' and `/'. Unusual characters in file names can
1408 do unexpected and often undesirable things to your terminal (for
1409 example, changing the settings of your function keys on some
1410 terminals). Unusual characters are handled differently by various
1411 actions, as described below.
1413 .IP "\-print0, \-fprint0\"
1414 Always print the exact filename, unchanged, even if the output is
1415 going to a terminal.
1418 Unusual characters are always escaped. White space, backslash, and
1419 double quote characters are printed using C-style escaping (for
1420 example `\ef', `\e"'). Other unusual characters are printed using an
1421 octal escape. Other printable characters (for
1425 these are the characters between octal 041 and 0176) are printed as-is.
1427 .IP "\-printf, \-fprintf"
1428 If the output is not going to a terminal, it is printed as-is.
1429 Otherwise, the result depends on which directive is in use. The
1430 directives %D, %F, %g, %G, %H, %Y, and %y expand to values which are
1431 not under control of files' owners, and so are printed as-is. The
1432 directives %a, %b, %c, %d, %i, %k, %m, %M, %n, %s, %t, %u and %U have
1433 values which are under the control of files' owners but which cannot
1434 be used to send arbitrary data to the terminal, and so these are
1435 printed as-is. The directives %f, %h, %l, %p and %P are quoted. This
1436 quoting is performed in the same way as for GNU
1438 This is not the same quoting mechanism as the one used for
1442 If you are able to decide what format to use for the output of
1444 then it is normally better to use `\e0' as a terminator
1445 than to use newline, as file names can contain white space and newline
1448 .IP "\-print, \-fprint"
1449 Quoting is handled in the same way as for
1455 in a script or in a situation where the matched files might have
1456 arbitrary names, you should consider using
1465 actions print the current filename as-is. This may change in a future release.
1468 Listed in order of decreasing precedence:
1470 .IP "( \fIexpr\fR )"
1471 Force precedence. Since parentheses are special to the shell, you
1472 will normally need to quote them. Many of the examples in this manual
1473 page use backslashes for this purpose: `\e(...\e)' instead of `(...)'.
1476 True if \fIexpr\fR is false. This character will also usually need
1477 protection from interpretation by the shell.
1479 .IP "\-not \fIexpr\fR"
1480 Same as ! \fIexpr\fR, but not POSIX compliant.
1482 .IP "\fIexpr1 expr2\fR"
1483 Two expressions in a row are taken to be joined with an
1484 implied "and"; \fIexpr2\fR is not evaluated if \fIexpr1\fR is false.
1486 .IP "\fIexpr1\fR \-a \fIexpr2\fR"
1487 Same as \fIexpr1 expr2\fR.
1489 .IP "\fIexpr1\fR \-and \fIexpr2\fR"
1490 Same as \fIexpr1 expr2\fR, but not POSIX compliant.
1492 .IP "\fIexpr1\fR \-o \fIexpr2\fR"
1493 Or; \fIexpr2\fR is not evaluated if \fIexpr1\fR is true.
1495 .IP "\fIexpr1\fR \-or \fIexpr2\fR"
1498 \fIexpr2\fR, but not POSIX compliant.
1500 .IP "\fIexpr1\fR , \fIexpr2\fR"
1501 List; both \fIexpr1\fR and \fIexpr2\fR are always evaluated. The
1502 value of \fIexpr1\fR is discarded; the value of the list is the value
1503 of \fIexpr2\fR. The comma operator can be useful for searching for
1504 several different types of thing, but traversing the filesystem
1505 hierarchy only once. The
1507 action can be used to list the various matched items into several
1508 different output files.
1511 .SH "STANDARDS CONFORMANCE"
1512 For closest compliance to the POSIX standard, you should set the
1513 POSIXLY_CORRECT environment variable. The following options are
1514 specified in the POSIX standard (IEEE Std 1003.1, 2003 Edition):
1517 This option is supported.
1520 This option is supported.
1523 This option is supported, but POSIX conformance depends on the
1524 POSIX conformance of the system's
1526 library function. As of findutils-4.2.2, shell metacharacters
1527 (`*', `?' or `[]' for example) will match a leading `.', because
1528 IEEE PASC interpretation 126 requires this. This is a change from
1529 previous versions of findutils.
1532 Supported. POSIX specifies `b', `c', `d', `l', `p', `f' and `s'.
1533 GNU find also supports `D', representing a Door, where the OS provides these.
1536 Supported. Interpretation of the response is not locale-dependent
1537 (see ENVIRONMENT VARIABLES).
1540 Supported. If the file specified is a symbolic link, it is always
1541 dereferenced. This is a change from previous behaviour, which used to
1542 take the relevant time from the symbolic link; see the HISTORY section
1546 Supported. If the POSIXLY_CORRECT environment variable is not set,
1547 some mode arguments (for example +a+x) which are not valid in POSIX
1548 are supported for backward-compatibility.
1550 .IP "Other predicates"
1569 The POSIX standard specifies parentheses `(', `)', negation `!' and the
1570 `and' and `or' operators (
1574 All other options, predicates, expressions and so forth are extensions
1575 beyond the POSIX standard. Many of these extensions are not unique to
1578 The POSIX standard requires that
1584 utility shall detect infinite loops; that is, entering a
1585 previously visited directory that is an ancestor of the last file
1586 encountered. When it detects an infinite loop, find shall write a
1587 diagnostic message to standard error and shall either recover its
1588 position in the hierarchy or terminate.
1592 complies with these requirements. The link count of
1593 directories which contain entries which are hard links to an ancestor
1594 will often be lower than they otherwise should be. This can mean that
1595 GNU find will sometimes optimise away the visiting of a subdirectory
1596 which is actually a link to an ancestor. Since
1598 does not actually enter such a subdirectory, it is allowed to avoid
1599 emitting a diagnostic message. Although this behaviour may be
1600 somewhat confusing, it is unlikely that anybody actually depends on
1601 this behaviour. If the leaf optimisation has been turned off with
1603 the directory entry will always be examined and the diagnostic message
1604 will be issued where it is appropriate. Symbolic links cannot be used
1605 to create filesystem cycles as such, but if the
1609 option is in use, a diagnostic message is issued when
1611 encounters a loop of symbolic links. As with loops containing hard
1612 links, the leaf optimisation will often mean that
1614 knows that it doesn't need to call
1618 on the symbolic link, so this diagnostic is frequently not necessary.
1622 option is supported for compatibility with various BSD systems,
1623 but you should use the POSIX-compliant option
1627 The POSIXLY_CORRECT environment variable does not affect the behaviour
1632 tests because those tests aren't specified in the POSIX standard.
1633 .SH "ENVIRONMENT VARIABLES"
1636 Provides a default value for the internationalization variables that
1640 If set to a non-empty string value, override the values of all the
1641 other internationalization variables.
1644 The POSIX standard specifies that this variable affects the pattern
1645 matching to be used for the
1647 option. GNU find uses the
1649 library function, and so support for `LC_COLLATE' depends on the
1653 POSIX also specifies that the `LC_COLLATE' environment
1654 variable affects the interpretation of the user's response to the
1657 but this is not the case for GNU find.
1660 This variable affects the treatment of character classes used with
1663 test, if the system's
1665 library function supports this. It has no effect on the behaviour
1671 Determines the locale to be used for internationalised messages.
1674 Determines the location of the internationalisation message catalogues.
1677 Affects the directories which are searched to find the executables
1686 Determines the block size used by
1692 is set, blocks are units of 512 bytes. Otherwise
1693 they are units of 1024 bytes.
1695 Setting this variable also turns off
1696 warning messages (that is, implies
1698 by default, because POSIX requires that apart from
1701 all messages printed on stderr are diagnositcs and must result in a
1702 non-zero exit status.
1704 When POSIXLY_CORRECT is not set,
1707 is treated just like
1711 +zzz is not a valid symbolic mode. When POSIXLY_CORRECT is set, such
1712 constructs are treated as an error.
1715 Affects the time zone used for some of the time-related format
1722 .B find /tmp \-name core \-type f \-print | xargs /bin/rm \-f
1727 in or below the directory
1729 and delete them. Note that this will work incorrectly if there are
1730 any filenames containing newlines, single or double quotes, or spaces.
1732 .B find /tmp \-name core \-type f \-print0 | xargs \-0 /bin/rm \-f
1737 in or below the directory
1739 and delete them, processing filenames in such a way that file or
1740 directory names containing single or double quotes, spaces or newlines
1741 are correctly handled. The
1743 test comes before the
1745 test in order to avoid having to call
1751 .B find . \-type f \-exec file \(aq{}\(aq \e\;
1754 Runs `file' on every file in or below the current directory. Notice
1755 that the braces are enclosed in single quote marks to protect them
1756 from interpretation as shell script punctuation. The semicolon is
1757 similarly protected by the use of a backslash, though single quotes
1758 could have been used in that case also.
1763 .B \e( \-perm \-4000 \-fprintf /root/suid.txt "%#m %u %p\en" \e) , \e
1764 .B \e( \-size +100M \-fprintf /root/big.txt "%\-10s %p\en" \e)
1767 Traverse the filesystem just once, listing setuid files and
1770 and large files into
1775 .B find $HOME \-mtime 0
1778 Search for files in your home directory which have been modified in
1779 the last twenty-four hours. This command works this way because the
1780 time since each file was last modified is divided by 24 hours and any
1781 remainder is discarded. That means that to match
1784 a file will have to have a modification in the past which is less than
1789 .B find /sbin /usr/sbin -executable \e! -readable \-print
1792 Search for files which are executable but not readable.
1796 .B find . \-perm 664
1799 Search for files which have read and write permission for their owner,
1800 and group, but which other users can read but not write to. Files
1801 which meet these criteria but have other permissions bits set (for
1802 example if someone can execute the file) will not be matched.
1806 .B find . \-perm \-664
1809 Search for files which have read and write permission for their owner
1810 and group, and which other users can read, without regard to the
1811 presence of any extra permission bits (for example the executable
1812 bit). This will match a file which has mode 0777, for example.
1816 .B find . \-perm /222
1819 Search for files which are writable by somebody (their owner, or
1820 their group, or anybody else).
1824 .B find . \-perm /220
1825 .B find . \-perm /u+w,g+w
1826 .B find . \-perm /u=w,g=w
1829 All three of these commands do the same thing, but the first one uses
1830 the octal representation of the file mode, and the other two use the
1831 symbolic form. These commands all search for files which are
1832 writable by either their owner or their group. The files don't have
1833 to be writable by both the owner and group to be matched; either will
1838 .B find . \-perm \-220
1839 .B find . \-perm \-g+w,u+w
1842 Both these commands do the same thing; search for files which are
1843 writable by both their owner and their group.
1847 .B find . \-perm \-444 \-perm /222 ! \-perm /111
1848 .B find . \-perm \-a+r \-perm /a+w ! \-perm /a+x
1851 These two commands both search for files that are readable for
1855 .BR "\-perm \-a+r" ),
1856 have at least one write bit
1861 but are not executable for anybody (
1870 .B find . \-name .snapshot \-prune \-o \e( \e! \-name "*~" \-print0 \e)|
1871 .B cpio \-pmd0 /dest-dir
1874 This command copies the contents of
1878 but omits files and directories named
1880 (and anything in them). It also omits files or directories whose name
1883 but not their contents. The construct
1884 .B \-prune \-o \e( ... \-print0 \e)
1885 is quite common. The idea here is that the expression before
1887 matches things which are to be pruned. However, the
1889 action itself returns true, so the following
1891 ensures that the right hand side is evaluated only for those
1892 directories which didn't get pruned (the contents of the pruned
1893 directories are not even visited, so their contents are irrelevant).
1894 The expression on the right hand side of the
1896 is in parentheses only for clarity. It emphasises that the
1898 action takes place only for things that didn't have
1900 applied to them. Because the default `and' condition between tests
1901 binds more tightly than
1903 this is the default anyway, but the parentheses help to show
1909 exits with status 0 if all files are processed successfully, greater
1910 than 0 if errors occur. This is deliberately a very broad
1911 description, but if the return value is non-zero, you should not rely
1912 on the correctness of the results of
1916 \fBlocate\fP(1), \fBlocatedb\fP(5), \fBupdatedb\fP(1), \fBxargs\fP(1),
1917 \fBchmod\fP(1), \fBfnmatch\fP(3), \fBregex\fP(7), \fBstat\fP(2),
1918 \fBlstat\fP(2), \fBls\fP(1), \fBprintf\fP(3), \fBstrftime\fP(3),
1919 \fBctime\fP(3), \fBFinding Files\fP (on-line in Info, or printed).
1921 As of findutils-4.2.2, shell metacharacters (`*', `?' or `[]' for
1922 example) used in filename patterns will match a leading `.', because
1923 IEEE POSIX interpretation 126 requires this.
1927 was deprecated in findutils-4.2.21, in favour of
1930 As of findutils-4.3.3,
1932 now matches all files instead of none.
1934 Nanosecond-resolution
1935 timestamps were implemented in findutils-4.3.3.
1937 As of findutils-4.3.11, the
1941 exit status to a nonzero value when it fails.
1944 will not exit immediately. Previously,
1946 exit status was unaffected by the failure of
1950 Feature Added in Also occurs in
1958 \-exec ... + 4.2.12 POSIX
1959 \-execdir 4.2.12 BSD
1970 \-ignore_readdir_race 4.2.0
1979 .B $ find . \-name *.c \-print
1980 find: paths must precede expression
1981 Usage: find [\-H] [\-L] [\-P] [\-Olevel] [\-D help|tree|search|stat|rates|opt|exec] [path...] [expression]
1984 This happens because
1986 has been expanded by the shell
1989 actually receiving a command line like this:
1992 .B find . \-name bigram.c code.c frcode.c locate.c \-print
1995 That command is of course not going to work. Instead of doing things
1996 this way, you should enclose the pattern in quotes or escape the wildcard:
1998 .B $ find . \-name \e*.c \-print
2003 There are security problems inherent in the behaviour that the POSIX
2004 standard specifies for
2006 which therefore cannot be fixed. For example, the
2009 inherently insecure, and
2011 should be used instead.
2012 Please see \fBFinding Files\fP for more information.
2014 The environment variable
2016 has no effect on the
2020 The best way to report a bug is to use the form at
2021 http://savannah.gnu.org/bugs/?group=findutils.
2022 The reason for this is that you will then be able to track progress in
2023 fixing the problem. Other comments about \fBfind\fP(1) and about
2024 the findutils package in general can be sent to the
2026 mailing list. To join the list, send email to
2027 .IR bug\-findutils\-request@gnu.org .