`find`

Find files (POSIX)

Syntax:

find path... [operand_expression]

find [limited_operand_expression]

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:

limited_operand_expression

An expression composed of any of the primary expressions and operators described below, except for -exec, -ok, and -spawn.

Description:

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

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:

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

who may be

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.

who	Permissions for:
`u`	The user who owns the file
`g`	The owner's group
`o`	Others
`a`	All users (equivalent to `ugo`)

op may be:

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

and perm may be any combination of

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.

-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.

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

\\: 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.

Format Codes

%%

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.

Examples:

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.

Exit status:

0: All path operands were successfully traversed.
>0: An error occurred.

Caveats:

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.