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 search 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.
259 predicate and specify a filsystem type
261 which is not known (that is, present in `/etc/mtab') at the time
263 starts, that predicate is equivalent to
266 At this optimisation level, the full cost-based query optimiser is
267 enabled. The order of tests is modified so that cheap (i.e. fast)
268 tests are performed first and more expensive ones are performed later,
269 if necessary. Within each cost band, predicates are evaluated earlier
270 or later according to whether they are likely to succeed or not. For
272 predicates which are likely to succeed are evaluated earlier, and for
274 predicates which are likely to fail are evaluated earlier.
277 The cost-based optimiser has a fixed idea of how likely any given test
278 is to succeed. In some cases the probability takes account of the
279 specific nature of the test (for example,
281 is assumed to be more likely to succeed than
283 The cost-based optimiser is currently being evaluated. If it does
284 not actually improve the performance of
286 it will be removed again. Conversely, optimisations that prove to be
287 reliable, robust and effective may be enabled at lower optimisation
288 levels over time. However, the default behaviour (i.e. optimisation
289 level 1) will not be changed in the 4.3.x release series. The
290 findutils test suite runs all the tests on
292 at each optimisation level and ensures that the result is the same.
295 The expression is made up of options (which affect overall operation
296 rather than the processing of a specific file, and always return
297 true), tests (which return a true or false value), and actions (which
298 have side effects and return a true or false value), all separated by
301 is assumed where the operator is omitted.
303 If the expression contains no actions other than
307 performed on all files for which the expression is true.
311 All options always return true. Except for
316 the options affect all tests, including tests specified
317 before the option. This is because the options are processed when the
318 command line is parsed, while the tests don't do anything until files
324 options are different in this respect, and have an effect only on tests which
325 appear later in the command line. Therefore, for clarity, it is best
326 to place them at the beginning of the expression. A warning is issued
327 if you don't do this.
330 A synonym for \-depth, for compatibility with FreeBSD, NetBSD, MacOS X and OpenBSD.
341 from the beginning of today rather than from 24 hours ago. This
342 option only affects tests which appear later on the command line.
345 Process each directory's contents before the directory itself. The
346 \-delete action also implies
352 option instead. Dereference symbolic links.
357 option affects only those tests which
358 appear after it on the command line. Unless the
363 been specified, the position of the
365 option changes the behaviour of the
367 predicate; any files listed as the argument
370 will be dereferenced if they are symbolic links. The same
371 consideration applies to
378 predicate will always match against the type of the file
379 that a symbolic link points to rather than the link itself. Using
384 predicates always to return false.
386 .IP "\-help, \-\-help"
387 Print a summary of the command-line usage of
391 .IP \-ignore_readdir_race
392 Normally, \fBfind\fR will emit an error message when it fails to stat a file.
393 If you give this option and a file is deleted between the time \fBfind\fR
394 reads the name of the file from the directory and the time it tries to stat
395 the file, no error message will be issued. This also applies to files
396 or directories whose names are given on the command line. This option takes
397 effect at the time the command line is read, which means that you cannot search
398 one part of the filesystem with this option on and part of it with this option
399 off (if you need to do that, you will need to issue two \fBfind\fR commands
400 instead, one with the option and one without it).
402 .IP "\-maxdepth \fIlevels\fR"
403 Descend at most \fIlevels\fR (a non-negative integer) levels of
404 directories below the command line arguments.
406 means only apply the tests and actions to the command line arguments.
408 .IP "\-mindepth \fIlevels\fR"
409 Do not apply any tests or actions at levels less than \fIlevels\fR (a
410 non-negative integer).
412 means process all files except the command line arguments.
415 Don't descend directories on other filesystems. An alternate name for
417 for compatibility with some other versions of
420 .IP \-noignore_readdir_race
421 Turns off the effect of
422 .BR \-ignore_readdir_race .
425 Do not optimize by assuming that directories contain 2 fewer
426 subdirectories than their hard link count. This option is needed when
427 searching filesystems that do not follow the Unix directory-link
428 convention, such as CD-ROM or MS-DOS filesystems or AFS volume mount
429 points. Each directory on a normal Unix filesystem has at least 2
430 hard links: its name and its `.' entry. Additionally, its
431 subdirectories (if any) each have a `..' entry linked to that
434 is examining a directory, after it has statted 2 fewer subdirectories
435 than the directory's link count, it knows that the rest of the entries
436 in the directory are non-directories (`leaf' files in the directory
437 tree). If only the files' names need to be examined, there is no need
438 to stat them; this gives a significant increase in search speed.
440 .IP "\-regextype \fItype\fR"
441 Changes the regular expression syntax understood by
445 tests which occur later on the command line. Currently-implemented
446 types are emacs (this is the default), posix-awk, posix-basic,
447 posix-egrep and posix-extended.
449 .IP "\-version, \-\-version"
450 Print the \fBfind\fR version number and exit.
452 .IP "\-warn, \-nowarn"
453 Turn warning messages on or off. These warnings apply only to the
454 command line usage, not to any conditions that
456 might encounter when it searches directories. The default behaviour
459 if standard input is a tty, and to
464 Don't descend directories on other filesystems.
467 Some tests, for example
471 allow comparison between the file currently being examined and some
472 reference file specified on the command line. When these tests are
473 used, the interpretation of the reference file is determined by the
481 but the reference file is only examined once, at the time the command
482 line is parsed. If the reference file cannot be examined (for
485 system call fails for it), an error message is issued, and
487 exits with a nonzero status.
489 Numeric arguments can be specified as
502 File was last accessed \fIn\fR minutes ago.
504 .IP "\-anewer \fIfile\fR"
505 File was last accessed more recently than \fIfile\fR was modified. If
506 \fIfile\fR is a symbolic link and the
510 option is in effect, the access time of the file it points to is
513 .IP "\-atime \fIn\fR"
514 File was last accessed \fIn\fR*24 hours ago.
515 When find figures out how many 24-hour periods ago the file
516 was last accessed, any fractional part is ignored, so to match
519 a file has to have been accessed at least
524 File's status was last changed \fIn\fR minutes ago.
526 .IP "\-cnewer \fIfile\fR"
527 File's status was last changed more recently than \fIfile\fR was
528 modified. If \fIfile\fR is a symbolic link and the
532 option is in effect, the status-change time of the file it points
535 .IP "\-ctime \fIn\fR"
536 File's status was last changed \fIn\fR*24 hours ago.
539 to understand how rounding affects the interpretation of file status
543 File is empty and is either a regular file or a directory.
546 Matches files which are executable and directories which are
547 searchable (in a file name resolution sense). This takes into account
548 access control lists and other permissions artefacts which the
550 test ignores. This test makes use of the
552 system call, and so can be fooled by NFS servers which do UID
553 mapping (or root-squashing), since many systems implement
555 in the client's kernel and so cannot make use of the UID mapping
556 information held on the server. Because this test is based only on
559 system call, there is no guarantee that a file for which this test
560 succeeds can actually be executed.
565 .IP "\-fstype \fItype\fR"
566 File is on a filesystem of type \fItype\fR. The valid filesystem
567 types vary among different versions of Unix; an incomplete list of
568 filesystem types that are accepted on some version of Unix or another
569 is: ufs, 4.2, 4.3, nfs, tmp, mfs, S51K, S52K. You can use
571 with the %F directive to see the types of your filesystems.
574 File's numeric group ID is \fIn\fR.
576 .IP "\-group \fIgname\fR"
577 File belongs to group \fIgname\fR (numeric group ID allowed).
579 .IP "\-ilname \fIpattern\fR"
582 but the match is case insensitive.
587 option is in effect, this test returns false unless the symbolic link
591 .IP "\-iname \fIpattern\fR"
594 but the match is case insensitive. For example, the
595 patterns `fo*' and `F??' match the file names `Foo', `FOO', `foo',
596 `fOo', etc. The pattern `*foo*` will also match a file
600 File has inode number \fIn\fR. It is normally easier to use the
604 .IP "\-ipath \fIpattern\fR"
607 but the match is case insensitive.
609 .IP "\-iregex \fIpattern\fR"
612 but the match is case insensitive.
614 .IP "\-iwholename \fIpattern\fR"
615 See \-ipath. This alternative is less portable than
618 .IP "\-links \fIn\fR"
619 File has \fIn\fR links.
621 .IP "\-lname \fIpattern\fR"
622 File is a symbolic link whose contents match shell pattern
623 \fIpattern\fR. The metacharacters do not treat `/' or `.' specially.
628 option is in effect, this test returns false unless the symbolic link
632 File's data was last modified \fIn\fR minutes ago.
634 .IP "\-mtime \fIn\fR"
635 File's data was last modified \fIn\fR*24 hours ago.
638 to understand how rounding affects the interpretation of file
641 .IP "\-name \fIpattern\fR"
642 Base of file name (the path with the leading directories removed)
643 matches shell pattern \fIpattern\fR. Because the leading directories
644 are removed, the file names considered for a match with
646 will never include a slash, so `\-name a/b' will never match anything
647 (you probably need to use
649 instead). The metacharacters (`*', `?',
650 and `[]') match a `.' at the start of the base name (this is a change
651 in findutils-4.2.2; see section STANDARDS CONFORMANCE below). To ignore a
652 directory and the files under it, use
654 see an example in the
657 Braces are not recognised as being
658 special, despite the fact that some shells including Bash imbue braces
659 with a special meaning in shell patterns. The filename matching is
660 performed with the use of the
662 library function. Don't forget to enclose the pattern in quotes
663 in order to protect it from expansion by the shell.
665 .IP "\-newer \fIfile\fR"
666 File was modified more recently than \fIfile\fR. If \fIfile\fR is a
667 symbolic link and the
671 option is in effect, the
672 modification time of the file it points to is always used.
674 .IP "\-newerXY \fIreference\fR"
675 Compares the timestamp of the current file with \fIreference\fR.
678 argument is normally the name of a file (and one of its timestamps is
679 used for the comparison) but it may also be a string describing an
684 are placeholders for other letters, and these letters select which
688 is used for the comparison.
695 a The access time of the file \fIreference\fR
696 B The birth time of the file \fIreference\fR
697 c The inode status change time of \fIreference\fR
698 m The modification time of the file \fIreference\fR
699 t \fIreference\fR is interpreted directly as a time
702 Some combinations are invalid; for example, it is invalid for
706 Some combinations are not implemented on all systems; for example
708 is not supported on all systems. If an invalid or unsupported
711 is specified, a fatal error results. Time specifications are
712 interpreted as for the argument to the
716 If you try to use the birth time of a reference file, and the birth
717 time cannot be determined, a fatal error message results. If you
718 specify a test which refers to the birth time of files being examined,
719 this test will fail for any files where the birth time is unknown.
722 No group corresponds to file's numeric group ID.
725 No user corresponds to file's numeric user ID.
727 .IP "\-path \fIpattern\fR"
728 File name matches shell pattern \fIpattern\fR. The metacharacters do
729 not treat `/' or `.' specially; so, for example,
732 find . \-path "./sr*sc"
735 will print an entry for a directory called `./src/misc' (if one
736 exists). To ignore a whole directory tree, use
739 checking every file in the tree. For example, to skip the
740 directory `src/emacs' and all files and directories under it, and
741 print the names of the other files found, do something like this:
744 find . \-path ./src/emacs \-prune \-o \-print
747 Note that the pattern match test applies to the whole file name,
748 starting from one of the start points named on the command line. It
749 would only make sense to use an absolute path name here if the
750 relevant start point is also an absolute path. This means that this
751 command will never match anything:
754 find bar \-path /foo/bar/myfile \-print
759 argument with the concatenation of a directory name and the base name
760 of the file it's examining. Since the concatenation will never end
763 arguments ending in a slash will match nothing (except perhaps a start
764 point specified on the command line).
767 is also supported by HP-UX
769 and will be in a forthcoming version of the POSIX standard.
771 .IP "\-perm \fImode\fR"
772 File's permission bits are exactly \fImode\fR (octal or symbolic).
773 Since an exact match is required, if you want to use this form for
774 symbolic modes, you may have to specify a rather complex mode string.
775 For example `\-perm g=w' will only match files which have mode 0020
776 (that is, ones for which group write permission is the only permission
777 set). It is more likely that you will want to use the `/' or `-'
778 forms, for example `\-perm \-g=w', which matches any file with group
779 write permission. See the
781 section for some illustrative examples.
783 .IP "\-perm \-\fImode\fR"
784 All of the permission bits \fImode\fR are set for the file.
785 Symbolic modes are accepted in this form, and this is usually the way
786 in which would want to use them. You must specify `u', `g' or `o' if
787 you use a symbolic mode. See the
789 section for some illustrative examples.
791 .IP "\-perm /\fImode\fR"
792 Any of the permission bits \fImode\fR are set for the file. Symbolic
793 modes are accepted in this form. You must specify `u', `g' or `o' if
794 you use a symbolic mode. See the
796 section for some illustrative examples. If no permission bits in
798 are set, this test matches any file (the idea here is to be consistent
799 with the behaviour of
803 .IP "\-perm +\fImode\fR"
804 Deprecated, old way of searching for files with any of the permission
805 bits in \fImode\fR set. You should use
806 .B \-perm \fI/mode\fR
807 instead. Trying to use the `+' syntax with symbolic modes will yield
808 surprising results. For example, `+u+x' is a valid symbolic mode
809 (equivalent to +u,+x, i.e. 0111) and will therefore not be evaluated
811 .B \-perm +\fImode\fR
812 but instead as the exact mode specifier
814 and so it matches files with exact permissions 0111 instead of files with any
815 execute bit set. If you found this paragraph confusing, you're not
817 .B \-perm /\fImode\fR.
820 test is deprecated because the POSIX specification requires the
821 interpretation of a leading `+' as being part of a symbolic mode, and
822 so we switched to using `/' instead.
825 Matches files which are readable. This takes into account access
826 control lists and other permissions artefacts which the
828 test ignores. This test makes use of the
830 system call, and so can be fooled by NFS servers which do UID
831 mapping (or root-squashing), since many systems implement
833 in the client's kernel and so cannot make use of the UID mapping
834 information held on the server.
836 .IP "\-regex \fIpattern\fR"
837 File name matches regular expression \fIpattern\fR. This is a match
838 on the whole path, not a search. For example, to match a file named
839 `./fubar3', you can use the regular expression `.*bar.' or `.*b.*3',
840 but not `f.*r3'. The regular expressions understood by
842 are by default Emacs Regular Expressions, but this can be
847 .IP "\-samefile \fIname\fR"
848 File refers to the same inode as \fIname\fR. When
850 is in effect, this can include symbolic links.
852 .IP "\-size \fIn\fR[cwbkMG]"
853 File uses \fIn\fP units of space. The following suffixes
857 for 512-byte blocks (this is the default if no suffix is used)
863 for Kilobytes (units of 1024 bytes)
865 for Megabytes (units of 1048576 bytes)
867 for Gigabytes (units of 1073741824 bytes)
870 The size does not count indirect blocks, but it does count blocks in
871 sparse files that are not actually allocated. Bear in mind that the
872 `%k' and `%b' format specifiers of
875 differently. The `b' suffix always denotes 512-byte blocks and never
876 1 Kilobyte blocks, which is different to the behaviour of
883 File is of type \fIc\fR:
886 block (buffered) special
888 character (unbuffered) special
896 symbolic link; this is never true if the
900 option is in effect, unless the symbolic link is broken. If you want
901 to search for symbolic links when
911 File's numeric user ID is \fIn\fR.
914 File was last accessed \fIn\fR days after its status was last changed.
916 .IP "\-user \fIuname\fR"
917 File is owned by user \fIuname\fR (numeric user ID allowed).
919 .IP "\-wholename \fIpattern\fR"
920 See \-path. This alternative is less portable than
924 Matches files which are writable. This takes into account access
925 control lists and other permissions artefacts which the
927 test ignores. This test makes use of the
929 system call, and so can be fooled by NFS servers which do UID
930 mapping (or root-squashing), since many systems implement
932 in the client's kernel and so cannot make use of the UID mapping
933 information held on the server.
935 .IP "\-xtype \fIc\fR"
938 unless the file is a symbolic link. For symbolic
943 option was specified, true if the file is a
944 link to a file of type \fIc\fR; if the
946 option has been given, true
947 if \fIc\fR is `l'. In other words, for symbolic links,
949 checks the type of the file that
952 .IP "\-context \fIpattern\fR"
953 (SELinux only) Security context of the file matches glob \fIpattern\fR.
957 Delete files; true if removal succeeded. If the removal failed, an
958 error message is issued.
963 exit status will be nonzero
964 (when it eventually exits).
967 automatically turns on the
972 Don't forget that the find command line is
973 evaluated as an expression, so putting
977 try to delete everything below the starting points you specified.
980 command line that you later intend to use with
982 you should explicitly specify
984 in order to avoid later surprises. Because
988 you cannot usefully use
994 .IP "\-exec \fIcommand\fR ;"
995 Execute \fIcommand\fR; true if 0 status is returned. All following
998 are taken to be arguments to the command until an argument consisting
999 of `;' is encountered. The string `{}' is replaced by the current
1000 file name being processed everywhere it occurs in the arguments to the
1001 command, not just in arguments where it is alone, as in some versions
1004 Both of these constructions might need to be escaped (with a `\e') or
1005 quoted to protect them from expansion by the shell. See the
1007 section for examples of the use of the
1009 option. The specified
1010 command is run once for each matched file.
1011 The command is executed in the starting directory. There are
1012 unavoidable security problems surrounding use of the
1019 .IP "\-exec \fIcommand\fR {} +"
1022 action runs the specified command on the
1023 selected files, but the command line is built by appending each
1024 selected file name at the end; the total number of invocations of the
1025 command will be much less than the number of matched files. The
1026 command line is built in much the same way that
1028 builds its command lines. Only one instance of `{}' is allowed within
1029 the command. The command is executed in the starting directory.
1031 .IP "\-execdir \fIcommand\fR ;"
1032 .IP "\-execdir \fIcommand\fR {} +"
1035 but the specified command is run from the subdirectory
1036 containing the matched file, which is not normally the directory in
1039 This a much more secure method for invoking commands, as it avoids
1040 race conditions during resolution of the paths to the matched files.
1043 action, the `+' form of
1046 command line to process more than one matched file, but any given
1049 will only list files that exist in the same subdirectory. If you use
1050 this option, you must ensure that your
1052 environment variable does not reference `.';
1053 otherwise, an attacker can run any commands they like by leaving an
1054 appropriately-named file in a directory in which you will run
1056 The same applies to having entries in
1058 which are empty or which are not absolute directory names.
1060 .IP "\-fls \fIfile\fR"
1063 but write to \fIfile\fR like
1065 The output file is always created, even if the predicate is never
1068 .B UNUSUAL FILENAMES
1069 section for information about how unusual characters in filenames are handled.
1071 .IP "\-fprint \fIfile\fR"
1072 True; print the full file name into file \fIfile\fR. If \fIfile\fR
1073 does not exist when \fBfind\fR is run, it is created; if it does
1074 exist, it is truncated. The file names `/dev/stdout' and
1075 `/dev/stderr' are handled specially; they refer to the standard
1076 output and standard error output, respectively.
1077 The output file is always created, even if the predicate is never matched.
1079 .B UNUSUAL FILENAMES
1080 section for information about how unusual characters in filenames are handled.
1082 .IP "\-fprint0 \fIfile\fR"
1085 but write to \fIfile\fR like
1087 The output file is always created, even if the predicate is never matched.
1089 .B UNUSUAL FILENAMES
1090 section for information about how unusual characters in filenames are handled.
1092 .IP "\-fprintf \fIfile\fR \fIformat\fR"
1095 but write to \fIfile\fR like
1097 The output file is always created, even if the predicate is never matched.
1099 .B UNUSUAL FILENAMES
1100 section for information about how unusual characters in filenames are handled.
1103 True; list current file in
1105 format on standard output.
1106 The block counts are of 1K blocks, unless the environment variable
1107 POSIXLY_CORRECT is set, in which case 512-byte blocks are used.
1109 .B UNUSUAL FILENAMES
1110 section for information about how unusual characters in filenames are handled.
1112 .IP "\-ok \fIcommand\fR ;"
1115 but ask the user first. If the user agrees, run the command. Otherwise
1116 just return false. If the command is run, its standard input is redirected
1121 The response to the prompt is matched against a pair of regular
1122 expressions to determine if it is an affirmative or negative
1123 response. This regular expression is obtained from the system if the
1124 `POSIXLY_CORRECT' environment variable is set, or otherwise from
1126 message translations. If the system has no suitable
1129 own definition will be used. In either case, the interpretation of
1130 the regular expression itself will be affected by the environment
1131 variables 'LC_CTYPE' (character classes) and 'LC_COLLATE' (character
1132 ranges and equivalence classes).
1136 .IP "\-okdir \fIcommand\fR ;"
1139 but ask the user first in the same way as for
1141 If the user does not agree, just return false.
1142 If the command is run, its standard input is redirected from
1146 True; print the full file name on the standard output, followed by a
1147 newline. If you are piping the output of
1149 into another program and there is the faintest possibility that the files
1150 which you are searching for might contain a newline, then you should
1151 seriously consider using the
1156 .B UNUSUAL FILENAMES
1157 section for information about how unusual characters in filenames are handled.
1160 True; print the full file name on the standard output, followed by a
1161 null character (instead of the newline character that
1164 This allows file names that contain newlines or other types of white
1165 space to be correctly interpreted by programs that process the
1166 \fBfind\fR output. This option corresponds to the
1171 .IP "\-printf \fIformat\fR"
1172 True; print \fIformat\fR on the standard output, interpreting `\e'
1173 escapes and `%' directives. Field widths and precisions can be
1174 specified as with the `printf' C function. Please note that many of
1175 the fields are printed as %s rather than %d, and this may mean that
1176 flags don't work as you might expect. This also means that the `\-'
1177 flag does work (it forces fields to be left-aligned). Unlike
1180 does not add a newline at the end of the string. The escapes
1188 Stop printing from this format immediately and flush the output.
1202 A literal backslash (`\e').
1204 The character whose ASCII code is NNN (octal).
1206 A `\e' character followed by any other character is treated as an
1207 ordinary character, so they both are printed.
1209 A literal percent sign.
1211 File's last access time in the format returned by the C `ctime' function.
1213 File's last access time in the format specified by \fIk\fR, which is
1214 either `@' or a directive for the C `strftime' function. The possible
1215 values for \fIk\fR are listed below; some of them might not be
1216 available on all systems, due to differences in `strftime' between
1220 seconds since Jan. 1, 1970, 00:00 GMT, with fractional part.
1236 time, 12-hour (hh:mm:ss [AP]M)
1238 Second (00.00 .. 61.00). There is a fractional part.
1240 time, 24-hour (hh:mm:ss)
1242 Date and time, separated by `+', for example
1243 `2004\-04\-28+22:22:05.0'. This is a GNU extension. The time is
1244 given in the current timezone (which may be affected by setting the TZ
1245 environment variable). The seconds field includes a fractional part.
1247 locale's time representation (H:M:S)
1249 time zone (e.g., EDT), or nothing if no time zone is determinable
1253 locale's abbreviated weekday name (Sun..Sat)
1255 locale's full weekday name, variable length (Sunday..Saturday)
1257 locale's abbreviated month name (Jan..Dec)
1259 locale's full month name, variable length (January..December)
1261 locale's date and time (Sat Nov 04 12:02:33 EST 1989). The format is
1264 and so to preserve compatibility with that format, there is no fractional part
1265 in the seconds field.
1267 day of month (01..31)
1273 day of year (001..366)
1277 week number of year with Sunday as first day of week (00..53)
1281 week number of year with Monday as first day of week (00..53)
1283 locale's date representation (mm/dd/yy)
1285 last two digits of year (00..99)
1290 The amount of disk space used for this file in 512-byte blocks. Since disk
1291 space is allocated in multiples of the filesystem block size this is usually
1292 greater than %s/512, but it can also be smaller if the file is a sparse file.
1294 File's last status change time in the format returned by the C `ctime'
1297 File's last status change time in the format specified by \fIk\fR,
1298 which is the same as for %A.
1300 File's depth in the directory tree; 0 means the file is a command line
1303 The device number on which the file exists (the st_dev field of struct
1306 File's name with any leading directories removed (only the last element).
1308 Type of the filesystem the file is on; this value can be used for
1311 File's group name, or numeric group ID if the group has no name.
1313 File's numeric group ID.
1315 Leading directories of file's name (all but the last element).
1316 If the file name contains no slashes (since it is in the current
1317 directory) the %h specifier expands to ".".
1319 Command line argument under which file was found.
1321 File's inode number (in decimal).
1323 The amount of disk space used for this file in 1K blocks. Since disk space is
1324 allocated in multiples of the filesystem block size this is usually greater
1325 than %s/1024, but it can also be smaller if the file is a sparse file.
1327 Object of symbolic link (empty string if file is not a symbolic link).
1329 File's permission bits (in octal). This option uses the `traditional'
1330 numbers which most Unix implementations use, but if your particular
1331 implementation uses an unusual ordering of octal permissions bits, you
1332 will see a difference between the actual value of the file's mode and
1333 the output of %m. Normally you will want to have a leading
1334 zero on this number, and to do this, you should use the
1336 flag (as in, for example, `%#m').
1338 File's permissions (in symbolic form, as for
1340 This directive is supported in findutils 4.2.5 and later.
1342 Number of hard links to file.
1346 File's name with the name of the command line argument under which
1347 it was found removed.
1349 File's size in bytes.
1351 File's sparseness. This is calculated as (BLOCKSIZE*st_blocks /
1352 st_size). The exact value you will get for an ordinary file of a
1353 certain length is system-dependent. However, normally sparse files
1354 will have values less than 1.0, and files which use indirect blocks
1355 may have a value which is greater than 1.0. The value used for
1356 BLOCKSIZE is system-dependent, but is usually 512 bytes. If the file
1357 size is zero, the value printed is undefined. On systems which lack
1358 support for st_blocks, a file's sparseness is assumed to be 1.0.
1360 File's last modification time in the format returned by the C `ctime'
1363 File's last modification time in the format specified by \fIk\fR,
1364 which is the same as for %A.
1366 File's user name, or numeric user ID if the user has no name.
1368 File's numeric user ID.
1370 File's type (like in
1372 U=unknown type (shouldn't happen)
1374 File's type (like %y), plus follow symlinks: L=loop, N=nonexistent
1376 (SELinux only) file's security context.
1378 A `%' character followed by any other character is discarded, but the
1379 other character is printed (don't rely on this, as further format
1380 characters may be introduced). A `%' at the end of the format
1381 argument causes undefined behaviour since there is no following
1382 character. In some locales, it may hide your door keys, while in
1383 others it may remove the final page from the novel you are reading.
1385 The %m and %d directives support the
1391 flags, but the other directives do not, even if they
1392 print numbers. Numeric directives that do not support these flags
1401 The `\-' format flag is supported and changes the alignment of a field
1402 from right-justified (which is the default) to left-justified.
1405 .B UNUSUAL FILENAMES
1406 section for information about how unusual characters in filenames are handled.
1411 True; if the file is a directory, do not descend into it. If
1413 is given, false; no effect. Because
1417 you cannot usefully use
1420 .B \-delete together.
1423 Exit immediately. No child processes will be left running, but no more
1424 paths specified on the command line will be processed. For example,
1425 .B find /tmp/foo /tmp/bar \-print \-quit
1428 Any command lines which have been built up with
1429 .B \-execdir ... {} +
1430 will be invoked before
1432 exits. The exit status may or may not be zero, depending on whether
1433 an error has already occurred.
1435 .SS UNUSUAL FILENAMES
1436 Many of the actions of
1438 result in the printing of data which is under the control of other
1439 users. This includes file names, sizes, modification times and so
1440 forth. File names are a potential problem since they can contain any
1441 character except `\e0' and `/'. Unusual characters in file names can
1442 do unexpected and often undesirable things to your terminal (for
1443 example, changing the settings of your function keys on some
1444 terminals). Unusual characters are handled differently by various
1445 actions, as described below.
1447 .IP "\-print0, \-fprint0\"
1448 Always print the exact filename, unchanged, even if the output is
1449 going to a terminal.
1452 Unusual characters are always escaped. White space, backslash, and
1453 double quote characters are printed using C-style escaping (for
1454 example `\ef', `\e"'). Other unusual characters are printed using an
1455 octal escape. Other printable characters (for
1459 these are the characters between octal 041 and 0176) are printed as-is.
1461 .IP "\-printf, \-fprintf"
1462 If the output is not going to a terminal, it is printed as-is.
1463 Otherwise, the result depends on which directive is in use. The
1464 directives %D, %F, %g, %G, %H, %Y, and %y expand to values which are
1465 not under control of files' owners, and so are printed as-is. The
1466 directives %a, %b, %c, %d, %i, %k, %m, %M, %n, %s, %t, %u and %U have
1467 values which are under the control of files' owners but which cannot
1468 be used to send arbitrary data to the terminal, and so these are
1469 printed as-is. The directives %f, %h, %l, %p and %P are quoted. This
1470 quoting is performed in the same way as for GNU
1472 This is not the same quoting mechanism as the one used for
1476 If you are able to decide what format to use for the output of
1478 then it is normally better to use `\e0' as a terminator
1479 than to use newline, as file names can contain white space and newline
1480 characters. The setting of the `LC_CTYPE' environment
1481 variable is used to determine which characters need to be quoted.
1483 .IP "\-print, \-fprint"
1484 Quoting is handled in the same way as for
1490 in a script or in a situation where the matched files might have
1491 arbitrary names, you should consider using
1500 actions print the current filename as-is. This may change in a future release.
1504 Listed in order of decreasing precedence:
1506 .IP "( \fIexpr\fR )"
1507 Force precedence. Since parentheses are special to the shell, you
1508 will normally need to quote them. Many of the examples in this manual
1509 page use backslashes for this purpose: `\e(...\e)' instead of `(...)'.
1512 True if \fIexpr\fR is false. This character will also usually need
1513 protection from interpretation by the shell.
1515 .IP "\-not \fIexpr\fR"
1516 Same as ! \fIexpr\fR, but not POSIX compliant.
1518 .IP "\fIexpr1 expr2\fR"
1519 Two expressions in a row are taken to be joined with an
1520 implied "and"; \fIexpr2\fR is not evaluated if \fIexpr1\fR is false.
1522 .IP "\fIexpr1\fR \-a \fIexpr2\fR"
1523 Same as \fIexpr1 expr2\fR.
1525 .IP "\fIexpr1\fR \-and \fIexpr2\fR"
1526 Same as \fIexpr1 expr2\fR, but not POSIX compliant.
1528 .IP "\fIexpr1\fR \-o \fIexpr2\fR"
1529 Or; \fIexpr2\fR is not evaluated if \fIexpr1\fR is true.
1531 .IP "\fIexpr1\fR \-or \fIexpr2\fR"
1534 \fIexpr2\fR, but not POSIX compliant.
1536 .IP "\fIexpr1\fR , \fIexpr2\fR"
1537 List; both \fIexpr1\fR and \fIexpr2\fR are always evaluated. The
1538 value of \fIexpr1\fR is discarded; the value of the list is the value
1539 of \fIexpr2\fR. The comma operator can be useful for searching for
1540 several different types of thing, but traversing the filesystem
1541 hierarchy only once. The
1543 action can be used to list the various matched items into several
1544 different output files.
1547 .SH "STANDARDS CONFORMANCE"
1548 For closest compliance to the POSIX standard, you should set the
1549 POSIXLY_CORRECT environment variable. The following options are
1550 specified in the POSIX standard (IEEE Std 1003.1, 2003 Edition):
1553 This option is supported.
1556 This option is supported.
1559 This option is supported, but POSIX conformance depends on the
1560 POSIX conformance of the system's
1562 library function. As of findutils-4.2.2, shell metacharacters
1563 (`*', `?' or `[]' for example) will match a leading `.', because
1564 IEEE PASC interpretation 126 requires this. This is a change from
1565 previous versions of findutils.
1568 Supported. POSIX specifies `b', `c', `d', `l', `p', `f' and `s'.
1569 GNU find also supports `D', representing a Door, where the OS provides these.
1573 Interpretation of the response is according to the "yes" and "no"
1574 patterns selected by setting the `LC_MESSAGES' environment variable.
1575 When the `POSIXLY_CORRECT' environment variable is set, these patterns
1576 are taken system's definition of a positive (yes) or negative (no)
1577 response. See the system's
1578 documentation for \fBnl_langinfo\fP(3), in particular YESEXPR and
1579 NOEXPR. When `POSIXLY_CORRECT' is not set, the patterns are instead
1582 own message catalogue.
1585 Supported. If the file specified is a symbolic link, it is always
1586 dereferenced. This is a change from previous behaviour, which used to
1587 take the relevant time from the symbolic link; see the HISTORY section
1591 Supported. If the POSIXLY_CORRECT environment variable is not set,
1592 some mode arguments (for example +a+x) which are not valid in POSIX
1593 are supported for backward-compatibility.
1595 .IP "Other predicates"
1628 The POSIX standard specifies parentheses `(', `)', negation `!' and the
1629 `and' and `or' operators (
1633 All other options, predicates, expressions and so forth are extensions
1634 beyond the POSIX standard. Many of these extensions are not unique to
1637 The POSIX standard requires that
1643 utility shall detect infinite loops; that is, entering a
1644 previously visited directory that is an ancestor of the last file
1645 encountered. When it detects an infinite loop, find shall write a
1646 diagnostic message to standard error and shall either recover its
1647 position in the hierarchy or terminate.
1651 complies with these requirements. The link count of
1652 directories which contain entries which are hard links to an ancestor
1653 will often be lower than they otherwise should be. This can mean that
1654 GNU find will sometimes optimise away the visiting of a subdirectory
1655 which is actually a link to an ancestor. Since
1657 does not actually enter such a subdirectory, it is allowed to avoid
1658 emitting a diagnostic message. Although this behaviour may be
1659 somewhat confusing, it is unlikely that anybody actually depends on
1660 this behaviour. If the leaf optimisation has been turned off with
1662 the directory entry will always be examined and the diagnostic message
1663 will be issued where it is appropriate. Symbolic links cannot be used
1664 to create filesystem cycles as such, but if the
1668 option is in use, a diagnostic message is issued when
1670 encounters a loop of symbolic links. As with loops containing hard
1671 links, the leaf optimisation will often mean that
1673 knows that it doesn't need to call
1677 on the symbolic link, so this diagnostic is frequently not necessary.
1681 option is supported for compatibility with various BSD systems,
1682 but you should use the POSIX-compliant option
1686 The POSIXLY_CORRECT environment variable does not affect the behaviour
1691 tests because those tests aren't specified in the POSIX standard.
1692 .SH "ENVIRONMENT VARIABLES"
1695 Provides a default value for the internationalization variables that
1699 If set to a non-empty string value, override the values of all the
1700 other internationalization variables.
1703 The POSIX standard specifies that this variable affects the pattern
1704 matching to be used for the
1706 option. GNU find uses the
1708 library function, and so support for `LC_COLLATE' depends on the
1709 system library. This variable also affects the interpretation of
1712 while the `LC_MESSAGES' variable selects the actual pattern used to
1713 interpret the response to
1715 the interpretation of any bracket expressions in the pattern will be
1716 affected by `LC_COLLATE'.
1719 This variable affects the treatment of character classes used in
1720 regular expressions and also with
1723 test, if the system's
1725 library function supports this. This variable also affects the
1726 interpretation of any character classes in the regular expressions
1727 used to interpret the response to the prompt issued by
1729 The `LC_CTYPE' environment variable will
1730 also affect which characters are considered to be unprintable when
1731 filenames are printed; see the section UNUSUAL FILENAMES.
1734 Determines the locale to be used for internationalised messages. If
1735 the `POSIXLY_CORRECT' environment variable is set, this also
1736 determines the interpretation of the response to the prompt made by the
1741 Determines the location of the internationalisation message catalogues.
1744 Affects the directories which are searched to find the executables
1753 Determines the block size used by
1759 is set, blocks are units of 512 bytes. Otherwise they are units of 1024 bytes.
1761 Setting this variable also turns off
1762 warning messages (that is, implies
1764 by default, because POSIX requires that apart from
1767 all messages printed on stderr are diagnostics and must result in a
1768 non-zero exit status.
1770 When POSIXLY_CORRECT is not set,
1773 is treated just like
1777 +zzz is not a valid symbolic mode. When POSIXLY_CORRECT is set, such
1778 constructs are treated as an error.
1780 When POSIXLY_CORRECT is set, the response to the prompt made by the
1782 action is interpreted according to the system's message catalogue, as
1783 opposed to according to
1785 own message translations.
1788 Affects the time zone used for some of the time-related format
1795 .B find /tmp \-name core \-type f \-print | xargs /bin/rm \-f
1800 in or below the directory
1802 and delete them. Note that this will work incorrectly if there are
1803 any filenames containing newlines, single or double quotes, or spaces.
1805 .B find /tmp \-name core \-type f \-print0 | xargs \-0 /bin/rm \-f
1810 in or below the directory
1812 and delete them, processing filenames in such a way that file or
1813 directory names containing single or double quotes, spaces or newlines
1814 are correctly handled. The
1816 test comes before the
1818 test in order to avoid having to call
1824 .B find . \-type f \-exec file \(aq{}\(aq \e\;
1827 Runs `file' on every file in or below the current directory. Notice
1828 that the braces are enclosed in single quote marks to protect them
1829 from interpretation as shell script punctuation. The semicolon is
1830 similarly protected by the use of a backslash, though single quotes
1831 could have been used in that case also.
1835 .B find / \e( \-perm \-4000 \-fprintf /root/suid.txt \(aq%#m %u %p\en\(aq \e) , \e
1836 .B \e( \-size +100M \-fprintf /root/big.txt \(aq%\-10s %p\en\(aq \e)
1839 Traverse the filesystem just once, listing setuid files and
1842 and large files into
1847 .B find $HOME \-mtime 0
1850 Search for files in your home directory which have been modified in
1851 the last twenty-four hours. This command works this way because the
1852 time since each file was last modified is divided by 24 hours and any
1853 remainder is discarded. That means that to match
1856 a file will have to have a modification in the past which is less than
1861 .B find /sbin /usr/sbin -executable \e! -readable \-print
1864 Search for files which are executable but not readable.
1868 .B find . \-perm 664
1871 Search for files which have read and write permission for their owner,
1872 and group, but which other users can read but not write to. Files
1873 which meet these criteria but have other permissions bits set (for
1874 example if someone can execute the file) will not be matched.
1878 .B find . \-perm \-664
1881 Search for files which have read and write permission for their owner
1882 and group, and which other users can read, without regard to the
1883 presence of any extra permission bits (for example the executable
1884 bit). This will match a file which has mode 0777, for example.
1888 .B find . \-perm /222
1891 Search for files which are writable by somebody (their owner, or
1892 their group, or anybody else).
1896 .B find . \-perm /220
1897 .B find . \-perm /u+w,g+w
1898 .B find . \-perm /u=w,g=w
1901 All three of these commands do the same thing, but the first one uses
1902 the octal representation of the file mode, and the other two use the
1903 symbolic form. These commands all search for files which are
1904 writable by either their owner or their group. The files don't have
1905 to be writable by both the owner and group to be matched; either will
1910 .B find . \-perm \-220
1911 .B find . \-perm \-g+w,u+w
1914 Both these commands do the same thing; search for files which are
1915 writable by both their owner and their group.
1919 .B find . \-perm \-444 \-perm /222 ! \-perm /111
1920 .B find . \-perm \-a+r \-perm /a+w ! \-perm /a+x
1923 These two commands both search for files that are readable for
1927 .BR "\-perm \-a+r" ),
1928 have at least one write bit
1933 but are not executable for anybody (
1942 .B find . \-name .snapshot \-prune \-o \e( \e! \-name "*~" \-print0 \e)|
1943 .B cpio \-pmd0 /dest-dir
1946 This command copies the contents of
1950 but omits files and directories named
1952 (and anything in them). It also omits files or directories whose name
1955 but not their contents. The construct
1956 .B \-prune \-o \e( ... \-print0 \e)
1957 is quite common. The idea here is that the expression before
1959 matches things which are to be pruned. However, the
1961 action itself returns true, so the following
1963 ensures that the right hand side is evaluated only for those
1964 directories which didn't get pruned (the contents of the pruned
1965 directories are not even visited, so their contents are irrelevant).
1966 The expression on the right hand side of the
1968 is in parentheses only for clarity. It emphasises that the
1970 action takes place only for things that didn't have
1972 applied to them. Because the default `and' condition between tests
1973 binds more tightly than
1975 this is the default anyway, but the parentheses help to show
1980 .B find repo/ -exec test -d {}/.svn \e; -or \e
1981 .B -exec test -d {}/.git \e; -or -exec test -d {}/CVS \e; \e
1985 Given the following directory of projects and their associated SCM
1986 administrative directories, perform an efficient search for the
1990 .B repo/project1/CVS
1991 .B repo/gnu/project2/.svn
1992 .B repo/gnu/project3/.svn
1993 .B repo/gnu/project3/src/.svn
1994 .B repo/project4/.git
1999 prevents unnecessary descent into directories that have already been
2000 discovered (for example we do not search project3/src because we
2001 already found project3/.svn), but ensures sibling directories
2002 (project2 and project3) are found.
2007 exits with status 0 if all files are processed successfully, greater
2008 than 0 if errors occur. This is deliberately a very broad
2009 description, but if the return value is non-zero, you should not rely
2010 on the correctness of the results of
2014 \fBlocate\fP(1), \fBlocatedb\fP(5), \fBupdatedb\fP(1), \fBxargs\fP(1),
2015 \fBchmod\fP(1), \fBfnmatch\fP(3), \fBregex\fP(7), \fBstat\fP(2),
2016 \fBlstat\fP(2), \fBls\fP(1), \fBprintf\fP(3), \fBstrftime\fP(3),
2017 \fBctime\fP(3), \fBFinding Files\fP (on-line in Info, or printed).
2019 As of findutils-4.2.2, shell metacharacters (`*', `?' or `[]' for
2020 example) used in filename patterns will match a leading `.', because
2021 IEEE POSIX interpretation 126 requires this.
2025 was deprecated in findutils-4.2.21, in favour of
2028 As of findutils-4.3.3,
2030 now matches all files instead of none.
2032 Nanosecond-resolution
2033 timestamps were implemented in findutils-4.3.3.
2035 As of findutils-4.3.11, the
2039 exit status to a nonzero value when it fails.
2042 will not exit immediately. Previously,
2044 exit status was unaffected by the failure of
2048 Feature Added in Also occurs in
2056 \-exec ... + 4.2.12 POSIX
2057 \-execdir 4.2.12 BSD
2068 \-ignore_readdir_race 4.2.0
2077 .B $ find . \-name *.c \-print
2078 find: paths must precede expression
2079 Usage: find [\-H] [\-L] [\-P] [\-Olevel] [\-D help|tree|search|stat|rates|opt|exec] [path...] [expression]
2082 This happens because
2084 has been expanded by the shell
2087 actually receiving a command line like this:
2090 .B find . \-name bigram.c code.c frcode.c locate.c \-print
2093 That command is of course not going to work. Instead of doing things
2094 this way, you should enclose the pattern in quotes or escape the wildcard:
2096 .B $ find . \-name \(aq*.c\(aq \-print
2097 .B $ find . \-name \e*.c \-print
2102 There are security problems inherent in the behaviour that the POSIX
2103 standard specifies for
2105 which therefore cannot be fixed. For example, the
2108 inherently insecure, and
2110 should be used instead.
2111 Please see \fBFinding Files\fP for more information.
2113 The environment variable
2115 has no effect on the
2119 The best way to report a bug is to use the form at
2120 http://savannah.gnu.org/bugs/?group=findutils.
2121 The reason for this is that you will then be able to track progress in
2122 fixing the problem. Other comments about \fBfind\fP(1) and about
2123 the findutils package in general can be sent to the
2125 mailing list. To join the list, send email to
2126 .IR bug\-findutils\-request@gnu.org .