find(C)

Syntax

Description

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

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

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

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

See also

Standards conformance

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.

Notices