diff options
Diffstat (limited to 'upstream/debian-unstable/man1/find.1')
| -rw-r--r-- | upstream/debian-unstable/man1/find.1 | 2774 |
1 files changed, 2774 insertions, 0 deletions
diff --git a/upstream/debian-unstable/man1/find.1 b/upstream/debian-unstable/man1/find.1 new file mode 100644 index 00000000..6bad0096 --- /dev/null +++ b/upstream/debian-unstable/man1/find.1 @@ -0,0 +1,2774 @@ +'\" t +.TH FIND 1 \" -*- nroff -*- +.SH NAME +find \- search for files in a directory hierarchy +.SH SYNOPSIS +.B find +[\-H] [\-L] [\-P] [\-D debugopts] [\-Olevel] [starting-point...\&] [expression] +. +.SH DESCRIPTION +This manual page +documents the GNU version of +.BR find . +GNU +.B find +searches the directory tree rooted at each given starting-point by +evaluating the given expression from left to right, according to the +rules of precedence (see section OPERATORS), until the outcome is +known (the left hand side is false for \fIand\fR operations, true for +.IR or ), +at which point +.B find +moves on to the next file name. If no starting-point is specified, +`.\&' is assumed. +.PP +If you are using +.B find +in an environment where security is important (for example if you are +using it to search directories that are writable by other users), you +should read the `Security Considerations' chapter of the findutils +documentation, which is called \fBFinding Files\fP and comes with +findutils. +That document also includes a lot more detail +and discussion than this manual page, so you may find it a more useful +source of information. +. +.SH OPTIONS +The +.BR \-H , +.B \-L +and +.B \-P +options control the treatment of symbolic +links. Command-line arguments following these are taken to be names +of files or directories to be examined, up to the first argument that +begins with `\-', or the argument `(' or `!'. That argument and any +following arguments are taken to be the expression describing what is +to be searched for. If no paths are given, the current directory is +used. If no expression is given, the expression +.B \-print +is used +(but you should probably consider using +.B \-print0 +instead, anyway). +.PP +This manual page talks about `options' within the expression list. +These options control the behaviour of +.B find +but are specified immediately after the last path name. The five +`real' options +.BR \-H , +.BR \-L , +.BR \-P , +.B \-D +and +.B \-O +must appear before +the first path name, if at all. A double dash +.B \-\- +could theoretically be used to signal that any remaining arguments +are not options, but this does not really work due to the way +.B find +determines the end of the following path arguments: it does that by reading +until an expression argument comes (which also starts with a `-'). +Now, if a path argument would start with a `-', then +.B find +would treat it as expression argument instead. +Thus, to ensure that all start points are taken as such, and especially to +prevent that wildcard patterns expanded by the calling shell are not mistakenly +treated as expression arguments, it is generally safer to prefix wildcards or +dubious path names with either `./' or to use absolute path names starting +with '/'. +Alternatively, it is generally safe though non-portable to use the GNU option +.B \-files0\-from +to pass arbitrary starting points to +.BR find . + +.IP \-P +Never follow symbolic links. This is the default behaviour. When +.B find +examines or prints information about files, and the file is a symbolic +link, the information used shall be taken from the properties of the +symbolic link itself. + +.IP \-L +Follow symbolic links. When +.B find +examines or prints information about files, the information used shall +be taken from the properties of the file to which the link points, not +from the link itself (unless it is a broken symbolic link or +.B find +is unable to examine the file to which the link points). Use of this +option implies +.BR \-noleaf . +If you later use the +.B \-P +option, +.B \-noleaf +will still be in effect. If +.B \-L +is in effect and +.B find +discovers a symbolic link to a subdirectory during its search, +the subdirectory pointed to by the symbolic link will be searched. +.IP +When the +.B \-L +option is in effect, the +.B \-type +predicate will always +match against the type of the file that a symbolic link points to +rather than the link itself (unless the symbolic link is broken). +Actions that can cause symbolic links to become broken while +.B find +is executing (for example +.BR \-delete ) +can give rise to confusing behaviour. +Using +.B \-L +causes the +.B \-lname +and +.B \-ilname +predicates always to return +false. + +.IP \-H +Do not follow symbolic links, except while processing the command +line arguments. When +.B find +examines or prints information about files, the information used +shall be taken from the properties of the symbolic link itself. +The only exception to this behaviour is when a file specified on the +command line is a symbolic link, +and the link can be resolved. +For that situation, the information used is taken from whatever the +link points to +(that is, the link is followed). +The information about the link itself is used as a fallback if the +file pointed to by the symbolic link cannot be examined. +If +.B \-H +is in effect and one of the +paths specified on the command line is a symbolic link to a directory, +the contents of that directory will be examined (though of course +.B \-maxdepth\ 0 +would prevent this). +.P +If more than one of +.BR \-H , +.B \-L +and +.B \-P +is specified, each overrides the +others; the last one appearing on the command line takes effect. +Since it is the default, the +.B \-P +option should be considered to be in +effect unless either +.B \-H +or +.B \-L +is specified. + +GNU +.B find +frequently stats files during the processing of the command line +itself, before any searching has begun. These options also affect how +those arguments are processed. Specifically, there are a number of +tests that compare files listed on the command line against a file we +are currently considering. In each case, the file specified on the +command line will have been examined and some of its properties will +have been saved. If the named file is in fact a symbolic link, and +the +.B \-P +option is in effect (or if neither +.B \-H +nor +.B \-L +were specified), the information used for the comparison will be taken from +the properties of the symbolic link. Otherwise, it will be taken from +the properties of the file the link points to. If +.B find +cannot follow the link (for example because it has insufficient +privileges or the link points to a nonexistent file) the properties of +the link itself will be used. +.P +When the +.B \-H +or +.B \-L +options are in effect, any symbolic links listed as the argument of +.B \-newer +will be dereferenced, and the timestamp +will be taken from the file to which the symbolic link points. The +same consideration applies to +.BR \-newerXY , +.B \-anewer +and +.BR \-cnewer . + +The +.B \-follow +option has a similar effect to +.BR \-L , +though it takes +effect at the point where it appears (that is, if +.B \-L +is not used but +.B \-follow +is, any symbolic links appearing after +.B \-follow +on the +command line will be dereferenced, and those before it will not). + +.IP "\-D debugopts" +Print diagnostic information; this can be helpful to diagnose problems +with why +.B find +is not doing what you want. The list of debug options should be comma +separated. Compatibility of the debug options is not guaranteed +between releases of findutils. For a complete list of valid debug +options, see the output of +.BR "find \-D\ help" . +Valid debug options include +.RS +.IP exec +Show diagnostic information relating to \-exec, \-execdir, \-ok and \-okdir +.IP opt +Prints diagnostic information relating to the optimisation of the +expression tree; see the \-O option. +.IP rates +Prints a summary indicating how often each predicate succeeded or +failed. +.IP search +Navigate the directory tree verbosely. +.IP stat +Print messages as files are examined with the +.B stat +and +.B lstat +system calls. The +.B find +program tries to minimise such calls. +.IP tree +Show the expression tree in its original and optimised form. +.IP all +Enable all of the other debug options (but +.BR help ). +.IP help +Explain the debugging options. +.RE +.IP \-Olevel +Enables query optimisation. +The +.B find +program reorders tests to speed up execution while preserving the +overall effect; that is, predicates with side effects are not +reordered relative to each other. The optimisations performed at each +optimisation level are as follows. +.RS +.IP 0 +Equivalent to optimisation level 1. +.IP 1 +This is the default optimisation level and corresponds to the +traditional behaviour. Expressions are reordered so that tests based +only on the names of files (for example +.B \-name +and +.BR \-regex ) +are performed first. +.IP 2 +Any +.B \-type +or +.B \-xtype +tests are performed after any tests based only on the names of files, +but before any tests that require information from the inode. On many +modern versions of Unix, file types are returned by +.B readdir() +and so these predicates are faster to evaluate than predicates which +need to stat the file first. +If you use the +.B "\-fstype\ \fIFOO\fR" +predicate and specify a filesystem type +.I FOO +which is not known (that is, present in `/etc/mtab') at the time +.B find +starts, that predicate is equivalent to +.BR \-false . +.IP 3 +At this optimisation level, the full cost-based query optimiser is +enabled. The order of tests is modified so that cheap (i.e.\& fast) +tests are performed first and more expensive ones are performed later, +if necessary. Within each cost band, predicates are evaluated earlier +or later according to whether they are likely to succeed or not. For +.BR \-o , +predicates which are likely to succeed are evaluated earlier, and for +.BR \-a , +predicates which are likely to fail are evaluated earlier. +.RE +.IP +The cost-based optimiser has a fixed idea of how likely any given test +is to succeed. In some cases the probability takes account of the +specific nature of the test (for example, +.B \-type\ f +is assumed to be more likely to succeed than +.BR "\-type\ c" ). +The cost-based optimiser is currently being evaluated. +If it does not actually improve the performance of +.BR find , +it will be removed again. Conversely, optimisations that prove to be +reliable, robust and effective may be enabled at lower optimisation +levels over time. However, the default behaviour (i.e.\& optimisation +level 1) will not be changed in the 4.3.x release series. The +findutils test suite runs all the tests on +.B find +at each optimisation level and ensures that the result is the same. +. +.SH EXPRESSION +The part of the command line after the list of starting points is the +.IR expression . +This is a kind of query specification describing how we match files +and what we do with the files that were matched. +An expression is composed of a sequence of things: + +.IP Tests +Tests return a true or false value, usually on the basis of some +property of a file we are considering. The +.B \-empty +test for example is true only when the current file is empty. + +.IP Actions +Actions have side effects (such as printing something on the standard +output) and return either true or false, usually based on whether or +not they are successful. The +.B \-print +action for example prints the name of the current file on the standard +output. + +.IP "Global options" +Global options affect the operation of tests and actions specified on +any part of the command line. Global options always return true. The +.B \-depth +option for example makes +.B find +traverse the file system in a depth-first order. + +.IP "Positional options" +Positional options affect only tests or actions which follow them. +Positional options always return true. The +.B \-regextype +option for example is positional, specifying the regular expression +dialect for regular expressions occurring later on the command line. + +.IP Operators +Operators join together the other items within the expression. They +include for example +.B \-o +(meaning logical OR) and +.B \-a +(meaning logical AND). Where an operator is missing, +.B \-a +is assumed. + +.P +The +.B \-print +action is performed on all files for which the whole expression is +true, unless it contains an action other than +.B \-prune +or +.BR \-quit . +Actions which inhibit the default +.B \-print +are +.BR \-delete , +.BR \-exec , +.BR \-execdir , +.BR \-ok , +.BR \-okdir , +.BR \-fls , +.BR \-fprint , +.BR \-fprintf , +.BR \-ls , +.B \-print +and +.BR \-printf . + + +The +.B \-delete +action also acts like an option (since it implies +.BR \-depth ). + +.SS POSITIONAL OPTIONS +Positional options always return true. They affect only tests occurring +later on the command line. + +.IP \-daystart +Measure times (for +.BR \-amin , +.BR \-atime , +.BR \-cmin , +.BR \-ctime , +.BR \-mmin , +and +.BR \-mtime ) +from the beginning of today rather than from 24 hours ago. This +option only affects tests which appear later on the command line. + +.IP \-follow +Deprecated; use the +.B \-L +option instead. Dereference symbolic links. +Implies +.BR \-noleaf . +The +.B \-follow +option affects only those tests which +appear after it on the command line. Unless the +.B \-H +or +.B \-L +option has +been specified, the position of the +.B \-follow +option changes the behaviour of the +.B \-newer +predicate; any files listed as the argument +of +.B \-newer +will be dereferenced if they are symbolic links. The same +consideration applies to +.BR \-newerXY , +.B \-anewer +and +.BR \-cnewer . +Similarly, the +.B \-type +predicate will always match against the type of the file +that a symbolic link points to rather than the link itself. Using +.B \-follow +causes the +.B \-lname and +.B \-ilname +predicates always to return false. + +.IP "\-regextype \fItype\fR" +Changes the regular expression syntax understood by +.B \-regex +and +.B \-iregex +tests which occur later on the command line. To see which regular +expression types are known, use +.BR "\-regextype\ help" . +The Texinfo documentation (see +.B SEE +.BR ALSO ) +explains the meaning of and +differences between the various types of regular expression. + +.IP "\-warn, \-nowarn" +Turn warning messages on or off. These warnings apply only to the +command line usage, not to any conditions that +.B find +might encounter when it searches directories. The default behaviour +corresponds to +.B \-warn +if standard input is a tty, and to +.B \-nowarn +otherwise. If a warning message relating to command-line usage is +produced, the exit status of +.B find +is not affected. If the +.B POSIXLY_CORRECT +environment variable is set, and +.B \-warn +is also used, it is not specified which, if any, warnings will be active. + +.SS GLOBAL OPTIONS +Global options always return true. +Global options take effect even for tests which occur earlier on the +command line. To prevent confusion, global options should specified +on the command-line after the list of start points, just before the +first test, positional option or action. +If you specify a global option in some other place, +.B find +will issue a warning message explaining that this can be confusing. + +The global options occur after the list of start points, and so are +not the same kind of option as +.BR \-L , +for example. + +.IP \-d +A synonym for \-depth, for compatibility with FreeBSD, NetBSD, \ +MacOS X and OpenBSD. + +.IP \-depth +Process each directory's contents before the directory itself. The +\-delete action also implies +.BR \-depth . + +.IP "\-files0\-from \fIfile\fR" +Read the starting points from \fIfile\fR instead of getting them on the +command line. +In contrast to the known limitations of passing starting points via arguments +on the command line, namely the limitation of the amount of file names, +and the inherent ambiguity of file names clashing with option names, +using this option allows to safely pass an arbitrary number of starting points +to \fBfind\fR. + +Using this option and passing starting points on the command line is mutually +exclusive, and is therefore not allowed at the same time. + +The \fIfile\fR argument is mandatory. +One can use +.B \-files0\-from\ \- +to read the list of starting points from the \fIstandard input\fR stream, +and e.g. from a pipe. +In this case, the actions +.B \-ok +and +.B \-okdir +are not allowed, because they would obviously interfere with reading from +\fIstandard input\fR in order to get a user confirmation. + +The starting points in \fIfile\fR have to be separated by ASCII NUL characters. +Two consecutive NUL characters, i.e., a starting point with a Zero-length +file name is not allowed and will lead to an error diagnostic followed by +a non-Zero exit code later. + +In the case the given \fIfile\fR is empty, \fBfind\fR does not process any +starting point and therefore will exit immediately after parsing the program +arguments. +This is unlike the standard invocation where \fBfind\fR assumes the current +directory as starting point if no path argument is passed. + +The processing of the starting points is otherwise as usual, e.g. +.B find +will recurse into subdirectories unless otherwise prevented. +To process only the starting points, one can additionally pass +.BR \-maxdepth\ 0 . + +Further notes: +if a file is listed more than once in the input file, it is unspecified +whether it is visited more than once. +If the \fIfile\fR is mutated during the operation of +.BR find , +the result is unspecified as well. +Finally, the seek position within the named \fIfile\fR at the time +.B find +exits, be it with +.B \-quit +or in any other way, is also unspecified. +By "unspecified" here is meant that it may or may not work or do any specific +thing, and that the behavior may change from platform to platform, or from +.B findutils +release to release. + +.IP "\-help, \-\-help" +Print a summary of the command-line usage of +.B find +and exit. + +.IP \-ignore_readdir_race +Normally, \fBfind\fR will emit an error message when it fails to stat a file. +If you give this option and a file is deleted between the time \fBfind\fR +reads the name of the file from the directory and the time it tries to stat +the file, no error message will be issued. +This also applies to files or directories whose names are given on the +command line. +This option takes effect at the time the command line is read, +which means that you cannot search one part of the filesystem with +this option on and part of it with this option off +(if you need to do that, you will need to issue two \fBfind\fR commands +instead, one with the option and one without it). + +Furthermore, +.B find +with the +.B \-ignore_readdir_race +option will ignore errors of the +.B \-delete +action in the case the file has disappeared since the parent directory was read: +it will not output an error diagnostic, and the return code of the +.B \-delete +action will be true. + +.IP "\-maxdepth \fIlevels\fR" +Descend at most \fIlevels\fR (a non-negative integer) levels of +directories below the starting-points. Using +.B \-maxdepth\ 0 +means only apply the tests and actions to the starting-points themselves. + +.IP "\-mindepth \fIlevels\fR" +Do not apply any tests or actions at levels less than \fIlevels\fR (a +non-negative integer). Using +.B \-mindepth\ 1 +means process all files except the starting-points. + +.IP \-mount +Don't descend directories on other filesystems. An alternate name for +.BR \-xdev , +for compatibility with some other versions of +.BR find . + +.IP \-noignore_readdir_race +Turns off the effect of +.BR \-ignore_readdir_race . + +.IP "\-noleaf" +Do not optimize by assuming that directories contain 2 fewer +subdirectories than their hard link count. This option is needed when +searching filesystems that do not follow the Unix directory-link +convention, such as CD-ROM or MS-DOS filesystems or AFS volume mount +points. Each directory on a normal Unix filesystem has at least 2 +hard links: its name and its `.\&' entry. Additionally, its +subdirectories (if any) each have a `..\&' entry linked to that +directory. When +.B find +is examining a directory, after it has statted 2 fewer subdirectories +than the directory's link count, it knows that the rest of the entries +in the directory are non-directories (`leaf' files in the directory +tree). If only the files' names need to be examined, there is no need +to stat them; this gives a significant increase in search speed. + +.IP "\-version, \-\-version" +Print the \fBfind\fR version number and exit. + +.IP \-xdev +Don't descend directories on other filesystems. + +.SS TESTS +Some tests, for example +.B \-newerXY +and +.BR \-samefile , +allow comparison between the file currently being examined and some +reference file specified on the command line. When these tests are +used, the interpretation of the reference file is determined by the +options +.BR \-H , +.B \-L +and +.B \-P +and any previous +.BR \-follow , +but the reference file is only examined once, at the time the command +line is parsed. If the reference file cannot be examined (for +example, the +.BR stat (2) +system call fails for it), an error message is issued, and +.B find +exits with a nonzero status. +.P +A numeric argument \fIn\fR can be specified to tests (like +.BR \-amin , +.BR \-mtime , +.BR \-gid , +.BR \-inum , +.BR \-links , +.BR \-size , +.BR \-uid +and +.BR \-used ) +as +.IP \fI+n\fP +for greater than +.IR n , +.IP \fI\-n\fP +for less than +.IR n , +.IP \fIn\fP +for exactly +.IR n . +. +.P +Supported tests: + +.IP "\-amin \fIn\fR" +File was last accessed less than, more than or exactly \fIn\fR minutes ago. + +.IP "\-anewer \fIreference\fR" +Time of the last access of the current file is more recent than that +of the last data modification of the \fIreference\fR file. +If \fIreference\fR is a symbolic link and the +.B \-H +option or the +.B \-L +option is in effect, then the time of the last data modification of the file +it points to is always used. + +.IP "\-atime \fIn\fR" +File was last accessed less than, more than or exactly +.IR n *24 +hours ago. +When find figures out how many 24-hour periods ago the file +was last accessed, any fractional part is ignored, so to match +.BR "\-atime\ +1" , +a file has to have been accessed at least +.I two +days ago. + +.IP "\-cmin \fIn\fR" +File's status was last changed less than, more than or exactly \fIn\fR minutes +ago. + +.IP "\-cnewer \fIreference\fR" +Time of the last status change of the current file is more recent than that +of the last data modification of the \fIreference\fR file. +If \fIreference\fR is a symbolic link and the +.B \-H +option or the +.B \-L +option is in effect, then the time of the last data modification of the file +it points to is always used. + +.IP "\-ctime \fIn\fR" +File's status was last changed less than, more than or exactly +.IR n *24 +hours ago. +See the comments for +.B \-atime +to understand how rounding affects the interpretation of file status +change times. + +.IP \-empty +File is empty and is either a regular file or a directory. + +.IP \-executable +Matches files which are executable and directories which are +searchable (in a file name resolution sense) by the current user. +This takes into account access control lists and other permissions +artefacts which the +.B \-perm +test ignores. This test makes use of the +.BR access (2) +system call, and so can be fooled by NFS servers which do UID +mapping (or root-squashing), since many systems implement +.BR access (2) +in the client's kernel and so cannot make use of the UID mapping +information held on the server. Because this test is based only on +the result of the +.BR access (2) +system call, there is no guarantee that a file for which this test +succeeds can actually be executed. + +.IP \-false +Always false. + +.IP "\-fstype \fItype\fR" +File is on a filesystem of type +.IR type . +The valid filesystem types vary among different versions of Unix; +an incomplete list of +filesystem types that are accepted on some version of Unix or another +is: ufs, 4.2, 4.3, nfs, tmp, mfs, S51K, S52K. You can use +.B \-printf +with the %F directive to see the types of your filesystems. + +.IP "\-gid \fIn\fR" +File's numeric group ID is less than, more than or exactly +.IR n . + +.IP "\-group \fIgname\fR" +File belongs to group \fIgname\fR (numeric group ID allowed). + +.IP "\-ilname \fIpattern\fR" +Like +.BR \-lname , +but the match is case insensitive. +If the +.B \-L +option or the +.B \-follow +option is in effect, this test returns false unless the symbolic link +is broken. + + +.IP "\-iname \fIpattern\fR" +Like +.BR \-name , +but the match is case insensitive. For example, the +patterns `fo*' and `F??' match the file names `Foo', `FOO', `foo', +`fOo', etc. +The pattern `*foo*` will also match a file called '.foobar'. + +.IP "\-inum \fIn\fR" +File has inode number smaller than, greater than or exactly +.IR n . +It is normally easier to use the +.B \-samefile +test instead. + +.IP "\-ipath \fIpattern\fR" +Like +.BR \-path . +but the match is case insensitive. + +.IP "\-iregex \fIpattern\fR" +Like +.BR \-regex , +but the match is case insensitive. + +.IP "\-iwholename \fIpattern\fR" +See \-ipath. This alternative is less portable than +.BR \-ipath . + +.IP "\-links \fIn\fR" +File has less than, more than or exactly \fIn\fR hard links. + +.IP "\-lname \fIpattern\fR" +File is a symbolic link whose contents match shell pattern +.IR pattern . +The metacharacters do not treat `/' or `.\&' specially. +If the +.B \-L +option or the +.B \-follow +option is in effect, this test returns false unless the symbolic link +is broken. + +.IP "\-mmin \fIn\fR" +File's data was last modified less than, more than or exactly \fIn\fR minutes +ago. + +.IP "\-mtime \fIn\fR" +File's data was last modified less than, more than or exactly +.IR n *24 +hours ago. +See the comments for +.B \-atime +to understand how rounding affects the interpretation of file +modification times. + +.IP "\-name \fIpattern\fR" +Base of file name (the path with the leading directories removed) +matches shell pattern +.IR pattern . +Because the leading directories are removed, +the file names considered for a match with +.B \-name +will never include a slash, so `\-name a/b' will never match anything +(you probably need to use +.B \-path +instead). +A warning is issued if you try to do this, +unless the environment variable +.B POSIXLY_CORRECT +is set. +The metacharacters (`*', `?', +and `[]') match a `.\&' at the start of the base name (this is a change +in findutils-4.2.2; see section STANDARDS CONFORMANCE below). To ignore a +directory and the files under it, use +.B \-prune +rather than checking every file in the tree; +see an example in the description of that action. +Braces are not recognised as being +special, despite the fact that some shells including Bash imbue braces +with a special meaning in shell patterns. The filename matching is +performed with the use of the +.BR fnmatch (3) +library function. +Don't forget to enclose the pattern in quotes in order to protect it +from expansion by the shell. + +.IP "\-newer \fIreference\fR" +Time of the last data modification of the current file is more recent than that +of the last data modification of the \fIreference\fR file. +If \fIreference\fR is a symbolic link and the +.B \-H +option or the +.B \-L +option is in effect, then the time of the last data modification of the file +it points to is always used. + +.IP "\-newerXY \fIreference\fR" +Succeeds if timestamp \fIX\fR of the file being considered is newer +than timestamp \fIY\fR of the file +.IR reference . +The letters \fIX\fR and \fIY\fR can be any of the following letters: + +.TS +ll +ll +ll +ll +llw(2i). +a The access time of the file \fIreference\fR +B The birth time of the file \fIreference\fR +c The inode status change time of \fIreference\fR +m The modification time of the file \fIreference\fR +t \fIreference\fR is interpreted directly as a time +.TE + +Some combinations are invalid; for example, it is invalid for +.I X +to be +.IR t . +Some combinations are not implemented on all systems; for example +.I B +is not supported on all systems. If an invalid or unsupported +combination of +.I XY +is specified, a fatal error results. Time specifications are +interpreted as for the argument to the +.B \-d +option of GNU +.BR date . +If you try to use the birth time of a reference file, and the birth +time cannot be determined, a fatal error message results. If you +specify a test which refers to the birth time of files being examined, +this test will fail for any files where the birth time is unknown. + +.IP \-nogroup +No group corresponds to file's numeric group ID. + +.IP \-nouser +No user corresponds to file's numeric user ID. + +.IP "\-path \fIpattern\fR" +File name matches shell pattern +.IR pattern . +The metacharacters do not treat `/' or `.\&' specially; +so, for example, +.in +4m +.nf +find . \-path \(dq./sr*sc\(dq +.fi +.in +will print an entry for a directory called +.I ./src/misc +(if one exists). To ignore a whole directory tree, use +.B \-prune +rather than +checking every file in the tree. +Note that the pattern match test applies to the whole file name, +starting from one of the start points named on the command line. It +would only make sense to use an absolute path name here if the +relevant start point is also an absolute path. This means that this +command will never match anything: +.br +.in +4m +.nf +find bar \-path /foo/bar/myfile \-print +.fi +.in +Find compares the +.B \-path +argument with the concatenation of a directory name and the base name +of the file it's examining. Since the concatenation will never end +with a slash, +.B \-path +arguments ending in a slash will match nothing (except perhaps a start +point specified on the command line). +The predicate +.B \-path +is also supported by HP-UX +.B find +and is part of the POSIX 2008 standard. + +.IP "\-perm \fImode\fR" +File's permission bits are exactly \fImode\fR (octal or symbolic). +Since an exact match is required, if you want to use this form for +symbolic modes, you may have to specify a rather complex mode string. +For example `\-perm g=w' will only match files which have mode 0020 +(that is, ones for which group write permission is the only permission +set). It is more likely that you will want to use the `/' or `\-' +forms, for example `\-perm \-g=w', which matches any file with group +write permission. See the +.B EXAMPLES +section for some illustrative examples. + +.IP "\-perm \-\fImode\fR" +All of the permission bits \fImode\fR are set for the file. +Symbolic modes are accepted in this form, and this is usually the way +in which you would want to use them. You must specify `u', `g' or `o' if +you use a symbolic mode. +See the +.B EXAMPLES +section for some illustrative examples. + +.IP "\-perm /\fImode\fR" +Any of the permission bits \fImode\fR are set for the file. Symbolic +modes are accepted in this form. You must specify `u', `g' or `o' if +you use a symbolic mode. See the +.B EXAMPLES +section for some illustrative examples. If no permission bits in +.I mode +are set, this test matches any file (the idea here is to be consistent +with the behaviour of +.BR "\-perm\ \-000" ). + +.IP "\-perm +\fImode\fR" +This is no longer supported (and has been deprecated since 2005). Use +.B "\-perm /\fImode\fR" +instead. + +.IP \-readable +Matches files which are readable by the current user. This takes into +account access control lists and other permissions artefacts which the +.B \-perm +test ignores. This test makes use of the +.BR access (2) +system call, and so can be fooled by NFS servers which do UID +mapping (or root-squashing), since many systems implement +.BR access (2) +in the client's kernel and so cannot make use of the UID mapping +information held on the server. + +.IP "\-regex \fIpattern\fR" +File name matches regular expression +.IR pattern . +This is a match on the whole path, not a search. +For example, to match a file named +.IR ./fubar3, +you can use the regular expression `.*bar.\&' or `.*b.*3', +but not `f.*r3'. +The regular expressions understood by +.B find +are by default Emacs Regular Expressions (except that `.' matches +newline), but this can be changed with the +.B \-regextype +option. + +.IP "\-samefile \fIname\fR" +File refers to the same inode as +.IR name . +When +.B \-L +is in effect, this can include symbolic links. + +.IP "\-size \fIn\fR[cwbkMG]" +File uses less than, more than or exactly \fIn\fP units of space, rounding up. +The following suffixes can be used: +.RS +.IP `b' +for 512-byte blocks (this is the default if no suffix is used) +.IP `c' +for bytes +.IP `w' +for two-byte words +.IP `k' +for kibibytes (KiB, units of 1024 bytes) +.IP `M' +for mebibytes (MiB, units of 1024 * 1024 = 1\|048\|576 bytes) +.IP `G' +for gibibytes (GiB, units of 1024 * 1024 * 1024 = 1\|073\|741\|824 bytes) +.RE +.IP +The size is simply the st_size member of the struct stat populated by +the lstat (or stat) system call, rounded up as shown above. +In other words, it's consistent with the result you get for +.BR "ls\ \-l" . +Bear in +mind that the `%k' and `%b' format specifiers of +.B \-printf +handle sparse files +differently. The `b' suffix always denotes 512-byte blocks and never +1024-byte blocks, which is different to the behaviour of +.BR \-ls . +.IP +The + and - prefixes signify greater than and less than, as usual; +i.e., an exact size of \fIn\fR units does not match. +Bear in mind that the size is rounded up to the next unit. +Therefore +.B \-size\ \-1M +is not equivalent to +.BR "\-size\ \-1\|048\|576c" . +The former only matches empty files, the latter matches files from 0 to +1,048,575 bytes. +.IP \-true +Always true. + +.IP "\-type \fIc\fR" +File is of type +.IR c : +.RS +.IP b +block (buffered) special +.IP c +character (unbuffered) special +.IP d +directory +.IP p +named pipe (FIFO) +.IP f +regular file +.IP l +symbolic link; this is never true if the +.B \-L +option or the +.B \-follow +option is in effect, unless the symbolic link is broken. If you want +to search for symbolic links when +.B \-L +is in effect, use +.BR \-xtype . +.IP s +socket +.IP D +door (Solaris) +.RE +.IP +To search for more than one type at once, you can supply the combined list of +type letters separated by a comma `,' (GNU extension). +.IP "\-uid \fIn\fR" +File's numeric user ID is less than, more than or exactly +.IR n . + +.IP "\-used \fIn\fR" +File was last accessed less than, more than or exactly \fIn\fR days after its +status was last changed. + +.IP "\-user \fIuname\fR" +File is owned by user \fIuname\fR (numeric user ID allowed). + +.IP "\-wholename \fIpattern\fR" +See \-path. This alternative is less portable than +.BR \-path . + +.IP "\-writable" +Matches files which are writable by the current user. This takes into +account access control lists and other permissions artefacts which the +.B \-perm +test ignores. This test makes use of the +.BR access (2) +system call, and so can be fooled by NFS servers which do UID +mapping (or root-squashing), since many systems implement +.BR access (2) +in the client's kernel and so cannot make use of the UID mapping +information held on the server. + +.IP "\-xtype \fIc\fR" +The same as +.B \-type +unless the file is a symbolic link. For symbolic +links: if the +.B \-H +or +.B \-P +option was specified, true if the file is a +link to a file of type +.IR c ; +if the +.B \-L +option has been given, true +if \fIc\fR is `l'. In other words, for symbolic links, +.B \-xtype +checks the type of the file that +.B \-type +does not check. +.IP "\-context \fIpattern\fR" +(SELinux only) Security context of the file matches glob +.IR pattern . + +.SS ACTIONS +.IP "\-delete\fR" +Delete files or directories; true if removal succeeded. +If the removal failed, an error message is issued and +.BR find 's +exit status will be nonzero (when it eventually exits). + +.BR Warning : +Don't forget that +.B find +evaluates the command line as an +expression, so putting +.B \-delete +first will make +.B find +try to delete everything below the starting points you specified. + +The use of the +.B \-delete +action on the command line automatically turns on the +.B \-depth +option. +As in turn +.B \-depth +makes +.B \-prune +ineffective, the +.B \-delete +action cannot usefully be combined with +.BR \-prune . + +Often, the user might want to test a find command line with +.B \-print +prior to adding +.B \-delete +for the actual removal run. +To avoid surprising results, it is usually best to remember to use +.B \-depth +explicitly during those earlier test runs. + +The +.B \-delete +action will fail to remove a directory unless it is empty. + +Together with the +.B \-ignore_readdir_race +option, +.B find +will ignore errors of the +.B \-delete +action in the case the file has disappeared since the parent directory was +read: it will not output an error diagnostic, not change the exit code to +nonzero, and the return code of the +.B \-delete +action will be true. + + +.IP "\-exec \fIcommand\fR ;" +Execute +.IR command ; +true if 0 status is returned. All following +arguments to +.B find +are taken to be arguments to the command until an argument consisting +of `;' is encountered. The string `{}' is replaced by the current +file name being processed everywhere it occurs in the arguments to the +command, not just in arguments where it is alone, as in some versions +of +.BR find . +Both of these constructions might need to be escaped (with a `\e') or +quoted to protect them from expansion by the shell. See the +.B EXAMPLES +section for examples of the use of the +.B \-exec +option. The specified +command is run once for each matched file. +The command is executed in the starting directory. +There are unavoidable security problems surrounding use of the +.B \-exec +action; +you should use the +.B \-execdir +option instead. + +.IP "\-exec \fIcommand\fR {} +" +This variant of the +.B \-exec +action runs the specified command on the +selected files, but the command line is built by appending each +selected file name at the end; the total number of invocations of the +command will be much less than the number of matched files. The +command line is built in much the same way that +.B xargs +builds its command lines. Only one instance of `{}' is allowed within +the command, and it must appear at the end, immediately before the `+'; +it needs to be escaped (with a `\e') or quoted to protect it from +interpretation by the shell. +The command is executed in the starting directory. If any invocation +with the `+' form returns a non-zero value as exit status, then +.B find +returns a non-zero exit status. If +.B find +encounters an error, this can sometimes cause an +immediate exit, so some pending commands may not be run +at all. For this reason +.B \-exec\ \fImy-command\fP\ ...\ {}\ +\ \-quit +may not result in +.I my-command +actually being run. This variant of +.B \-exec +always returns true. + +.IP "\-execdir \fIcommand\fR ;" +.IP "\-execdir \fIcommand\fR {} +" +Like +.BR \-exec , +but the specified command is run from the subdirectory +containing the matched file, which is not normally the directory in +which you started +.BR find . +As with \-exec, the {} should be quoted if find is being invoked from +a shell. +This a much more secure method for invoking commands, as it avoids +race conditions during resolution of the paths to the matched files. +As with the +.B \-exec +action, the `+' form of +.B \-execdir +will build a +command line to process more than one matched file, but any given +invocation of +.I command +will only list files that exist in the same subdirectory. If you use +this option, you must ensure that your +.B PATH +environment variable does not reference `.'; +otherwise, an attacker can run any commands they like by leaving an +appropriately-named file in a directory in which you will run +.BR \-execdir . +The same applies to having entries in +.B PATH +which are empty or which are not absolute directory names. If +any invocation with the `+' form returns a non-zero value as exit status, +then +.B find +returns a non-zero exit status. If +.B find +encounters an error, this can sometimes cause an +immediate exit, so some pending commands may not be run +at all. +The result of the action depends on whether the +.B + +or the +.B ; +variant is being used; +.B \-execdir\ \fIcommand\fP\ {}\ + +always returns true, while +.B \-execdir\ \fIcommand\fP\ {}\ ; +returns true only if +.I command +returns 0. + + +.IP "\-fls \fIfile\fR" +True; like +.B \-ls +but write to \fIfile\fR like +.BR \-fprint . +The output file is always created, even if the predicate is never +matched. +See the +.B UNUSUAL FILENAMES +section for information about how unusual characters in filenames are handled. + +.IP "\-fprint \fIfile\fR" +True; print the full file name into file +.IR file . +If \fIfile\fR +does not exist when \fBfind\fR is run, it is created; if it does +exist, it is truncated. The file names +.I /dev/stdout +and +.I /dev/stderr +are handled specially; they refer to the standard +output and standard error output, respectively. +The output file is always created, even if the predicate is never matched. +See the +.B UNUSUAL FILENAMES +section for information about how unusual characters in filenames are handled. + +.IP "\-fprint0 \fIfile\fR" +True; like +.B \-print0 +but write to \fIfile\fR like +.BR \-fprint . +The output file is always created, even if the predicate is never matched. +See the +.B UNUSUAL FILENAMES +section for information about how unusual characters in filenames are handled. + +.IP "\-fprintf \fIfile\fR \fIformat\fR" +True; like +.B \-printf +but write to \fIfile\fR like +.BR \-fprint . +The output file is always created, even if the predicate is never matched. +See the +.B UNUSUAL FILENAMES +section for information about how unusual characters in filenames are handled. + +.IP \-ls +True; list current file in +.B ls \-dils +format on standard output. +The block counts are of 1\ KB blocks, unless the environment variable +.B POSIXLY_CORRECT +is set, in which case 512-byte blocks are used. +See the +.B UNUSUAL FILENAMES +section for information about how unusual characters in filenames are handled. + +.IP "\-ok \fIcommand\fR ;" +Like +.B \-exec +but ask the user first. If the user agrees, run the command. Otherwise +just return false. If the command is run, its standard input is redirected +from +.IR /dev/null . +This action may not be specified together with the +.B \-files0\-from +option. + +.IP +The response to the prompt is matched against a pair of regular +expressions to determine if it is an affirmative or negative +response. This regular expression is obtained from the system if the +.B POSIXLY_CORRECT +environment variable is set, or otherwise from +.BR find 's +message translations. If the system has no suitable +definition, +.BR find 's +own definition will be used. +In either case, the interpretation of the regular expression itself +will be affected by the environment variables +.B LC_CTYPE +(character classes) and +.B LC_COLLATE +(character ranges and equivalence classes). + + + +.IP "\-okdir \fIcommand\fR ;" +Like +.B \-execdir +but ask the user first in the same way as for +.BR \-ok . +If the user does not agree, just return false. +If the command is run, its standard input is redirected from +.IR /dev/null . +This action may not be specified together with the +.B \-files0\-from +option. + + +.IP \-print +True; print the full file name on the standard output, followed by a +newline. +If you are piping the output of +.B find +into another program and there is the faintest possibility that the files +which you are searching for might contain a newline, then you should +seriously consider using the +.B \-print0 +option instead of +.BR \-print . +See the +.B UNUSUAL FILENAMES +section for information about how unusual characters in filenames are handled. + +.IP \-print0 +True; print the full file name on the standard output, followed by a +null character (instead of the newline character that +.B \-print +uses). +This allows file names that contain newlines or other types of white +space to be correctly interpreted by programs that process the +\fBfind\fR output. This option corresponds to the +.B \-0 +option of +.BR xargs . + +.IP "\-printf \fIformat\fR" +True; print \fIformat\fR on the standard output, interpreting `\e' +escapes and `%' directives. Field widths and precisions can be +specified as with the +.BR printf (3) +C function. Please note that many of +the fields are printed as %s rather than %d, and this may mean that +flags don't work as you might expect. This also means that the `\-' +flag does work (it forces fields to be left-aligned). Unlike +.BR \-print , +.B \-printf +does not add a newline at the end of the string. The escapes +and directives are: +.RS +.IP \ea +Alarm bell. +.IP \eb +Backspace. +.IP \ec +Stop printing from this format immediately and flush the output. +.IP \ef +Form feed. +.IP \en +Newline. +.IP \er +Carriage return. +.IP \et +Horizontal tab. +.IP \ev +Vertical tab. +.IP \e0 +ASCII NUL. +.IP \e\e +A literal backslash (`\e'). +.IP \eNNN +The character whose ASCII code is NNN (octal). +.PP +A `\e' character followed by any other character is treated as an +ordinary character, so they both are printed. +.IP %% +A literal percent sign. +.IP %a +File's last access time in the format returned by the C +.BR ctime (3) +function. +.IP %A\fIk\fP +File's last access time in the format specified by +.IR k , +which is either `@' or a directive for the C +.BR strftime (3) +function. +The following shows an incomplete list of possible values for \fIk\fR. +Please refer to the documentation of +.BR strftime (3) +for the full list. +Some of the conversion specification characters might not be available on all systems, +due to differences in the implementation of the +.BR strftime (3) +library function. +.RS +.IP @ +seconds since Jan.\& 1, 1970, 00:00 GMT, with fractional part. +.PP +Time fields: +.IP H +hour (00..23) +.IP I +hour (01..12) +.IP k +hour ( 0..23) +.IP l +hour ( 1..12) +.IP M +minute (00..59) +.IP p +locale's AM or PM +.IP r +time, 12-hour (hh:mm:ss [AP]M) +.IP S +Second (00.00 \&..\& 61.00). There is a fractional part. +.IP T +time, 24-hour (hh:mm:ss.xxxxxxxxxx) +.IP + +Date and time, separated by `+', for example +`2004\-04\-28+22:22:05.0'. This is a GNU extension. The time is +given in the current timezone (which may be affected by setting the +.B TZ +environment variable). The seconds field includes a fractional part. +.IP X +locale's time representation (H:M:S). The seconds field includes a +fractional part. +.IP Z +time zone (e.g., EDT), or nothing if no time zone is determinable +.PP +Date fields: +.IP a +locale's abbreviated weekday name (Sun..Sat) +.IP A +locale's full weekday name, variable length (Sunday..Saturday) +.IP b +locale's abbreviated month name (Jan..Dec) +.IP B +locale's full month name, variable length (January..December) +.IP c +locale's date and time (Sat Nov 04 12:02:33 EST 1989). The format is +the same as for +.BR ctime (3) +and so to preserve compatibility with that format, there is no fractional part +in the seconds field. +.IP d +day of month (01..31) +.IP D +date (mm/dd/yy) +.IP F +date (yyyy-mm-dd) +.IP h +same as b +.IP j +day of year (001..366) +.IP m +month (01..12) +.IP U +week number of year with Sunday as first day of week (00..53) +.IP w +day of week (0..6) +.IP W +week number of year with Monday as first day of week (00..53) +.IP x +locale's date representation (mm/dd/yy) +.IP y +last two digits of year (00..99) +.IP Y +year (1970...\&) +.RE +.IP %b +The amount of disk space used for this file in 512-byte blocks. Since disk +space is allocated in multiples of the filesystem block size this is usually +greater than %s/512, but it can also be smaller if the file is a sparse file. + +.IP %B\fIk\fP +File's birth time, i.e., its creation time, in the format specified by +.IR k , +which is the same as for %A. +This directive produces an empty string if the underlying operating system or +filesystem does not support birth times. + +.IP %c +File's last status change time in the format returned by the C +.BR ctime (3) +function. +.IP %C\fIk\fP +File's last status change time in the format specified by +.IR k , +which is the same as for %A. +.IP %d +File's depth in the directory tree; 0 means the file is a starting-point. +.IP %D +The device number on which the file exists (the st_dev field of struct +stat), in decimal. +.IP %f +Print the basename; the file's name with any leading directories +removed (only the last element). For +.BR / , +the result is `/'. +See the +.B EXAMPLES +section for an example. + +.IP %F +Type of the filesystem the file is on; this value can be used for +\-fstype. +.IP %g +File's group name, or numeric group ID if the group has no name. +.IP %G +File's numeric group ID. +.IP %h +Dirname; the Leading directories of the file's name (all but the last +element). If the file name contains no slashes (since it is in the +current directory) the %h specifier expands to `.'. For files which +are themselves directories and contain a slash (including +.BR / ), +%h expands to the empty string. See the +.B EXAMPLES +section for an example. +.IP %H +Starting-point under which file was found. +.IP %i +File's inode number (in decimal). +.IP %k +The amount of disk space used for this file in 1\ KB blocks. +Since disk space is allocated in multiples of the filesystem block +size this is usually greater than %s/1024, +but it can also be smaller if the file is a sparse file. +.IP %l +Object of symbolic link (empty string if file is not a symbolic link). +.IP %m +File's permission bits (in octal). This option uses the `traditional' +numbers which most Unix implementations use, but if your particular +implementation uses an unusual ordering of octal permissions bits, you +will see a difference between the actual value of the file's mode and +the output of %m. +Normally you will want to have a leading zero on this number, +and to do this, you should use the +.B # +flag (as in, for example, `%#m'). +.IP %M +File's permissions (in symbolic form, as for +.BR ls ). +This directive is supported in findutils 4.2.5 and later. +.IP %n +Number of hard links to file. +.IP %p +File's name. +.IP %P +File's name with the name of the starting-point under which +it was found removed. +.IP %s +File's size in bytes. +.IP %S +File's sparseness. This is calculated as (BLOCKSIZE*st_blocks / +st_size). The exact value you will get for an ordinary file of a +certain length is system-dependent. However, normally sparse files +will have values less than 1.0, and files which use indirect blocks +may have a value which is greater than 1.0. In general the number of +blocks used by a file is file system dependent. +The value used for BLOCKSIZE is system-dependent, but is usually 512 +bytes. +If the file size is zero, the value printed is undefined. +On systems which lack support for st_blocks, +a file's sparseness is assumed to be 1.0. +.IP %t +File's last modification time in the format returned by the C +.BR ctime (3) +function. +.IP %T\fIk\fP +File's last modification time in the format specified by +.IR k , +which is the same as for %A. +.IP %u +File's user name, or numeric user ID if the user has no name. +.IP %U +File's numeric user ID. +.IP %y +File's type (like in +.BR "ls \-l" ), +U=unknown type (shouldn't happen) +.IP %Y +File's type (like %y), plus follow symbolic links: `L'=loop, `N'=nonexistent, +`?' for any other error when determining the type of the target of a symbolic +link. +.IP %Z +(SELinux only) file's security context. +.IP "%{ %[ %(" +Reserved for future use. +.PP +A `%' character followed by any other character is discarded, but the +other character is printed (don't rely on this, as further format +characters may be introduced). A `%' at the end of the format +argument causes undefined behaviour since there is no following +character. In some locales, it may hide your door keys, while in +others it may remove the final page from the novel you are reading. + +The %m and %d directives support the +.BR # , +.B 0 +and +.B + +flags, but the other directives do not, even if they +print numbers. Numeric directives that do not support these flags +include +.BR G , +.BR U , +.BR b , +.BR D , +.B k +and +.BR n . +The `\-' format flag is supported and changes the alignment of a field +from right-justified (which is the default) to left-justified. +.PP +See the +.B UNUSUAL FILENAMES +section for information about how unusual characters in filenames are handled. + + +.RE +.IP \-prune +True; if the file is a directory, do not descend into it. If +.B \-depth +is given, then +.B \-prune +has no effect. Because +.B \-delete +implies +.BR \-depth , +you cannot usefully use +.B \-prune +and +.B \-delete +together. +For example, to skip the directory +.I src/emacs +and all files and directories under it, and print the names of the other files +found, do something like this: +.in +4m +.nf +find . \-path ./src/emacs \-prune \-o \-print +.fi +.in + + +.IP "\-quit" +Exit immediately (with return value zero if no errors have occurred). +This is different to +.B \-prune +because +.B \-prune +only applies to the contents of pruned directories, while +.B \-quit +simply makes +.B find +stop immediately. No child processes will be left +running. Any command lines which have been built by +.B \-exec\ ...\ + +or +.B \-execdir\ ...\ + +are invoked before the program is +exited. After +.B \-quit +is executed, no more files specified on the command line will be +processed. For example, +.RB ` "find\ \fI/tmp/foo\fP\ \fI/tmp/bar\fP\ \-print\ \-quit" ` +will print only `/tmp/foo`. +.br +One common use of +.B \-quit +is to stop searching the file system once we have +found what we want. For example, if we want to find just a single +file we can do this: +.in +4m +.nf +find / -name needle -print -quit +.fi +.in + +.SS OPERATORS +Listed in order of decreasing precedence: + +.IP "( \fIexpr\fR )" +Force precedence. Since parentheses are special to the shell, you +will normally need to quote them. Many of the examples in this manual +page use backslashes for this purpose: `\e(...\e)' instead of `(...)'. + +.IP "! \fIexpr\fR" +True if \fIexpr\fR is false. This character will also usually need +protection from interpretation by the shell. + +.IP "\-not \fIexpr\fR" +Same as !\& +.IR expr , +but not POSIX compliant. + +.IP "\fIexpr1 expr2\fR" +Two expressions in a row are taken to be joined with an +implied +.BR \-a ; +\fIexpr2\fR is not evaluated if \fIexpr1\fR is false. + +.IP "\fIexpr1\fR \-a \fIexpr2\fR" +Same as +.IR "expr1 expr2" . + +.IP "\fIexpr1\fR \-and \fIexpr2\fR" +Same as +.IR "expr1 expr2" , +but not POSIX compliant. + +.IP "\fIexpr1\fR \-o \fIexpr2\fR" +Or; \fIexpr2\fR is not evaluated if \fIexpr1\fR is true. + +.IP "\fIexpr1\fR \-or \fIexpr2\fR" +Same as \fIexpr1\fR +.B \-o +.IR expr2 , +but not POSIX compliant. + +.IP "\fIexpr1\fR , \fIexpr2\fR" +List; both \fIexpr1\fR and \fIexpr2\fR are always evaluated. The +value of \fIexpr1\fR is discarded; the value of the list is the value +of +.IR expr2 . +The comma operator can be useful for searching for +several different types of thing, but traversing the filesystem +hierarchy only once. The +.B \-fprintf +action can be used to list the various matched items into several +different output files. +.P +Please note that +.B \-a +when specified implicitly (for example by two tests appearing without +an explicit operator between them) or explicitly has higher precedence +than +.BR \-o . +This means that +.B find . \-name afile \-o \-name bfile \-print +will never print +.IR afile . +. +.SH UNUSUAL FILENAMES +Many of the actions of +.B find +result in the printing of data which is under the control of other +users. This includes file names, sizes, modification times and so +forth. File names are a potential problem since they can contain any +character except `\e0' and `/'. Unusual characters in file names can +do unexpected and often undesirable things to your terminal (for +example, changing the settings of your function keys on some +terminals). Unusual characters are handled differently by various +actions, as described below. + +.IP "\-print0, \-fprint0" +Always print the exact filename, unchanged, even if the output is +going to a terminal. + +.IP "\-ls, \-fls" +Unusual characters are always escaped. White space, backslash, and +double quote characters are printed using C-style escaping (for +example `\ef', `\e\(dq'). Other unusual characters are printed using an +octal escape. Other printable characters (for +.B \-ls +and +.B \-fls +these are the characters between octal 041 and 0176) are printed as-is. + +.IP "\-printf, \-fprintf" +If the output is not going to a terminal, it is printed as-is. +Otherwise, the result depends on which directive is in use. The +directives %D, %F, %g, %G, %H, %Y, and %y expand to values which are +not under control of files' owners, and so are printed as-is. The +directives %a, %b, %c, %d, %i, %k, %m, %M, %n, %s, %t, %u and %U have +values which are under the control of files' owners but which cannot +be used to send arbitrary data to the terminal, and so these are +printed as-is. The directives %f, %h, %l, %p and %P are quoted. This +quoting is performed in the same way as for GNU +.BR ls . +This is not the same quoting mechanism as the one used for +.B \-ls +and +.BR \-fls . +If you are able to decide what format to use for the output of +.B find +then it is normally better to use `\e0' as a terminator +than to use newline, as file names can contain white space and newline +characters. The setting of the +.B LC_CTYPE +environment variable is used to determine which characters need to be quoted. + +.IP "\-print, \-fprint" +Quoting is handled in the same way as for +.B \-printf +and +.BR \-fprintf . +If you are using +.B find +in a script or in a situation where the matched files might have +arbitrary names, you should consider using +.B \-print0 +instead of +.BR \-print . +.P +The +.B \-ok +and +.B \-okdir +actions print the current filename as-is. This may change in a future release. +. +.SH "STANDARDS CONFORMANCE" +For closest compliance to the POSIX standard, you should set the +.B POSIXLY_CORRECT +environment variable. +The following options are specified in the POSIX standard +(IEEE Std 1003.1-2008, 2016 Edition): + +.IP \fB\-H\fR +This option is supported. + +.IP \fB\-L\fR +This option is supported. + +.IP \fB\-name\fR +This option is supported, but POSIX conformance depends on the +POSIX conformance of the system's +.BR fnmatch (3) +library function. As of findutils-4.2.2, shell metacharacters +(`*', `?' or `[]' for example) match a leading `.', because +IEEE PASC interpretation 126 requires this. +This is a change from previous versions of findutils. + +.IP \fB\-type\fR +Supported. +POSIX specifies `b', `c', `d', `l', `p', `f' and `s'. +GNU find also supports `D', representing a Door, where the OS provides these. +Furthermore, GNU find allows multiple types to be specified at once in a +comma-separated list. + +.IP \fB\-ok\fR +Supported. +Interpretation of the response is according to the `yes' and `no' +patterns selected by setting the +.B LC_MESSAGES +environment variable. +When the +.B POSIXLY_CORRECT +environment variable is set, these patterns are taken system's definition +of a positive (yes) or negative (no) response. +See the system's documentation for +.BR nl_langinfo (3), +in particular YESEXPR and NOEXPR. +When +.B POSIXLY_CORRECT +is not set, the patterns are instead taken from +.BR find 's +own message catalogue. + +.IP \fB\-newer\fR +Supported. If the file specified is a symbolic link, it is always +dereferenced. This is a change from previous behaviour, which used to +take the relevant time from the symbolic link; see the HISTORY section +below. + +.IP \fB\-perm\fR +Supported. If the +.B POSIXLY_CORRECT +environment variable is not set, +some mode arguments (for example +a+x) which are not valid in POSIX +are supported for backward-compatibility. + +.IP "Other primaries" +The primaries +.BR \-atime , +.BR \-ctime , +.BR \-depth , +.BR \-exec , +.BR \-group , +.BR \-links , +.BR \-mtime , +.BR \-nogroup , +.BR \-nouser , +.BR \-ok , +.BR \-path , +.BR \-print , +.BR \-prune , +.BR \-size , +.B \-user +and +.B \-xdev +are all supported. + +.P +The POSIX standard specifies parentheses `(', `)', negation `!' and the +logical AND/OR operators +.B \-a +and +.BR \-o . +.P +All other options, predicates, expressions and so forth are extensions +beyond the POSIX standard. Many of these extensions are not unique to +GNU find, however. +.P +The POSIX standard requires that +.B find +detects loops: +.IP +The +.B find +utility shall detect infinite loops; that is, entering a +previously visited directory that is an ancestor of the last file +encountered. When it detects an infinite loop, find shall write a +diagnostic message to standard error and shall either recover its +position in the hierarchy or terminate. +.P +GNU +.B find +complies with these requirements. The link count of +directories which contain entries which are hard links to an ancestor +will often be lower than they otherwise should be. This can mean that +GNU find will sometimes optimise away the visiting of a subdirectory +which is actually a link to an ancestor. Since +.B find +does not actually enter such a subdirectory, it is allowed to avoid +emitting a diagnostic message. Although this behaviour may be +somewhat confusing, it is unlikely that anybody actually depends on +this behaviour. If the leaf optimisation has been turned off with +.BR \-noleaf , +the directory entry will always be examined and the diagnostic message +will be issued where it is appropriate. Symbolic links cannot be used +to create filesystem cycles as such, but if the +.B \-L +option or the +.B \-follow +option is in use, a diagnostic message is issued when +.B find +encounters a loop of symbolic links. As with loops containing hard +links, the leaf optimisation will often mean that +.B find +knows that it doesn't need to call +.I stat() +or +.I chdir() +on the symbolic link, so this diagnostic is frequently not necessary. +.P +The +.B \-d +option is supported for compatibility with various BSD systems, +but you should use the POSIX-compliant option +.B \-depth +instead. +.P +The +.B POSIXLY_CORRECT +environment variable does not affect the behaviour of the +.B \-regex +or +.B \-iregex +tests because those tests aren't specified in the POSIX standard. +. +.SH "ENVIRONMENT VARIABLES" + +.IP LANG +Provides a default value for the internationalization variables that +are unset or null. + +.IP LC_ALL +If set to a non-empty string value, override the values of all the +other internationalization variables. + +.IP LC_COLLATE +The POSIX standard specifies that this variable affects the pattern +matching to be used for the +.B \-name +option. +GNU find uses the +.BR fnmatch (3) +library function, and so support for +.B LC_COLLATE +depends on the system library. +This variable also affects the interpretation of the response to +.BR \-ok ; +while the +.B LC_MESSAGES +variable selects the actual pattern used to interpret the response to +.BR \-ok , +the interpretation of any bracket expressions in the pattern will be +affected by +.BR LC_COLLATE . + +.IP LC_CTYPE +This variable affects the treatment of character classes used in +regular expressions and also with +the +.B \-name +test, if the system's +.BR fnmatch (3) +library function supports this. This variable also affects the +interpretation of any character classes in the regular expressions +used to interpret the response to the prompt issued by +.BR \-ok . +The +.B LC_CTYPE +environment variable will also affect which characters are considered +to be unprintable when filenames are printed; +see the section UNUSUAL FILENAMES. + +.IP LC_MESSAGES +Determines the locale to be used for internationalised messages. If the +.B POSIXLY_CORRECT +environment variable is set, this also determines the interpretation of +the response to the prompt made by the +.B \-ok +action. + +.IP NLSPATH +Determines the location of the internationalisation message catalogues. + +.IP PATH +Affects the directories which are searched to find the executables +invoked by +.BR \-exec , +.BR \-execdir , +.B \-ok +and +.BR \-okdir . + +.IP POSIXLY_CORRECT +Determines the block size used by +.B \-ls +and +.BR \-fls . +If +.B POSIXLY_CORRECT +is set, blocks are units of 512 bytes. Otherwise they are units of 1024 bytes. +.IP +Setting this variable also turns off +warning messages (that is, implies +.BR \-nowarn ) +by default, because POSIX requires that apart from +the output for +.BR \-ok , +all messages printed on stderr are diagnostics and must result in a +non-zero exit status. +.IP +When +.B POSIXLY_CORRECT +is not set, +.B "\-perm \fI+zzz\fR" +is treated just like +.B "\-perm \fI/zzz\fR" +if +\fI+zzz\fR is not a valid symbolic mode. When +.B POSIXLY_CORRECT +is set, such +constructs are treated as an error. +.IP +When +.B POSIXLY_CORRECT +is set, the response to the prompt made by the +.B \-ok +action is interpreted according to the system's message catalogue, as +opposed to according to +.BR find 's +own message translations. + +.IP TZ +Affects the time zone used for some of the time-related format +directives of +.B \-printf +and +.BR \-fprintf . +. +.SH "EXAMPLES" +.\" A bulleted \[bu] list of examples. +.SS Simple `find|xargs` approach +.IP \[bu] +Find files named +.I core +in or below the directory +.I /tmp +and delete them. +.nf +\& +.in +4m +.B $ find /tmp \-name core \-type f \-print | xargs /bin/rm \-f +.in +\& +.fi +Note that this will work incorrectly if there are +any filenames containing newlines, single or double quotes, or spaces. +. +.SS Safer `find -print0 | xargs -0` approach +.IP \[bu] +Find files named \fIcore\fP in or below the directory \fI/tmp\fP +and delete them, processing filenames in such a way that file or +directory names containing single or double quotes, spaces or newlines +are correctly handled. +.nf +\& +.in +4m +.B $ find /tmp \-name core \-type f \-print0 | xargs \-0 /bin/rm \-f +.in +\& +.fi +The +.B \-name +test comes before the +.B \-type +test in order to avoid having to call +.BR stat (2) +on every file. +.PP +Note that there is still a race between the time +.B find +traverses the hierarchy printing the matching filenames, and the time the +process executed by +.B xargs +works with that file. +. +.SS Processing arbitrary starting points +.IP \[bu] +Given that another program \fIproggy\fR pre-filters and creates a huge +NUL-separated list of files, process those as starting points, and find +all regular, empty files among them: +.nf +\& +.in +4m +.B $ proggy | find \-files0\-from \- \-maxdepth 0 \-type f \-empty +.in +\& +.fi +The use of +.B `\-files0\-from\ \-` +means to read the names of the starting points from \fIstandard input\fR, +i.e., from the pipe; and +.B \-maxdepth\ 0 +ensures that only explicitly those entries are examined without recursing +into directories (in the case one of the starting points is one). +. +.SS +Executing a command for each file +.IP \[bu] +Run +.I file +on every file in or below the current directory. +.nf +\& +.in +4m +.B $ find . \-type f \-exec file \(aq{}\(aq \e; +.in +\& +.fi +Notice that the braces are enclosed in single quote marks to protect them +from interpretation as shell script punctuation. The semicolon is +similarly protected by the use of a backslash, though single quotes +could have been used in that case also. +.PP +In many cases, one might prefer the +.B `\-exec\ \&...\&\ +` +or better the +.B `\-execdir\ \&...\&\ +` +syntax for performance and security reasons. +. +.SS Traversing the filesystem just once - for 2 different actions +.IP \[bu] +Traverse the filesystem just once, listing set-user-ID files and +directories into +.I /root/suid.txt +and large files into +.IR /root/big.txt . +.nf +\& +.in +4m +.B $ find / \e +.in +4m +.B \e( \-perm \-4000 \-fprintf /root/suid.txt \(aq%#m %u %p\en\(aq \e) , \e +.br +.B \e( \-size +100M \-fprintf /root/big.txt \(aq%\-10s %p\en\(aq \e) +.in -4m +.in -4m +\& +.fi +This example uses the line-continuation character \(aq\e\(aq on the first two +lines to instruct the shell to continue reading the command on the next line. +. +.SS +Searching files by age +.IP \[bu] +Search for files in your home directory which have been modified in +the last twenty-four hours. +.nf +\& +.in +4m +.B $ find $HOME \-mtime 0 +.in +\& +.fi +This command works this way because the +time since each file was last modified is divided by 24 hours and any +remainder is discarded. That means that to match +.B \-mtime +.BR 0 , +a file will have to have a modification in the past which is less than +24 hours ago. +. +.SS +Searching files by permissions +.IP \[bu] +Search for files which are executable but not readable. +.nf +\& +.in +4m +.B $ find /sbin /usr/sbin \-executable \e! \-readable \-print +.in +\& +.fi +. +.IP \[bu] +Search for files which have read and write permission for their owner, +and group, but which other users can read but not write to. +.nf +\& +.in +4m +.B $ find . \-perm 664 +.in +\& +.fi +Files which meet these criteria but have other permissions bits set +(for example if someone can execute the file) will not be matched. +. +.IP \[bu] +Search for files which have read and write permission for their owner +and group, and which other users can read, without regard to the +presence of any extra permission bits (for example the executable +bit). +.nf +\& +.in +4m +.B $ find . \-perm \-664 +.in +\& +.fi +This will match a file which has mode +.IR 0777 , +for example. +. +.IP \[bu] +Search for files which are writable by somebody (their owner, or +their group, or anybody else). +.nf +\& +.in +4m +.B $ find . \-perm /222 +.in +\& +.fi +. +.IP \[bu] +Search for files which are writable by either their owner or their group. +.nf +\& +.in +4m +.B $ find . \-perm /220 +.B $ find . \-perm /u+w,g+w +.B $ find . \-perm /u=w,g=w +.in +\& +.fi +All three of these commands do the same thing, but the first one uses +the octal representation of the file mode, and the other two use the +symbolic form. +The files don't have to be writable by both the owner and group to be matched; +either will do. +. +.IP \[bu] +Search for files which are writable by both their owner and their group. +.nf +\& +.in +4m +.B $ find . \-perm \-220 +.B $ find . \-perm \-g+w,u+w +.in +\& +.fi +Both these commands do the same thing. +. +.IP \[bu] +A more elaborate search on permissions. +.nf +\& +.in +4m +.B $ find . \-perm \-444 \-perm /222 \e! \-perm /111 +.B $ find . \-perm \-a+r \-perm /a+w \e! \-perm /a+x +.in +\& +.fi +These two commands both search for files that are readable for everybody +.RB ( "\-perm \-444" +or +.BR "\-perm \-a+r" ), +have at least one write bit +set +.RB ( "\-perm /222" +or +.BR "\-perm /a+w" ) +but are not executable for anybody +.RB ( "! \-perm /111" +or +.B ! \-perm /a+x +respectively). +. +.SS +Pruning - omitting files and subdirectories +.IP \[bu] +Copy the contents of +.I /source-dir +to +.IR /dest-dir , +but omit files and directories named +.I .snapshot +(and anything in them). It also omits files or directories whose name ends in +`\(ti', but not their contents. +.nf +\& +.in +4m +.B $ cd /source-dir +.B $ find . \-name .snapshot \-prune \-o \e( \e! \-name \(aq*~\(aq \-print0 \e) \e +.br +.in +4m +.B | cpio \-pmd0 /dest-dir +.in -4m +.in -4m +\& +.fi +The construct +.B \-prune\ \-o\ \e(\ \&...\&\ \-print0\ \e) +is quite common. The idea here is that the expression before +.B \-prune +matches things which are to be pruned. However, the +.B \-prune +action itself returns true, so the following +.B \-o +ensures that the right hand side is evaluated only for those +directories which didn't get pruned (the contents of the pruned +directories are not even visited, so their contents are irrelevant). +The expression on the right hand side of the +.B \-o +is in parentheses only for clarity. It emphasises that the +.B \-print0 +action takes place only for things that didn't have +.B \-prune +applied to them. Because the default `and' condition between tests +binds more tightly than +.BR \-o , +this is the default anyway, but the parentheses help to show +what is going on. +. +.IP \[bu] +Given the following directory of projects and their associated SCM +administrative directories, perform an efficient search for the +projects' roots: +.nf +\& +.in +4m +.B $ find repo/ \e +.in +4m +.B \e( \-exec test \-d \(aq{}/.svn\(aq \e; \e +.B \-or \-exec test \-d \(aq{}/.git\(aq \e; \e +.B \-or \-exec test \-d \(aq{}/CVS\(aq \e; \e +.B \e) \-print \-prune +.in -4m +.in -4m +\& +.fi +Sample output: +.nf +\& +.in +4m +.B repo/project1/CVS +.B repo/gnu/project2/.svn +.B repo/gnu/project3/.svn +.B repo/gnu/project3/src/.svn +.B repo/project4/.git +.in +\& +.fi +In this example, +.B \-prune +prevents unnecessary descent into directories that have already been +discovered (for example we do not search +.I project3/src +because we already found +.IR project3/.svn ), +but ensures sibling directories +.RI ( project2 +and +.IR project3 ) +are found. +. +.SS +Other useful examples +.IP \[bu] +Search for several file types. +.nf +\& +.in +4m +.B $ find /tmp \-type f,d,l +.in +\& +.fi +Search for files, directories, and symbolic links in the directory +.I /tmp +passing these types as a comma-separated list (GNU extension), +which is otherwise equivalent to the longer, yet more portable: +.nf +\& +.in +4m +.B $ find /tmp \e( \-type f \-o \-type d \-o \-type l \e) +.in +\& +.fi +. +.IP \[bu] +Search for files with the particular name +.I needle +and stop immediately when we find the first one. +.nf +\& +.in +4m +.B $ find / -name needle -print -quit +.in +\& +.fi +. +.IP \[bu] +Demonstrate the interpretation of the +.B %f +and +.B %h +format directives of the +.B \-printf +action for some corner-cases. +Here is an example including some output. +.nf +\& +.in +4m +.B $ find . .. / /tmp /tmp/TRACE compile compile/64/tests/find -maxdepth 0 -printf '[%h][%f]\en' +.B [.][.] +.B [.][..] +.B [][/] +.B [][tmp] +.B [/tmp][TRACE] +.B [.][compile] +.B [compile/64/tests][find] +.in +\& +.fi +. +.SH EXIT STATUS +.B find +exits with status 0 if all files are processed successfully, greater +than 0 if errors occur. +This is deliberately a very broad description, +but if the return value is non-zero, +you should not rely on the correctness of the results of +.BR find . + +When some error occurs, +.B find +may stop immediately, without completing all the actions specified. +For example, some starting points may not have been examined or some +pending program invocations for +.B \-exec\ \&...\&\ {}\ + +or +.B "\-execdir\ \&...\&\ {}\ + +may not have been performed. +. +.SH "HISTORY" +As of findutils-4.2.2, shell metacharacters (`*', `?' or `[]' for +example) used in filename patterns match a leading `.', because +IEEE POSIX interpretation 126 requires this. +.P +As of findutils-4.3.3, +.B \-perm\ /000 +now matches all files instead of none. +.P +Nanosecond-resolution +timestamps were implemented in findutils-4.3.3. +.P +As of findutils-4.3.11, the +.B \-delete +action sets +.BR find 's +exit status to a nonzero value when it fails. +However, +.B find +will not exit immediately. Previously, +.BR find 's +exit status was unaffected by the failure of +.BR \-delete . +.TS +l l l . +Feature Added in Also occurs in +\-files0\-from 4.9.0 +\-newerXY 4.3.3 BSD +\-D 4.3.1 +\-O 4.3.1 +\-readable 4.3.0 +\-writable 4.3.0 +\-executable 4.3.0 +\-regextype 4.2.24 +\-exec ... + 4.2.12 POSIX +\-execdir 4.2.12 BSD +\-okdir 4.2.12 +\-samefile 4.2.11 +\-H 4.2.5 POSIX +\-L 4.2.5 POSIX +\-P 4.2.5 BSD +\-delete 4.2.3 +\-quit 4.2.3 +\-d 4.2.3 BSD +\-wholename 4.2.0 +\-iwholename 4.2.0 +\-ignore_readdir_race 4.2.0 +\-fls 4.0 +\-ilname 3.8 +\-iname 3.8 +\-ipath 3.8 +\-iregex 3.8 +.TE +.P +The syntax +\.B \-perm +MODE +was removed in findutils-4.5.12, in favour of +\.B \-perm +.BR /MODE . +The +.B +MODE +syntax had been deprecated since findutils-4.2.21 +which was released in 2005. +. +.SH "NON-BUGS" +.SS Operator precedence surprises +The command +.B find . \-name afile \-o \-name bfile \-print +will never print +.I afile +because this is actually equivalent to +.BR "find . \-name afile \-o \e( \-name bfile \-a \-print \e)" . +Remember that the precedence of +.B \-a +is higher than that of +.B \-o +and when there is no operator specified between tests, +.B \-a +is assumed. +.SS \(lqpaths must precede expression\(rq error message +.nf +.B $ find . \-name *.c \-print +find: paths must precede expression +find: possible unquoted pattern after predicate `-name'? +.fi +.P +This happens when the shell could expand the pattern +.I *.c +to more than one file name existing in the current directory, +and passing the resulting file names in the command line to +.B find +like this: +.nf +. +.B find . \-name frcode.c locate.c word_io.c \-print +. +.fi +That command is of course not going to work, because the +.B \-name +predicate allows exactly only one pattern as argument. Instead of doing things +this way, you should enclose the pattern in quotes or escape the wildcard, thus +allowing +.B find +to use the pattern with the wildcard during the search for file name matching +instead of file names expanded by the parent shell: +.nf +.B $ find . \-name \(aq*.c\(aq \-print +.B $ find . \-name \e*.c \-print +.fi +. +.SH "BUGS" +There are security problems inherent in the behaviour that the POSIX +standard specifies for +.BR find , +which therefore cannot be fixed. For example, the +.B \-exec +action is +inherently insecure, and +.B \-execdir +should be used instead. +. +.P +The environment variable +.B LC_COLLATE +has no effect on the +.B \-ok +action. +. +.SH "REPORTING BUGS" +GNU findutils online help: <https://www.gnu.org/software/findutils/#get-help> +.br +Report any translation bugs to <https://translationproject.org/team/> +.PP +Report any other issue via the form at the GNU Savannah bug tracker: +.RS +<https://savannah.gnu.org/bugs/?group=findutils> +.RE +General topics about the GNU findutils package are discussed at the +.I bug\-findutils +mailing list: +.RS +<https://lists.gnu.org/mailman/listinfo/bug-findutils> +.RE +. +.SH COPYRIGHT +Copyright \(co 1990-2022 Free Software Foundation, Inc. +License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>. +.br +This is free software: you are free to change and redistribute it. +There is NO WARRANTY, to the extent permitted by law. +. +.SH "SEE ALSO" +.BR chmod (1), +.BR locate (1), +.BR ls (1), +.BR updatedb (1), +.BR xargs (1), +.BR lstat (2), +.BR stat (2), +.BR ctime (3) +.BR fnmatch (3), +.BR printf (3), +.BR strftime (3), +.BR locatedb (5), +.BR regex (7) +.PP +Full documentation <https://www.gnu.org/software/findutils/find> +.br +or available locally via: +.B info find |