find(C)

find -- find files

Syntax

find pathname-list expression

Description

The find command is used to find files matching a certain set of selection criteria. find recursively descends the directory hierarchy for each pathname in the pathname-list (a list of one or more pathnames specified for searching) seeking files that match a boolean expression written in the primaries given below.

Primaries can be thought of as selection criteria for files. For any given file, each primary is evaluated in turn and determined to be logically true or false. The values of adjacent primaries are combined and used to determine whether the next primary in line is to be evaluated; if not, find moves on to the next file.

For example, suppose you supply find with a list of four primaries, the third of which is false. find checks the first primary, discovers it to be true, and checks the second primary. Because the first and second primaries are true, the boolean (true/false) value of the sum of the first and second primaries is also true. Therefore find checks the third primary and discovers that it is false. The boolean value obtained by ANDing the third primary (false) with the preceding (true) primaries is false, so find stops evaluating primaries and proceeds to the next file without testing the fourth primary.

Some primaries are automatically true (for example, -print or -depth). It is possible to negate a primary (so that it evaluates to the logical negative of its real value) using the ``!'' operator; when used in conjunction with the -o (logical-OR) and \( ... \) (grouping) primaries this permits the construction of complex logical conditions.

A simple rule of thumb when constructing series of find expressions is that a failed primary early in the series prevents subsequent primaries from being evaluated. Conversely, a -print primary should always go at the end of an expression (otherwise filenames that do not match the entire expression may appear in the find output).

Remember to place a shell escape ``\'' in front of the ``!'', ``('', ``)'', or ``;'' characters when using them in an expression; otherwise the shell will interpret them before passing them on to find.

Expressions

For each file encountered, find evaluates the specified expression, formed of one or more of the following primary expressions, which may evaluate as true or false. In the descriptions, the argument n is used as a decimal integer where +n means more than n, -n means less than n and n means exactly n.

-atime n: True if the file was last accessed n days ago. The access time refers to the last time that the file's data was read, or the creation of the file. It does not record the time that changes were written to the file's data, or to the information stored in the inode.
-cpio device: Writes the current file on device in cpio(F) format (5120-byte records) by piping output to cpio(C) (equivalent to | /bin/cpio -ocBO device). If -follow is also specified, files referenced by symbolic links are also copied into the archive (equivalent to | /bin/cpio -ocBLO device). This option sets -depth automatically. Always true.
-ctime n: True if the file was last changed n days ago. The change time refers to modification of the file's data, modification of the information stored in the inode, or creation of the file.
-depth: Causes all entries in a directory to be acted upon before the directory itself. In a depth-first search, find descends the directory hierarchy as far as it can before traversing the filesystem. This option is set automatically by -cpio to stop copied non-writable directories from preventing their contents being copied to them. Always true.
-exec cmd: Executes shell command cmd. A command argument {} is replaced by the current pathname. True if the executed cmd returns a zero value as exit status (most commands return a zero value on successful completion and a non-zero value if an error is encountered). The end of cmd must be followed by a semicolon. The semicolon should be preceded by a shell escape (like ``\'') because it has a special meaning in the shell.
-follow: Always true; causes symbolic links to be followed. When following symbolic links, find keeps track of the directories visited so that it can detect infinite loops. For example, an infinite loop in a find would occur if a symbolic link pointed to an ancestor. This expression should not be used with the -type l expression.
-group gname: True if the file belongs to the group gname. If gname is numeric and does not appear in the /etc/group file as a group name, it is taken as a group ID.
-inum num: True if the file's inode is num. This is useful for locating files with matching inodes.
-level n: Causes the depth of directories searched to be limited. find descends into n level of directories for each given pathname. Always true.
-links n: True if the file has n links.
-local: True if the file physically resides on the local system.
-mount: Always true; restricts the search to the filesystem containing the directory specified, or if no directory was specified, the current directory.
-mtime n: True if the file's data was last modified n days ago. The modification time refers only to changes made to the file's data, or the creation of the file. It does not record the time that changes were made to the information stored in the inode.
-name pattern: True if pattern matches the current filename. pattern is a shell regular expression, as described in regexp(M). Because this syntax is interpreted by the shell, care should be taken to escape or quote patterns (to prevent them being evaluated prematurely).
-newer file: True if the current file has been modified more recently than the argument file.
-nogroup: True if the file belongs to a group ID that does not have a groupname associated with it.
-none: No operation. Can be used when no operation is given and the -print default is not required.
-nouser: True if the file belongs to a user ID that does not have a username associated with it.
-ok cmd: Like -exec except that the generated command line is printed with a question mark first, and is executed only if the user responds by typing ``y''. (The command should be followed by an escaped semicolon.)
-perm [-] mode: The mode argument is used to represent file mode bits. It is identical to the symbolic mode specified by chmod(C). To start with a blank template is created, corresponding to a file's access permissions with no mode bits set. The permissions granted or revoked in the mode string are then applied. If the hyphen is omitted, this primary expression is true when the permissions specified in the resulting template exactly match the file permissions. Otherwise the expression evaluates as true if, at a minimum, all bits in the template that are set are also set in the file permission bits (the other permissions being ignored).
-perm [-]onum: If the dash (-) is omitted, this primary evaluates as true when the file's permission bits exactly match the file permission bits defined by the value of the octal number onum.
If the dash is specified, this primary evaluates as true if all bits that are set in onum are also set in the file's permission bits.
-print: Causes the current pathname to be printed. This option is used to create a list of files matched by the previous primaries. Always true.
-prune: Always true; causes find not to descend the current pathname if it is a directory. If -depth is specified, -prune has no effect.
-size n [ c ]: True if the file is n blocks long (512 bytes per block), not including indirect blocks. If n is followed by a ``c'', the size is in characters.
-type x: True if the type of the file is x, where x is b for block special file, c for character special file, d for directory, p for named pipe (first-in-first-out (FIFO)), f for regular file, or l for symbolic link.
-user uname: True if the file belongs to the user uname. If uname is numeric and does not appear as a login name in the /etc/passwd file, it is taken as a user ID.
-xdev: Equivalent to the primary -mount.

The primaries may be combined using the following operators (in order of decreasing precedence):

( expression ): True if the parenthesized expression is true. Usually used with the -o operator (see below), parentheses are used for grouping. Parentheses are special to the shell and must be escaped.
! expression: The ``!'' operator specifies the negation of the next primary (that is, ! -newer file is true if the current file is not newer than file). This is the equivalent of the unary NOT operator.
expression [ -a ] expression: Conjunction of primaries (the AND operator). The second expression is not evaluated if the first expression is false.
expression -o expression: Alternation of primaries (the OR operator). Placing the -o operator between two primaries creates an expression that is true if either of the two primaries is true. It should be used with parentheses (that is, \( -perm 644 -o -perm 664 \) is true if the current file has permissions 644 or 664).

Note that placing two primaries next to each other (without an intervening -a operator) is the equivalent of the logical AND operation. The precedence of this operation is less than that of the ``!'' operator but greater than that of the -o operator.

If no expression is given, -print is assumed. Otherwise, if the given expression does not contain any of the primaries -exec, -ok, -cpio, -none or -print, the given expression is assumed to be replaced by:

( given_expression ) -print

Exit values

0: success
1: unable to parse all path-arguments successfully, unable to exec() utility unable to stat() path-argument for mount option
2: command line syntax error
3: out of memory
4: start up error, that is: cannot get current time, cannot get current working directory, cannot compile regular expression for -ok, cannot create pipe for -cpio, cannot stat() file for -newer
5: fatal error

Examples

The following command searches for files named chapter1 in the current directory and all directories below it and sends the pathname of any such files it finds to the standard output:

find . -name chapter1 -print

The following removes all files named core or filenames ending in .out that have not been accessed in the last seven days.

find / \( -name core -o -name ".out" \) -atime +7 -exec rm {} \;

The next example uses find with the -cpio expression to make a tape archive of all files modified within the last seven days.

find / -mtime -7 -print -cpio /dev/rct0

find is used here to list all files within a given range of sizes (between 50 and 100 kilobytes) by including the -size expression twice:

find / -size +100 -size -200 -exec ls -s {} \;

For comparison, the ls(C) command is called with the -s option to report the size of each file in 512-byte blocks (including indirect blocks).

The following command:

find . -perm -o+w,+s

prints (-print is assumed) the names of all files in or below the current directory, with the write permission bit set for ``other'' and set-uid on execute set.

The following command:

find . -name SCCS -prune -o -print

recursively prints pathnames of all files in the current directory and below, but skips the directories named SCCS and the files in them.

The following command:

find . -print -name SCCS -prune

behaves as in the previous example, but prints the paths of the SCCS directories.

The following command:

find . -level 0 -name "foo*"

finds all the files in the current directory that begin with the string foo.

The following command:

find /etc -level 1 -name "bah*"

finds all the files in the directory /etc and the directories /etc/* only, that match the pattern bah*.

Files

/etc/passwd: user names and uids
/etc/group: group names and gids

Standards conformance

find is conformant with:

ISO/IEC DIS 99452:1992, Information technology Portable Operating System Interface (POSIX) Part 2: Shell and Utilities (IEEE Std 1003.21992);
AT&T SVID Issue 2;
X/Open CAE Specification, Commands and Utilities, Issue 4, 1992.