mirror of
https://https.git.savannah.gnu.org/git/findutils.git
synced 2026-01-26 07:37:52 +00:00
0193dbcda2
Patch contributed via http://bugs.debian.org/726870 * find/find.1: A full stop (.) that starts or ends a string and is a part of it, is now protected with \& and the space between some sentences has been reduced or increased. Copyright-paperwork-exempt: Yes
2221 lines
63 KiB
Groff
2221 lines
63 KiB
Groff
.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
|
|
\fIor\fR), 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 \-\-
|
|
can also be used
|
|
to signal that any remaining arguments are not options (though
|
|
ensuring that all start points begin with either `./' or `/' is
|
|
generally safer if you use wildcards in the list of start points).
|
|
.IP \-P
|
|
Never follow symbolic links. This is the default behaviour. When
|
|
.B find
|
|
examines or prints information a file, 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
|
|
\-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 debugoptions"
|
|
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
|
|
.B find \-D
|
|
.BR help .
|
|
Valid debug options include
|
|
.RS
|
|
.IP help
|
|
Explain the debugging options
|
|
.IP tree
|
|
Show the expression tree in its original and optimised form.
|
|
.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 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.
|
|
.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
|
|
.I FOO
|
|
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.
|
|
.P
|
|
.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 optiona 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 regulat 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
|
|
If the whole expression contains no actions other than
|
|
.B \-prune
|
|
or
|
|
.BR \-print ,
|
|
.B \-print
|
|
is performed on all files for which the whole expression is true.
|
|
|
|
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
|
|
.B -regextype
|
|
.BR 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 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 occurr 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 "\-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).
|
|
|
|
.IP "\-maxdepth \fIlevels\fR"
|
|
Descend at most \fIlevels\fR (a non-negative integer) levels of
|
|
directories below the starting-points.
|
|
.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).
|
|
.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
|
|
Numeric arguments can be specified 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
|
|
|
|
.IP "\-amin \fIn\fR"
|
|
File was last accessed \fIn\fR minutes ago.
|
|
|
|
.IP "\-anewer \fIfile\fR"
|
|
File was last accessed more recently than \fIfile\fR was modified. If
|
|
\fIfile\fR is a symbolic link and the
|
|
.B \-H
|
|
option or the
|
|
.B \-L
|
|
option is in effect, the access time of the file it points to is
|
|
always used.
|
|
|
|
.IP "\-atime \fIn\fR"
|
|
File was last accessed \fIn\fR*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
|
|
.B \-atime
|
|
.BR +1 ,
|
|
a file has to have been accessed at least
|
|
.I two
|
|
days ago.
|
|
|
|
.IP "\-cmin \fIn\fR"
|
|
File's status was last changed \fIn\fR minutes ago.
|
|
|
|
.IP "\-cnewer \fIfile\fR"
|
|
File's status was last changed more recently than \fIfile\fR was
|
|
modified. If \fIfile\fR is a symbolic link and the
|
|
.B \-H
|
|
option or the
|
|
.B \-L
|
|
option is in effect, the status-change time of the file it points
|
|
to is always used.
|
|
|
|
.IP "\-ctime \fIn\fR"
|
|
File's status was last changed \fIn\fR*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). 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 \fItype\fR. 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 \fIn\fR.
|
|
|
|
.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 \fIn\fR. 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 \fIn\fR links.
|
|
|
|
.IP "\-lname \fIpattern\fR"
|
|
File is a symbolic link whose contents match shell pattern
|
|
\fIpattern\fR. 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 \fIn\fR minutes ago.
|
|
|
|
.IP "\-mtime \fIn\fR"
|
|
File's data was last modified \fIn\fR*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 \fIpattern\fR. 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
|
|
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
|
|
.BR \-prune ;
|
|
see an example in the
|
|
description of
|
|
.BR \-path .
|
|
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 \fIfile\fR"
|
|
File was modified more recently than \fIfile\fR. If \fIfile\fR is a
|
|
symbolic link and the
|
|
.B \-H
|
|
option or the
|
|
.B \-L
|
|
option is in effect, the
|
|
modification time 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 \fIreference\fR. 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 \fIpattern\fR. The metacharacters do
|
|
not treat `/' or `.' specially; so, for example,
|
|
.br
|
|
.in +1i
|
|
find . \-path "./sr*sc"
|
|
.br
|
|
.in -1i
|
|
will print an entry for a directory called `./src/misc' (if one
|
|
exists). To ignore a whole directory tree, use
|
|
.B \-prune
|
|
rather than
|
|
checking every file in the tree. For example, to skip the
|
|
directory `src/emacs' and all files and directories under it, and
|
|
print the names of the other files found, do something like this:
|
|
.br
|
|
.in +1i
|
|
find . \-path ./src/emacs \-prune \-o \-print
|
|
.br
|
|
.in -1i
|
|
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 +1i
|
|
find bar \-path /foo/bar/myfile \-print
|
|
.br
|
|
.in -1i
|
|
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 will be in a forthcoming version of the POSIX 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
|
|
.B \-perm
|
|
.BR \-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. 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 \fIpattern\fR. This is a match
|
|
on the whole path, not a search. For example, to match a file named
|
|
`./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, but this can be
|
|
changed with the
|
|
.B \-regextype
|
|
option.
|
|
|
|
.IP "\-samefile \fIname\fR"
|
|
File refers to the same inode as \fIname\fR. When
|
|
.B \-L
|
|
is in effect, this can include symbolic links.
|
|
|
|
.IP "\-size \fIn\fR[cwbkMG]"
|
|
File uses \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 Kilobytes (units of 1024 bytes)
|
|
.IP `M'
|
|
for Megabytes (units of 1048576 bytes)
|
|
.IP `G'
|
|
for Gigabytes (units of 1073741824 bytes)
|
|
.RE
|
|
.IP
|
|
The size does not count indirect blocks, but it does count blocks in
|
|
sparse files that are not actually allocated. 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
|
|
1 Kilobyte blocks, which is different to the behaviour of
|
|
.BR \-ls .
|
|
The + and - prefixes signify greater than and less than, as usual,
|
|
but bear in mind that the size is rounded up to the next unit (so a
|
|
1-byte file is not matched by
|
|
.BR "-size -1M" ).
|
|
.IP \-true
|
|
Always true.
|
|
|
|
.IP "\-type \fIc\fR"
|
|
File is of type \fIc\fR:
|
|
.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 "\-uid \fIn\fR"
|
|
File's numeric user ID is \fIn\fR.
|
|
|
|
.IP "\-used \fIn\fR"
|
|
File was last accessed \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. 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 \fIc\fR; 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 \fIpattern\fR.
|
|
|
|
.SS ACTIONS
|
|
.IP "\-delete\fR"
|
|
Delete files; true if removal succeeded. If the removal failed, an
|
|
error message is issued.
|
|
If
|
|
.B \-delete
|
|
fails,
|
|
.BR find 's
|
|
exit status will be nonzero
|
|
(when it eventually exits).
|
|
Use of
|
|
.B \-delete
|
|
automatically turns on the
|
|
.RB ` \-depth '
|
|
option.
|
|
|
|
.BR Warnings :
|
|
Don't forget that the find command line is
|
|
evaluated as an expression, so putting
|
|
.B \-delete
|
|
first will make
|
|
.B find
|
|
try to delete everything below the starting points you specified.
|
|
When testing a
|
|
.B find
|
|
command line that you later intend to use with
|
|
.BR \-delete ,
|
|
you should explicitly specify
|
|
.B \-depth
|
|
in order to avoid later surprises. Because
|
|
.B \-delete
|
|
implies
|
|
.BR \-depth ,
|
|
you cannot usefully use
|
|
.B \-prune
|
|
and
|
|
.B \-delete
|
|
together.
|
|
|
|
.IP "\-exec \fIcommand\fR ;"
|
|
Execute \fIcommand\fR; 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. The command is executed in the starting directory. If
|
|
.B find
|
|
encounters an error, this can sometimes cause an
|
|
immediate exit, so some pending commands may not be run
|
|
at all. 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 .
|
|
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
|
|
.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
|
|
.I command
|
|
.B {} +
|
|
always returns true, while
|
|
.B \-execdir
|
|
.I command
|
|
.B {} ;
|
|
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 \fIfile\fR. If \fIfile\fR
|
|
does not exist when \fBfind\fR is run, it is created; if it does
|
|
exist, it is truncated. The file names `/dev/stdout' and
|
|
`/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 1K blocks, unless the environment variable
|
|
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
|
|
.BR /dev/null .
|
|
|
|
.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
|
|
`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 'LC_CTYPE' (character classes) and '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
|
|
.BR /dev/null .
|
|
|
|
.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 `printf' 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 `ctime' function.
|
|
.IP %A\fIk\fP
|
|
File's last access time in the format specified by \fIk\fR, which is
|
|
either `@' or a directive for the C `strftime' function. The possible
|
|
values for \fIk\fR are listed below; some of them might not be
|
|
available on all systems, due to differences in `strftime' between
|
|
systems.
|
|
.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)
|
|
.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 TZ
|
|
environment variable). The seconds field includes a fractional part.
|
|
.IP X
|
|
locale's time representation (H:M:S)
|
|
.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 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 %c
|
|
File's last status change time in the format returned by the C `ctime'
|
|
function.
|
|
.IP %C\fIk\fP
|
|
File's last status change time in the format specified by \fIk\fR,
|
|
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
|
|
File's name with any leading directories removed (only the last element).
|
|
.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
|
|
Leading directories of 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 ".".
|
|
.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 1K 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. 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 `ctime'
|
|
function.
|
|
.IP %T\fIk\fP
|
|
File's last modification time in the format specified by \fIk\fR,
|
|
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 symlinks: L=loop, N=nonexistent
|
|
.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
|
|
.B #
|
|
,
|
|
.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, false; no effect. Because
|
|
.B \-delete
|
|
implies
|
|
.BR \-depth ,
|
|
you cannot usefully use
|
|
.B \-prune
|
|
and
|
|
.B \-delete
|
|
together.
|
|
|
|
.IP "\-quit"
|
|
Exit immediately. No child processes will be left running, but no more
|
|
paths specified on the command line will be processed. For example,
|
|
.B find /tmp/foo /tmp/bar \-print \-quit
|
|
will print only
|
|
.BR /tmp/foo .
|
|
Any command lines which have been built up with
|
|
.B \-execdir \&...\& {} +
|
|
will be invoked before
|
|
.B find
|
|
exits. The exit status may or may not be zero, depending on whether
|
|
an error has already occurred.
|
|
|
|
.SS OPERATORS
|
|
.P
|
|
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 ! \fIexpr\fR, but not POSIX compliant.
|
|
|
|
.IP "\fIexpr1 expr2\fR"
|
|
Two expressions in a row are taken to be joined with an
|
|
implied "and"; \fIexpr2\fR is not evaluated if \fIexpr1\fR is false.
|
|
|
|
.IP "\fIexpr1\fR \-a \fIexpr2\fR"
|
|
Same as \fIexpr1 expr2\fR.
|
|
|
|
.IP "\fIexpr1\fR \-and \fIexpr2\fR"
|
|
Same as \fIexpr1 expr2\fR, 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
|
|
\fIexpr2\fR, 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 \fIexpr2\fR. 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.
|
|
|
|
|
|
.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"'). 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 `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
|
|
POSIXLY_CORRECT environment variable. The following options are
|
|
specified in the POSIX standard (IEEE Std 1003.1, 2003 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) will 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.
|
|
|
|
.IP \fB\-ok\fR
|
|
Supported.
|
|
Interpretation of the response is according to the "yes" and "no"
|
|
patterns selected by setting the `LC_MESSAGES' environment variable.
|
|
When the `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 \fBnl_langinfo\fP(3), in particular YESEXPR and
|
|
NOEXPR. When `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 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 predicates"
|
|
The predicates
|
|
.BR \-atime ,
|
|
.BR \-ctime ,
|
|
.BR \-depth ,
|
|
.BR \-group ,
|
|
.BR \-links ,
|
|
.BR \-mtime ,
|
|
.BR \-nogroup ,
|
|
.BR \-nouser ,
|
|
.BR \-print ,
|
|
.BR \-prune ,
|
|
.BR \-size ,
|
|
.BR \-user
|
|
and
|
|
.B \-xdev
|
|
`\-atime',
|
|
`\-ctime',
|
|
`\-depth',
|
|
`\-group',
|
|
`\-links',
|
|
`\-mtime',
|
|
`\-nogroup',
|
|
`\-nouser',
|
|
`\-perm',
|
|
`\-print',
|
|
`\-prune',
|
|
`\-size',
|
|
`\-user' and
|
|
`\-xdev',
|
|
are all supported.
|
|
|
|
.P
|
|
The POSIX standard specifies parentheses `(', `)', negation `!' and the
|
|
`and' and `or' operators (
|
|
.BR \-a ,
|
|
.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 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 `LC_COLLATE' depends on the
|
|
system library. This variable also affects the interpretation of
|
|
the response to
|
|
.BR \-ok;
|
|
while the `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 `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 `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 `POSIXLY_CORRECT' environment variable is set, this also
|
|
determines the interpretation of the response to the prompt made by the
|
|
.BR \-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 POSIXLY_CORRECT is not set,
|
|
.B \-perm
|
|
+zzz
|
|
is treated just like
|
|
.B \-perm
|
|
/zzz
|
|
if
|
|
+zzz is not a valid symbolic mode. When POSIXLY_CORRECT is set, such
|
|
constructs are treated as an error.
|
|
.IP
|
|
When 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"
|
|
.nf
|
|
.B find /tmp \-name core \-type f \-print | xargs /bin/rm \-f
|
|
|
|
.fi
|
|
Find files named
|
|
.B core
|
|
in or below the directory
|
|
.B /tmp
|
|
and delete them. Note that this will work incorrectly if there are
|
|
any filenames containing newlines, single or double quotes, or spaces.
|
|
.P
|
|
.B find /tmp \-name core \-type f \-print0 | xargs \-0 /bin/rm \-f
|
|
|
|
.fi
|
|
Find files named
|
|
.B core
|
|
in or below the directory
|
|
.B /tmp
|
|
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. The
|
|
.B \-name
|
|
test comes before the
|
|
.B \-type
|
|
test in order to avoid having to call
|
|
.B stat(2)
|
|
on every file.
|
|
|
|
.P
|
|
.nf
|
|
.B find . \-type f \-exec file \(aq{}\(aq \e;
|
|
|
|
.fi
|
|
Runs `file' on every file in or below the current directory. 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.
|
|
|
|
.P
|
|
.nf
|
|
.B find / \e( \-perm \-4000 \-fprintf /root/suid.txt \(aq%#m %u %p\en\(aq \e) , \e
|
|
.B \e( \-size +100M \-fprintf /root/big.txt \(aq%\-10s %p\en\(aq \e)
|
|
|
|
.fi
|
|
Traverse the filesystem just once, listing setuid files and
|
|
directories into
|
|
.B /root/suid.txt
|
|
and large files into
|
|
.BR /root/big.txt .
|
|
|
|
.P
|
|
.nf
|
|
.B find $HOME \-mtime 0
|
|
|
|
.fi
|
|
Search for files in your home directory which have been modified in
|
|
the last twenty-four hours. 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.
|
|
|
|
.P
|
|
.nf
|
|
.B find /sbin /usr/sbin -executable \e! -readable \-print
|
|
|
|
.fi
|
|
Search for files which are executable but not readable.
|
|
|
|
.P
|
|
.nf
|
|
.B find . \-perm 664
|
|
|
|
.fi
|
|
Search for files which have read and write permission for their owner,
|
|
and group, but which other users can read but not write to. Files
|
|
which meet these criteria but have other permissions bits set (for
|
|
example if someone can execute the file) will not be matched.
|
|
|
|
.P
|
|
.nf
|
|
.B find . \-perm \-664
|
|
|
|
.fi
|
|
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). This will match a file which has mode 0777, for example.
|
|
|
|
.P
|
|
.nf
|
|
.B find . \-perm /222
|
|
|
|
.fi
|
|
Search for files which are writable by somebody (their owner, or
|
|
their group, or anybody else).
|
|
|
|
.P
|
|
.nf
|
|
.B find . \-perm /220
|
|
.B find . \-perm /u+w,g+w
|
|
.B find . \-perm /u=w,g=w
|
|
|
|
.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. These commands all search for files which are
|
|
writable by either their owner or their group. The files don't have
|
|
to be writable by both the owner and group to be matched; either will
|
|
do.
|
|
|
|
.P
|
|
.nf
|
|
.B find . \-perm \-220
|
|
.B find . \-perm \-g+w,u+w
|
|
|
|
.fi
|
|
Both these commands do the same thing; search for files which are
|
|
writable by both their owner and their group.
|
|
|
|
.P
|
|
.nf
|
|
.B find . \-perm \-444 \-perm /222 ! \-perm /111
|
|
.B find . \-perm \-a+r \-perm /a+w ! \-perm /a+x
|
|
|
|
.fi
|
|
These two commands both search for files that are readable for
|
|
everybody (
|
|
.B \-perm \-444
|
|
or
|
|
.BR "\-perm \-a+r" ),
|
|
have at least one write bit
|
|
set (
|
|
.B \-perm /222
|
|
or
|
|
.BR "\-perm /a+w" )
|
|
but are not executable for anybody (
|
|
.B ! \-perm /111
|
|
and
|
|
.B ! \-perm /a+x
|
|
respectively).
|
|
|
|
.P
|
|
.nf
|
|
.B cd /source-dir
|
|
.B find . \-name .snapshot \-prune \-o \e( \e! \-name "*~" \-print0 \e)|
|
|
.B cpio \-pmd0 /dest-dir
|
|
|
|
.fi
|
|
This command copies the contents of
|
|
.B /source-dir
|
|
to
|
|
.BR /dest-dir ,
|
|
but omits files and directories named
|
|
.B .snapshot
|
|
(and anything in them). It also omits files or directories whose name
|
|
ends in
|
|
.BR ~ ,
|
|
but not their contents. 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.
|
|
|
|
.P
|
|
.nf
|
|
.B find repo/ -exec test -d {}/.svn \e; -or \e
|
|
.B -exec test -d {}/.git \e; -or -exec test -d {}/CVS \e; \e
|
|
.B -print -prune
|
|
.fi
|
|
|
|
Given the following directory of projects and their associated SCM
|
|
administrative directories, perform an efficient search for the
|
|
projects' roots:
|
|
|
|
.nf
|
|
.B repo/project1/CVS
|
|
.B repo/gnu/project2/.svn
|
|
.B repo/gnu/project3/.svn
|
|
.B repo/gnu/project3/src/.svn
|
|
.B repo/project4/.git
|
|
|
|
.fi
|
|
In this example,
|
|
.B \-prune
|
|
prevents unnecessary descent into directories that have already been
|
|
discovered (for example we do not search project3/src because we
|
|
already found project3/.svn), but ensures sibling directories
|
|
(project2 and project3) are found.
|
|
|
|
.SH EXIT STATUS
|
|
.PP
|
|
.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 "SEE ALSO"
|
|
\fBlocate\fP(1), \fBlocatedb\fP(5), \fBupdatedb\fP(1), \fBxargs\fP(1),
|
|
\fBchmod\fP(1), \fBfnmatch\fP(3), \fBregex\fP(7), \fBstat\fP(2),
|
|
\fBlstat\fP(2), \fBls\fP(1), \fBprintf\fP(3), \fBstrftime\fP(3),
|
|
\fBctime\fP(3)
|
|
|
|
The full documentation for
|
|
.B find
|
|
is maintained as a Texinfo manual. If the
|
|
.B info
|
|
and
|
|
.B find
|
|
programs are properly installed at your site, the command
|
|
.B info find
|
|
should give you access to the complete manual.
|
|
|
|
.SH "HISTORY"
|
|
As of findutils-4.2.2, shell metacharacters (`*', `?' or `[]' for
|
|
example) used in filename patterns will 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
|
|
\-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.
|
|
.P
|
|
.SH "NON-BUGS"
|
|
.nf
|
|
.B $ find . \-name *.c \-print
|
|
find: paths must precede expression
|
|
Usage: find [\-H] [\-L] [\-P] [\-Olevel] [\-D help|tree|search|stat|rates|opt|exec] [path...] [expression]
|
|
.fi
|
|
.P
|
|
This happens because
|
|
.I *.c
|
|
has been expanded by the shell
|
|
resulting in
|
|
.B find
|
|
actually receiving a command line like this:
|
|
.nf
|
|
|
|
.B find . \-name bigram.c code.c frcode.c locate.c \-print
|
|
|
|
.fi
|
|
That command is of course not going to work. Instead of doing things
|
|
this way, you should enclose the pattern in quotes or escape the wildcard:
|
|
.nf
|
|
.B $ find . \-name \(aq*.c\(aq \-print
|
|
.B $ find . \-name \e*.c \-print
|
|
.fi
|
|
|
|
.SH "BUGS"
|
|
.P
|
|
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.
|
|
Please see \fBFinding Files\fP for more information.
|
|
.P
|
|
The environment variable
|
|
.B LC_COLLATE
|
|
has no effect on the
|
|
.B \-ok
|
|
action.
|
|
.P
|
|
The best way to report a bug is to use the form at
|
|
http://savannah.gnu.org/bugs/?group=findutils.
|
|
The reason for this is that you will then be able to track progress in
|
|
fixing the problem. Other comments about \fBfind\fP(1) and about
|
|
the findutils package in general can be sent to the
|
|
.I bug\-findutils
|
|
mailing list. To join the list, send email to
|
|
.IR bug\-findutils\-request@gnu.org .
|