Find files (POSIX)
find path... [operand_expression] find [limited_operand_expression]
QNX Neutrino, Microsoft Windows
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
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.
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
Primary expressions
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:
The primary expressions are:
Specifying -chgrp inhibits the automatic -print when the expression as a whole evaluates to true.
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:
| who | Permissions for: |
|---|---|
| u | The user who owns the file |
| g | The owner's group |
| o | Others |
| a | All users (equivalent to ugo) |
You can combine these. For example, if you specify ug, the subsequent op and perm arguments are applied to the user and group permissions on the file.
| op | 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 |
| perm | Meaning |
|---|---|
| r | Read permission |
| w | Write permission (create/unlink for directories) |
| x | Execute permissions (search for directories) |
| s | Setuid for owner or setgid for group, sticky for directories |
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.
Specifying -chown inhibits the automatic -print when the expression as a whole evaluates to true.
Specifying -echo inhibits the automatic -print when the expression as a whole evaluates to true.
Specifying -errmsg inhibits the automatic -print when the expression as a whole evaluates to true.
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.
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's 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' \;
The -spawn primary expression (a QNX Neutrino extension) is similar, but it invokes the command directly, not through a shell. Its behavior is similar to the GNU or BSD version of the -exec primary.
Specifying -fls inhibits the automatic -print when the expression as a whole evaluates to true.
Specifying -fprint inhibits the automatic -print when the expression as a whole evaluates to true.
Specifying -fprint0 inhibits the automatic -print when the expression as a whole evaluates to true.
Specifying -fprintf inhibits the automatic -print when the expression as a whole evaluates to true.
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.
Specifying -ls inhibits the automatic -print when the expression as a whole evaluates to true.
find / -NOP
Specifying -ok inhibits the automatic -print when the expression as a whole evaluates to true.
| 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.
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.
Specifying -print inhibits the automatic -print when the expression as a whole evaluates to true.
Specifying -print0 inhibits the automatic -print when the expression as a whole evaluates to true.
Specifying -printf inhibits the automatic -print when the expression as a whole evaluates to true.
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.
Specifying -rename inhibits the automatic -print when the expression as a whole evaluates to true.
Specifying -spawn inhibits the automatic -print when the expression as a whole evaluates to true.
| Filetype | Description |
|---|---|
| b | Block special file |
| c | Character special file |
| d | Directory |
| p | FIFO |
| f | Regular file |
| l | Symbolic link |
| n | Named special file |
Formatted printing (-printf and -fprintf primitives)
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.
Backslash (\) Escape Codes
Format Codes
| 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 |
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.