find

Find files (POSIX)

Syntax:

find path... [operand_expression]

find [limited_operand_expression]

Options:

path...

This names the pathnames under which find should search for files. The utility will traverse the pathname tree from these files down, looking for files which 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

This is an expression composed of any set of the primary expressions and operators described in the description.

limited_operand_expression

This represents an expression composed of any of the primary expressions and operators described in the description except for -exec, -ok and -spawn.

If no operand_expression or limited_operand_expression is supplied on the command line, an operand_expression of -print is assumed.

Description:

The find utility recursively descends the directory hierarchy for each file specified by path and seeks files that match operand_expression.

When an operand expression isn't specified, the find utility will match every file and directory, printing each pathname to the standard output, one file per line.

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:

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 can be summarized as follows:

Primary expressions

Note that when no expression is supplied, find behaves as if an expression of -print were specified.

If an expression is supplied 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 the following expression were supplied:

• ( given_expression ) -print

Specifying "more than" or "less than" with numerical arguments

Whenever a number n is used in a primary expression, it may be optionally preceded by a plus (+) or minus (-) sign, which changes the meaning as follows:

Each of the primaries listed below have been identified as POSIX, QNX and/or GNU for the benefit of those concerned with portable use of the find utility.

POSIX

the primary is supported by any POSIX find implementation

GNU

the primary is supported by the QNX and GNU find implementations

QNX

the primary is supported only by the QNX implementation

-abort

(QNX) 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 will find all files under the current directory for which the file was accessed within the last 24 hours.

-chgrp gname

(QNX) Changes 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 will inhibit the automatic -print when the expression as a whole evaluates to true.

-chmod mode

(QNX) Changes the permissions of the file currently being evaluated according to the specified mode.

The mode argument represents file mode bits. It is identical to the symbolic_mode operand described in chmod.

For example, to remove write permission for group and other from the file being evaluated, you would use -chmod go-w.

Specifying -chmod will inhibit the automatic -print when the expression as a whole evaluates to true.

-chown uname[:gname]

(QNX) Changes 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 will inhibit 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 will cause find to globally alter the behavior of the -atime, -ctime, -ftime, and -mtime primitives: instead of comparing file times to n 24-hour periods before the current time, it will compare 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, then all entries in the directory are acted on after the directory itself. If any -depth primary is specified, then it applies to the entire expression even if the -depth primary wouldn't normally be evaluated.

-echo [text] ;

(QNX) Write the supplied text to standard output. If the text contains any {}s, they're interpreted as in the -exec primitive to represent the pathname being evaluated.

Specifying -echo will inhibit 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 which contains no files.

-errmsg [text] ;

(QNX) Similar to -echo, except the output is written to standard error.

Specifying -errmsg will inhibit the automatic -print when the expression as a whole evaluates to true.

-error

(QNX) 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 this command:

find /bin -type f \( -exec cmp {} //9/hd{} \; \
     -o -error \)

find will exit with a nonzero status if any of the files in /bin doesn't compare successfully against the same files under //9/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 will be replaced by the pathname being evaluated. Such arguments are used by -echo, -errmsg, -exists, -fanewer, -fcnewer, -fFnewer, -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 will inhibit the automatic -print when the expression as a whole evaluates to true.

There is a QNX-only extension to the {} syntax for stripping leading and trailing characters. 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), te syntax 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) True if the file represented by filestring exists. filestring may be a simple filename or it may contain {}s to represent the name of the file currently being evaluated, in the same manner as used with the -exec primitive.

-extents n

(QNX) True if the file has n extents in the filesystem.

-false

(GNU) Always false.

-fanewer filestring

(QNX) True if the file was accessed more recently than the file represented by filestring.

-fcnewer filestring

(QNX) True if the file had its status changed more recently than the file represented by filestring.

-fFnewer filestring

(QNX) True if the file was created more recently than the file represented by filestring.

-fls file

(GNU) Always true. Similar to -ls, but output is written to the file file instead of the standard output.

Specifying -fls will inhibit the automatic -print when the expression as a whole evaluates to true.

-fmnewer filestring

(QNX) True if the file was modified more recently than the file represented by filestring.

-fnewer filestring

(QNX) Synonym for -fmnewer (above).

-Fnewer file

(QNX) True if the file being evaluated was created more recently than file.

-follow

(GNU) Always true. When -follow is specified, find will treat symbolic links as being the type of the file they point to. If the link points to a directory, find will recurse 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 will inhibit 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 will inhibit 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 will inhibit the automatic -print when the expression as a whole evaluates to true.

-fsmanager name

(QNX) True if the file being evaluated is being managed by a process whose name, as reported by its response to a version query, matches name. Typical names include Fsys32, Fsys, Dev32, Dev16, Proc, Pipe, Iso9660fsys, Photon, X11R5, Mouse, Socket, and INT10h. A special name "Unknown", will match files whose managers reject the version query.

-ftime n

(QNX) True if the file creation time subtracted from the time that the find utility started running is between n-1 and n multiples of 24 hours.

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

will display all the directories in /usr, and for each directory that has a .usrinit file, will display 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

will display information in ls -l format only on files in /usr and won't descend into any subdirectories of /usr.

-links n

(POSIX) True if the file has n links.

-lname fpattern

(GNU) True if -follow/-logical is not specified, and the file being evaluated is a symbolic link whose target is a pathname which matches the pattern fpattern.

-logical

(QNX) Synonym for -follow.

-ls

(GNU) Similar to -print, but displays in the same format as ls -l.

Specifying -ls will inhibit the automatic -print when the expression as a whole evaluates to true.

-maxdepth n

(GNU) Always true. When this flag is set, find will descend 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 will not 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) True if the file being evaluated was modified more recently than file was.

-mount

(GNU) Synonym for -xdev.

-mountdev

(QNX) True if the file is a block special file for which there is a corresponding filesystem mount point.

-mountpoint

(QNX) True if the file is a directory that is the mount point for a QNX filesystem. If you just want to find all mount points, it's faster to use df or prefix instead.

-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 the fnmatch() C function. (For details, see the section on "Pattern-matching special characters" in the cp utility.)

-newer file

(POSIX) True if the current file has been modified more recently than the modification time of the file named by the file pathname. 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) 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. This primitive can be used 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 user ID 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 will inhibit 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 is 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 - cannot 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) Synonym for -path.

-print

(POSIX) Always true; causes the current pathname to be written to standard output, one pathname per line.

Specifying -print will inhibit 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 will inhibit 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. See the "Description" section for details on the format string.

Specifying -printf will inhibit 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 utility documentation for details on regular expressions.

-remove!

(QNX) 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 is not empty the attempt to remove it will fail. 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! will inhibit the automatic -print when the expression as a whole evaluates to true.

-rename filestring

(QNX) Renames the file to the pathname indicated by filestring. As with other filestring arguments, {}s encountered in the string will be 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 will fail. Evaluates to true if the rename succeeds, false if it fails.

Specifying -rename will inhibit 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) 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 will inhibit the automatic -print when the expression as a whole evaluates to true.

-status [grown|busy]

(QNX) True if the file has a pre-grown or busy status, as specified.

-true

(GNU) Always true.

-type c

(POSIX) True if the filetype is c, where c can be:

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 wouldn't normally be 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.

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

printf Format Codes

%%

Literal percent (%) character.

%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

%b

The file's size in 512-byte blocks (rounded up).

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

%d

The depth of the file in the directory tree. The files specified on the command line have a depth of 0.

%D

The name of the mounted block-special device that the file resides in.

%f

The basename of the file.

%F

The name of the manager process responsible for the file.

%g

The file's group name, or numeric group ID if no name found.

%G

The file's numeric group ID.

%h

The dirname of the file.

%H

The name of the root of the file tree (pathname specified on the command line under which the current file was found).

%i

The inode number of the file.

%k

The file's size in 1K units (rounded up).

%l

If the file is a symbolic link, the filename of the link object. Nil if file is not a symbolic link.

%m

The file's permissions in octal.

%M

The mount point of the filesystem which the file resides on.

%n

The link count of the file.

%p

The pathname currently being evaluated.

%P

The name of the file with the root of the file tree (pathname specified on the command line) removed from the beginning.

%s

The file's size in bytes.

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

%u

The file's user name, or numeric user ID if no name found.

%U

The file's numeric user ID.

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. The xargs utility can be used to start a program once for many files; -exec or -spawn will start 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 detail.

Exit status:

0

At least one file was found which matched the search criteria.

>0

An error occurred, or no files were found matching the search criteria.

Caveats:

If -exec, -ok, or -spawn is used, find will catch SIGINT (which can be generated, for example, by Ctrl-C or Ctrl-Break) and will ask you whether the find should continue. If these primaries aren't used, find will terminate from SIGINT.

See also:

chmod, chown, mv, pax, rm, xargs