Find files (POSIX)
find path... [operand_expression]
find [limited_operand_expression]
QNX Neutrino, Linux, Microsoft Windows
- path...
- Pathnames under which find should
search for files. The utility traverses
the pathname tree from these files down, looking for files
that match the search criteria specified by the
operand_expression.
If no paths are specified, and the
expression meets the criteria of a limited_operand_expression
(below), then a path of .
is assumed.
- operand_expression
- An expression composed of any set of the
primary expressions
and operators described below.
Here are some links to help you find the expressions:
-abort ¦
-amin ¦
-anewer ¦
-atime ¦
-chgrp ¦
-chmod ¦
-chown ¦
-cmin ¦
-cnewer ¦
-ctime ¦
-daystart ¦
-depth ¦
-echo ¦
-empty ¦
-errmsg ¦
-error ¦
-exec ¦
-exists ¦
-false ¦
-fanewer ¦
-fcnewer ¦
-fls ¦
-fmnewer ¦
-fnewer ¦
-Fnewer ¦
-follow ¦
-fprint ¦
-fprint0 ¦
-fprintf ¦
-gid ¦
-group ¦
-ilname ¦
-iname ¦
-inode ¦
-inum ¦
-ipath ¦
-iregex ¦
-level ¦
-links ¦
-lname ¦
-logical ¦
-ls ¦
-maxdepth ¦
-mindepth ¦
-mmin ¦
-mnewer ¦
-mount ¦
-mtime ¦
-name ¦
-newer ¦
-nogroup ¦
-NOP ¦
-nouser ¦
-ok ¦
-path ¦
-perm (symbolic) ¦
-perm (octal) ¦
-pname ¦
-print ¦
-print0 ¦
-printf ¦
-prune ¦
-regex ¦
-remove! ¦
-rename ¦
-size ¦
-spawn ¦
-true ¦
-type ¦
-uid ¦
-used ¦
-user ¦
-xdev
- limited_operand_expression
- An expression composed of any of the primary expressions and
operators described below, except for
-exec,
-ok,
and
-spawn.
The find utility recursively descends the directory hierarchy
for each file specified by path and seeks files that match
operand_expression.
If you don't specify an operand_expression or
limited_operand_expression on the
command line, find uses
-print
(i.e. the utility matches every file and directory, printing each pathname
on its own line to standard output).
The operand expression follows one or more pathnames. The find
utility treats as a pathname all the arguments up to the first one starting
with any of these characters:
- ! (
Everything after that is part of the operand expression.
|
You'll probably have to quote some operands and patterns, depending on
the shell that you're using. |
Operand expressions are made up of primaries and operators. The following
operators are supported:
Operator |
Action |
! |
(NOT) |
-a |
(AND) |
-o |
(OR) |
AND operations have higher precedence than OR operators.
Negation (!) has a higher precedence than AND
operators. Parentheses are supported to override the normal precedence
rules.
The rules that apply to primaries and operators are:
Expression |
Evaluates to |
-primary
|
True if primary is true. |
( expression )
|
True if expression is true. |
! expression
|
(NOT) Negation of a primary or expression enclosed
in parentheses. |
expression [-a] expression
|
(AND) True if both expressions are true. If the first
expression is false, the second expression isn't evaluated. The
-a is optional. AND is implied by the
juxtaposition of two expressions (see below). |
expression -o expression
|
(OR) True if either expression is true. If the first
expression is true, the second expression isn't evaluated. |
As mentioned above, the -a operand is optional.
If you want to match files of two different patterns, you might be inclined
to use this command:
find . -name "*~" -o -name "*.o" -print
but this doesn't work the way you might expect it to because of the implicit
-a before the -print expression.
The rules of precedence make the above command equivalent to this:
find . \( -name "*~" \) -o \( -name "*.o" -a -print \)
You should specify the command like this:
find . \( -name "*~" -o -name "*.o" \) -print
Note that if you don't supply an expression, find behaves
as if you specified -print.
If you specify an expression, but it doesn't contain a
-chmod,
-chown,
-exec,
-fls,
-fprint,
-fprint0,
-fprintf,
-ls,
-ok,
-print,
-print0,
-printf,
-rename,
-remove!,
or -spawn
primary, the find utility operates as if you specified the following
expression:
( given_expression ) -print
Whenever a primary expression uses a number (n),
you can optionally precede it by a plus
(+) or minus (-) sign, which changes the meaning
as follows:
Expression |
Means |
+n |
More than n |
-n |
Less than n |
n |
Exactly n |
We've classified the primary expressions as follows,
in case you're interested in using find in a portable manner:
- POSIX
- Supported by any POSIX find implementation.
- GNU
- Supported by the QNX Neutrino and GNU find implementations.
- QNX Neutrino
- Supported only by the QNX Neutrino implementation.
The primary expressions are:
- -abort
- (QNX Neutrino) Immediately terminate the find with a nonzero exit status.
- -amin n
- (GNU) True if the file was last accessed n minutes
ago.
- -anewer file
- (GNU) True if the file being evaluated was accessed more recently than
file.
- -atime n
- (POSIX) True if the file access time subtracted from the time that
the find utility started running is between
n-1 and n multiples
of 24 hours. For example, find . -atime 1 finds all files
under the current directory for which the file was accessed
within the last 24 hours.
- -chgrp gname
- (QNX Neutrino) Change the file group ownership of the file currently
being evaluated
to gname. If gname is
numeric and the name doesn't exist in the group database,
gname is taken as a group ID.
Specifying -chgrp inhibits the automatic
-print when the expression as a whole evaluates to true.
- -chmod mode
- (QNX Neutrino) Change the permissions of the file currently being
evaluated according
to the specified mode.
The mode argument represents file mode bits. It's
identical to the symbolic_mode operand described in
chmod and is
interpreted as follows.
A file mode has the form:
who{op}perm[,mode...]
where
For example, to remove write permission for group and other from
the file being evaluated, use -chmod go-w.
Specifying -chmod inhibits the automatic
-print when the expression as a whole evaluates to true.
- -chown uname[:gname]
- (QNX Neutrino) Change the file ownership of the file currently being evaluated
to the one specified, taking a ownership specification similar to that
accepted by the chown utility. A user name uname must be
specified, optionally followed by a colon (:) and group name
gname. The uname and
gname parameters may be either an ASCII name
or the actual numeric user or group ID.
Specifying -chown inhibits the automatic
-print when the expression as a whole evaluates to true.
- -cmin n
- (GNU) True if the file status was last changed n minutes
ago.
- -cnewer file
- (GNU) True if the file being evaluated had its status changed more recently than
that of file.
- -ctime n
- (POSIX) True if the file change of status time subtracted from the
time that the find utility started running is between
n-1 and n multiples
of 24 hours.
- -daystart
- (GNU) Always true. When used, this primitive causes find to
globally alter the behavior of the
-atime,
-ctime,
and -mtime
primitives: instead of comparing file times to n
24-hour periods before the current time, it compares file times
to n 24-hour periods before the beginning of the
current calendar day.
- -depth
- (POSIX) Always true; causes descent of the directory hierarchy to
be done so that all entries in the directory are acted on before the
directory itself. If no -depth primary is specified,
all entries in the directory are acted on after the directory
itself. If any -depth primary is specified, it
applies to the entire expression even if the -depth
primary isn't normally evaluated.
- -echo [text] ;
- (QNX Neutrino) Write the supplied text to standard output. If the text contains any
braces ({}), they're interpreted as in the
-exec
primitive to represent the pathname being evaluated.
Specifying -echo inhibits the automatic
-print when the expression as a whole evaluates to true.
- -empty
- (GNU) True if the file is a regular file of size 0, or a directory that
contains no files.
- -errmsg [text] ;
- (QNX Neutrino) Similar to -echo, except the output is written to
standard error.
Specifying -errmsg inhibits the automatic
-print when the expression as a whole evaluates to true.
- -error
- (QNX Neutrino) Cause the exit status to be nonzero when the find is completed.
This primary always evaluates to false and is typically used with
-exec. For example, if you enter:
find /bin -type f \( -exec cmp {} /hd{} \; \
-o -error \)
find exits with a nonzero status if any of the files in
/bin don't compare successfully against
the same files under /hd/bin.
- -exec utility_name [argument...] ;
- (POSIX) True if the executed utility utility_name returns
a zero value as exit status. The end of the primary expression is
punctuated by a semicolon (;).
If a utility_name or argument contains
{...},
the {...} is replaced by
the current pathname or a portion thereof as follows:
A {} in a utility_name or argument
is replaced by the pathname being evaluated.
Such arguments are used by -echo,
-errmsg,
-exists,
-fanewer,
-fcnewer,
-fmnewer,
-fnewer,
-ok,
-rename
and -spawn
in addition to -exec.
The current directory for the execution
of utility_name is the same as the current
directory when the find utility was started.
Specifying -exec inhibits the automatic
-print when the expression as a whole evaluates to true.
There is a QNX Neutrino-only extension to the {} syntax for
stripping leading and trailing characters. You may also opt to
insert the filename stripped of a number of characters at the end
(strip) or the filename less a number of characters at the
beginning (skip). The syntax for this is
{[strip][,skip]}
So, to move all files ending in .c to the same
names ending in .C, one might use:
find . -type f -name '*.c' \
-exec 'mv {} {1}C' \;
- -exists filestring
- (QNX Neutrino) True if the file represented by filestring exists.
The filestring may be a simple filename or it may
contain braces ({}) to represent the name of the file
currently being evaluated, in the same manner as used with the
-exec primitive.
- -false
- (GNU) Always false.
- -fanewer filestring
- (QNX Neutrino) True if the file was accessed more recently than the file represented
by filestring.
- -fcnewer filestring
- (QNX Neutrino) True if the file had its status changed more recently than the file
represented by filestring.
- -fls file
- (GNU) Always true. Similar to -ls, but output is written
to file instead of the standard output.
Specifying -fls inhibits the automatic
-print when the expression as a whole evaluates to true.
- -fmnewer filestring
- (QNX Neutrino) True if the file was modified more recently than the file represented
by filestring.
- -fnewer filestring
- (QNX Neutrino) Synonym for -fmnewer (above).
- -Fnewer file
- (QNX Neutrino) True if the file being evaluated was created more recently than
file.
- -follow
- (GNU) Always true. When -follow is specified, find
treats symbolic links as being the type of the file they point to.
If the link points to a directory, find recurses into
that directory. By default, symbolic links are treated as special
files of type symbolic link. What they point to is irrelevant to
find's default behavior.
- -fprint file
- (GNU) Similar to -print, but output is written to
file instead of to the standard output.
Specifying -fprint inhibits the automatic
-print when the expression as a whole evaluates to true.
- -fprint0 file
- (GNU) Similar to -print, but each file name is followed
by a NUL instead of a newline character, and the output is written
to file instead of to the standard output.
Specifying -fprint0 inhibits the automatic
-print when the expression as a whole evaluates to true.
- -fprintf file format
- (GNU) Always true. Write data pertaining to the file currently being
evaluated to file, according to the
format specified. See “Formatted Printing”
for details on the format string.
Specifying -fprintf inhibits the automatic
-print when the expression as a whole evaluates to true.
- -gid n|groupname
- (GNU) Synonym for -group.
- -group gname
- (POSIX) True if the file belongs to the group gname. If
gname is numeric and the name doesn't exist in
the group database, gname is taken as a group
ID. Note that gname is evaluated
only once.
- -ilname fpattern
- (GNU) Similar to -lname, but case-insensitive in the pattern
match.
- -iname fpattern
- (GNU) Similar to -name, but case-insensitive in the pattern
match.
- -inode file|n
- (QNX Neutrino) True if the file uses the same inode (has the same serial number) as the
named file. If the file doesn't exist and is
numeric, the number is used as the serial number to match. This primary
is used to find links to a file.
- -inum n|file
- (GNU) Synonym for -inode.
- -ipath fpattern
- (GNU) Like -path, but case-insensitive when evaluating the
pattern match.
- -iregex ere
- (GNU) Like -regex, but case-insensitive when evaluating
the regular expression match.
- -level n
- (QNX Neutrino) True when the level down in a directory tree is n.
A file or directory specified on the command line is considered level
0. For example, this command:
find /usr -level 1 -type d \
-print -o \
-level 2 -prune -type f \
-name .usrinit -ls
displays all the directories in /usr, and
for each directory that has a .usrinit file,
displays information on that file in ls -l format.
(The -prune at level 2 prevents unnecessary processing
in walking down the directory tree. Though no files further down could
possibly match the -level 1 or -level 2
criteria, find doesn't detect this automatically — the
command-line expression is applied against every file in the directory
tree unless a full recursion of that tree is prevented by a
-prune primitive.)
The following command:
find /usr -level 1 -ls -prune
displays information in ls -l format only on files in
/usr and doesn't descend into any subdirectories
of /usr.
- -links n
- (POSIX) True if the file has n links.
- -lname fpattern
- (GNU) True if -follow
or -logical isn't
specified, and the file being evaluated is a symbolic link whose target
is a pathname that matches the pattern fpattern.
- -logical
- (QNX Neutrino) Synonym for -follow.
- -ls
- (GNU) Similar to -print, but displays in the same format as
ls -l.
Specifying -ls inhibits the automatic
-print when the expression as a whole evaluates to true.
- -maxdepth n
- (GNU) Always true. When this flag is set, find descends at most
n levels in the directory hierarchy. Files that
are named on the command line are level 0. Note: the + and -
modifiers have no meaning when used in conjunction with n
in this primary.
- -mindepth n
- (GNU) Always true. When this flag is set, find doesn't apply the
expression to files unless the files are at least n
levels down in the directory hierarchy. Files named on the command line
are level 0. Note: the + and - modifiers have no meaning when used in
conjunction with n in this primary.
- -mmin n
- (GNU) True if the file data was last modified n minutes
ago.
- -mnewer file
- (QNX Neutrino) True if the file being evaluated was modified more recently than
file was.
- -mount
- (GNU) Synonym for -xdev.
- -mtime n
- (POSIX) True if the file modification time subtracted from the time that the
find utility started running is between n-1
and n multiples of 24 hours.
- -name pattern
- (POSIX) True if the basename of the filename being examined matches
pattern. This follows the same pattern-matching
rules as used by
fnmatch()
(see the Neutrino Library Reference).
- -newer file
- (POSIX) True if the current file has been modified more recently than
file has.
Note that file is evaluated only once.
- -nogroup
- (POSIX) True if the file belongs to a group ID that isn't in the group
database.
- -NOP
- (QNX Neutrino) Always true, does nothing. This primitive has the side effect of disabling
the implicit -print that occurs when
the expression as a whole evaluates to true.
You can use this primitive
to benchmark the time it takes to do a walk of the filesystem. For
example:
find / -NOP
- -nouser
- (POSIX) True if the file belongs to a userid that isn't in the password
database.
- -ok utility_name [argument...] ;
- (POSIX) Similar to -exec, except that find
requests affirmation of the execution of utility_name
using the current file as an argument by writing to standard error. If
the response on standard input is affirmative, the utility is executed.
If the response isn't affirmative, the command isn't executed and the
value of the -ok operand is false.
Specifying -ok inhibits the automatic
-print when the expression as a whole evaluates to true.
- -path fpattern
- (GNU) True for any file whose path (as would be printed by -print)
matches fpattern.
- -perm [-]mode
- (POSIX) The mode argument represents file mode bits. It's
identical to the symbolic_mode operand described in
chmod and is interpreted as follows. To start, a template is
assumed with all file mode bits cleared. An op
symbol of:
Operator |
Action
|
+ |
Sets the appropriate mode bits
|
- |
Clears the appropriate mode bits
|
= |
Sets the appropriate mode bits, regardless of
the process's file mode creation mask
|
An op symbol of - can't be the first
character of mode.
If the optional hyphen preceding mode is omitted,
the primary is true when the file permission bits exactly match the
value of the resulting template. In addition, the bits associated
with the perm symbol s are ignored.
If the hyphen is included, the primary is true if at least all the bits
in the resulting template are set.
- -perm [-] onum
- (POSIX) If the optional hyphen is omitted, the primary is true when the file
permission bits exactly match the value of the octal number
onum and only the bits corresponding to the octal
mask 777 are compared.
If the hyphen is included, more flag bits, corresponding
to the octal mask 06777, are compared and the primary is true if at
least all the bits in onum are set.
- -pname pattern
- (QNX Neutrino) Synonym for -path.
- -print
- (POSIX) Always true; causes the current pathname to be written to standard output,
one pathname per line.
Specifying -print inhibits the automatic
-print when the expression as a whole evaluates to true.
- -print0
- (GNU) Always true. Writes the path currently being evaluated followed by an
ASCII NUL character to the standard output.
Specifying -print0 inhibits the automatic
-print when the expression as a whole evaluates to true.
- -printf format
- (GNU) Always true. Write data pertaining to the file currently being
evaluated to the standard output, according to the
format specified. For more information, see
“Formatted printing,”
below.
Specifying -printf inhibits the automatic
-print when the expression as a whole evaluates to true.
- -prune
- (POSIX) Stops find's descent from that point in the file hierarchy.
- -regex ere
- (GNU) True when the pathname of the file currently being evaluated matches
the extended regular expression specified by ere.
See the grep
documentation for details on regular expressions.
- -remove!
- (QNX Neutrino) Removes the file being evaluated. If the file is a directory,
rmdir() is performed, otherwise an attempt is made
to unlink() the file.
If a directory isn't empty,
the attempt to remove it fails. Thus, to recursively
remove a directory tree with find, the
-depth
primitive must be used in conjunction with
-remove!.
(Note the simple removal of a directory tree is better and more portably
done by using the rm utility.)
This primitive evaluates
to TRUE if the removal was successful. Note that the exclamation mark
(!) is a required part of this primitive.
Specifying -remove! inhibits the automatic
-print when the expression as a whole evaluates to true.
- -rename filestring
- (QNX Neutrino) Renames the file to the pathname indicated by filestring.
As with other filestring arguments, braces ({})
encountered in the string are expanded to the name of the file
currently being evaluated. A file may be renamed anywhere within the
same filesystem. If the new path lies on another device, the rename
fails. Evaluates to true if the rename succeeds, false if it fails.
Specifying -rename inhibits the automatic
-print when the expression as a whole evaluates to true.
- -size n[c]
- (POSIX) True if the file size in bytes, divided by 512 and rounded up to the next
integer, is n. If n is
followed by c, the size is in bytes.
- -spawn cmd [arguments]... ;
- (QNX Neutrino) Similar to -exec, except that the command is invoked
directly (i.e. not through a shell). The -spawn primary
is faster but less flexible than -exec.
Specifying -spawn inhibits the automatic
-print when the expression as a whole evaluates to true.
- -true
- (GNU) Always true.
- -type c
- (POSIX) True if the file type is c, where
c is one of:
Filetype |
Description
|
b |
Block special file
|
c |
Character special file
|
d |
Directory
|
p |
FIFO
|
f |
Regular file
|
l |
Symbolic link
|
n |
Named special file
|
- -uid n|userid
- (GNU) Synonym for -user.
- -used n
- (GNU) True if file was last accessed n days after its
status was last changed.
- -user uname
- (POSIX) True if the file belongs to the user uname. If
uname is numeric and the name doesn't exist in
the password database, uname is taken as a user
ID. Note that uname is evaluated
only once.
- -xdev
- (POSIX) Always true — stops find from descending past directories that
have a different device ID. If any -xdev
primary is specified, it applies to the entire expression, even if
the -xdev primary isn't normally evaluated.
The -printf and
-fprintf primaries
require as arguments a format string similar in appearance to that used
in the C language printf() function. The format
string consists of regular ASCII characters and a set of special codes
starting with percent (%) format codes and backslash (\) escape codes.
- \\
- Literal backslash (\) character.
- \a
- Alarm bell.
- \b
- Backspace character.
- \c
- Stop printing from format and flush output.
- \f
- Form-feed character.
- \n
- Newline character.
- \r
- Carriage return character.
- \v
- Vertical tab character.
- %%
- Literal percent (%) character.
- %p
- The pathname currently being evaluated.
- %f
- The basename of the file.
- %h
- The dirname of the file.
- %P
- The name of the file with the root of the file tree (pathname
specified on the command line) removed from the beginning.
- %H
- The name of the root of the file tree (pathname specified on
the command line under which the current file was found).
- %g
- The file's group name, or numeric group ID if no name found.
- %G
- The file's numeric group ID.
- %u
- The file's user name, or numeric userid if no name found.
- %U
- The file's numeric userid.
- %m
- The file's permissions in octal.
- %k
- The file's size in 1k blocks (rounded up).
- %b
- The file's size in 512-byte blocks (rounded up).
- %s
- The file's size in bytes.
- %d
- The depth of the file in the directory tree. The files
specified on the command line have a depth of 0.
- %l
- If the file is a symbolic link, the filename of the link
object. Null if file isn't a symbolic link.
- %i
- The inode number of the file.
- %n
- The link count of the file.
- %a
- The file's last access date and time; equivalent to %Ac
- %Afchar
- Partial or full representation of the file's last access time,
depending on the format character fchar:
fchar |
Is replaced by:
|
a |
Abbreviated weekday name
|
A |
Full weekday name
|
b |
Abbreviated month name
|
B |
Full month name
|
c |
Locale's appropriate date and time representation
|
d |
Day of the month as a decimal number (01-31)
|
D |
Date in the format mm/dd/yy
|
h |
Abbreviated month name
|
H |
Hour (24 hr) as a decimal number (00-23)
|
I |
Hour (12 hr) as a decimal number (01-12)
|
j |
Day of the year as a decimal number (001-366)
|
m |
Month as a decimal number (01-12)
|
M |
Minute as a decimal number
|
n |
Newline character
|
p |
AM or PM
|
r |
12-hr clock time (01-12) using the AM/PM notation
i.e. hh:mm:ss (AM|PM)
|
S |
Second as a decimal number (00-59)
|
t |
Tab character
|
T |
24-hr clock time (00-23) hh:mm:ss
|
U |
Week number of the year as a decimal number (00-52),
where Sunday is the first day of the week
|
w |
Weekday as a decimal number (0-6), where 0 is Sunday
|
W |
Week number of the year as a decimal number (00-52), where
Monday is the first day of the week
|
x |
Locale's appropriate date representation
|
X |
Locale's appropriate time representation
|
y |
Year without century as a decimal number
|
Y |
Year with century as a decimal number
|
Z |
Timezone name, NULL if no timezone exists
|
|
QNX Neutrino currently supports only the POSIX (i.e. C) locale.
|
- %c
- File's last status change date and time — equivalent to
%Cc
- %Cfchar
- Partial or full representation of the file's last
status change time, depending on the format character
fchar. See description of %A, above for
details.
- %t
- File's last modification date and time — equivalent to
%Tc
- %Tfchar
- Partial or full representation of the file's last
modification time, depending on the format character
fchar. See description of %A, above for
details.
Search the filesystem for the myfile file or directory:
find / -name myfile
Remove all files named tmp or ending in
.xx that haven't been accessed for seven or more
24-hour periods:
find / \( -name tmp -o -name '*.xx' \) \
-atime +7 -exec rm {} \;
Print the pathnames of all files in and below the current directory,
but skip any directories named SCCS and the
files beneath them:
find . -name SCCS -prune -o -print
Note that when possible, it's better to use find in combination
with xargs than it is to use the
-exec or
-spawn options to start commands.
You can use xargs to start a program once for
many files; -exec or -spawn starts
the program once for every file matched. You'll see a
tremendous difference in speed between the two approaches.
For instance:
find / -name '*.tmp' | xargs rm
is generally preferable to:
find / -name '*.tmp' -exec rm {} \;
See xargs for more details.
- 0
- All path operands were successfully traversed.
- >0
- An error occurred.
If you use -exec,
-ok,
or -spawn,
find catches SIGINT (which you can generate,
for example, by pressing Ctrl-C
or Ctrl-Break)
and asks you whether the find should continue. If these primaries aren't
used, find terminates from SIGINT.
chmod,
chown,
mv,
pax,
rm,
xargs