find - find files

find scans directories and all their subdirectories for files which match a specified search criterion. Files located in this way can be listed and/or processed with a command.

find locates not only ordinary files, but also directories, special files and FIFOs.

Syntax

find directory expression

directory

Name of the directory that is to be scanned. find will search through this directory and recursively through its subdirectories, provided you have read and execute permission (r and x bit) for them. More than one directory may be named.

expression

expression may be given as one or more primary expressions (primaries) of the kind listed below or as a combination of these primaries.

find applies expression to each file in the specified directories or subdirectories by evaluating primaries from left to right. Each primary is considered to have a "true" or "false" value for a file. The truth value of each expression and the next relational operator determine whether or not find will process the next primary.

Most primaries define conditions, i.e. they return a value of true if the current file satisfies the condition.

The expressions:

-print
-exec command \;
-ok command \;

are not conditions. They cause actions to be executed, e.g. output of the file name or deletion of the file. When find processes one of these expressions, the associated action is always performed, regardless of whether the expression returns a value of true or false. If none of the above action primaries are specified, find exits with an error message. Shell metacharacters that appear in expression must be escaped to ensure that they are passed to find and not interpreted by the shell.

Primaries as conditions

The following section describes primaries; the method of combining primaries is shown thereafter.

If you use options to find files with specific attributes (e.g. the files modified within a given period), the relevant option must come before the -print option (see below), as otherwise all files will be listed.

In the following discussion, n represents a decimal integer; +n means "more than n", -n means "less than n", and n means "exactly n".

-name file

True if file matches the name of the current file.
You can also use the usual shell metanotation for file name generation, but then file must be enclosed in single quotes, e.g. find /usr/adam -name ’group.*’ (see section “Metacharacters for the POSIX shell” ). Only file basenames may be specified; pathnames such as text/tmp are not permitted.

-perm mode

True if the file permission flags exactly match mode (see chmod). mode can also be an octal number. If mode is prefixed by a minus sign (-), only the bits that are set in mode are compared with the file permission flags, and the expression evaluates true if they match.

-type character

True if the current file is of type character, where character can be:

f	ordinary file
d	directory
b	block special file
c	character special file
l	symbolic links
p	named pipe or FIFO file

-fstype name

True if the file system to which the current file belongs is of type name, where name can be ufs or some special file systems such as proc or fdfs.

-links [+-]n

True if there are (more/less than) n links to the current file.

-inum [+-]n

True if the current file has an inode number greater than (+), less than (-), or equal to n. The expression -inum +n -inum -m can be used to find all inode numbers between n and m.

-user login_name

True if the current file belongs to the user login_name. This option is only of use for users with uid=0 (command id).

-nouser

True if the current file belongs to a login name which is not present. This option is only of use for users with uid=0 (command id).

-group group_name

True if the current file belongs to the group group_name.

-nogroup

True if the current file belongs to a group that is not listed in the /etc/group file.

-size [+-]n[c]

c not specified:
True if the current file is (more / less than / equal) n blocks long, where one block is 512 bytes.

c specified:
True if the current file is (more / less than / equal) n bytes long.

-atime [+-]n

(access) True if the current file was last accessed (more / less than / equal) (n-1) to n*24 hours ago. The access time of directories searched by find is changed by find itself.

-mtime [+-]n

(modification time) True if the current file was last modified (more / less than / equal) (n-1) to n*24 hours ago.

-ctime [+-]n

True if the inode of the current file was last modified (more / less than / equal) (n-1) to n*24 hours ago.

-newer file

True if the current file is "newer" than the specified file, i.e. if it was created or modified at a later point in time.

-local

True if the current file physically resides on the local system.

-prune

Always true. If this expression is processed no search is conducted in files or directories which lie below the current level in the file hierarchy.

-xdev

Always true. If this expression is processed no search is conducted in files or directories which lie below directories which have a different device number (st_dev, see the stat() function [4]). If -xdev is set then this applies to the entire expression even if -xdev is not normally processed.

Action primaries

-print

Always true. If this expression is present, it causes find to print the path name of the current file on standard output.

-exec command \;

command is executed as soon as this expression is processed.

You must terminate command with a blank and an escaped semicolon (\;).

A set of braces {} can be used to represent the name of the current file.

The expression -exec command \; is true if the executed command returns an exit status of 0. The truth value is significant when this expression is combined with other expressions.

-ok command \;

Like -exec, except that find asks if the command is to be executed each time the expression is processed. The command is only executed if you respond with the character or string signifying "y[es]" in the current locale (see environment variable LANG).

Expressions that affect the behavior of find

-depth

Always true. If present, this expression causes find to act upon entries in a directory before the directory itself.

-follow

Always true. This expression causes symbolic links to be followed. It should not be combined with the -type l expression.

-mount

Always true. If this expression is present, it causes find to restrict its search to the file system containing the directory specified.

Combining expressions

The expressions described above can be combined with one another as shown below. Please note the blanks used before and after the operators!
The operators are listed in order of decreasing precedence.

\( expression... \)

Parentheses group expressions together. The parentheses themselves must be escaped with a backslash, since they have a special meaning for the shell.

! expression

Negation, i.e. true if the expression evaluates to false.

expression expression

Logical AND, i.e. true if both expressions are true. If the first expression is false, find does not process the second expression.

Example

If the second expression is
-exec command \;
the specified command will only be executed if the first expression is true.

expression -o expression

Logical OR, i.e. true when either of the expressions is true. If the first expression is true,
find does not process the second expression.

Example

If the second expression is
-exec command \;
the command will only be executed if the first expression is false.

Error

Error messages without command termination (exit status 0)

find: cannot read dir dir : Permission denied
Since you have no read permission for the dir directory, this directory cannot be scanned. find does not terminate after this error message, but continues scanning directories for which you do have the required access permissions (r bit).

find: cannot access dir/file : permission denied
Since you have no execute permission (x bit) for dir, this directory cannot be scanned. find does not terminate after this message but searches through those directories for which you do have the appropriate perimissions (r and x bits).

find: cannot open dir : No such file or directory
There is no directory named dir.

Error messages with command termination (non-zero exit status)

find: missing conjunction

You have either combined primaries incorrectly in the find call or specified more than one argument in a primary.

find: no action specified

You have not specified an action (print, exec, ok).

find: incomplete statement

You have forgotten the escaped semicolon \; which is required to terminate a command in an -exec or -ok expression.

find: insufficient number of arguments

You have specified too few arguments.

find: path-list predicate-list

You have failed to specify the pathname list for directory.

File

/etc/group

File containing group names

Locale

The following environment variables affect the execution of find:

LANG

Provide a default value for the internationalization variables that are unset or null. If LANG is unset of null, the corresponding value from the implementation-specific default locale will be used. If any of the internationalization variables contains an invalid setting, the utility will behave as if none of the variables had been defined.

LC_ALL

If set to a non-empty string value, override the values of all the other internationalization variables.

LC_COLLATE

Determine the locale for the behavior of ranges, equivalence classes and multicharacter collating elements used in pattern matching notation for the -n option. In file name generation patterns in square brackets (such as find . -name ’[[=a=]]*’ -print), the LC_COLLATE environment variable governs the scope of character ranges, equivalence classes and collating elements.

LC_CTYPE

Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single- as opposed to multi-byte characters in arguments and input files), the classification of characters as upper- to lower-case, and the mapping of characters from one case to the other.

LC_MESSAGES

Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.

NLSPATH

Determine the location of message catalogs for the processing of LC_MESSAGES.

Example 1

A simple example to illustrate how find works:

Display the path names of all files that

• are located in the current directory or in a subdirectory and

• have the name tmp.

$ find . -name tmp -print

In this case, expression comprises two primaries that are linked by a logical AND operator. find first checks the -name tmp primary for each file. If this expression is true (i.e. the current file is named tmp), find will also process the expression -print, which outputs the path names. Otherwise, find does not process the -print expression and remains silent.

Please note the sequence. If you entered:

$ find . -print -name tmp

instead, find would process the -print expression for each file, i.e. would output the path names of all files.

Example 2

A more complex example:

Display the path names of all files that

• are located in the current directory or its subdirectories, and

• are named tmp or have names ending in .xx.

$ find . \( -name tmp -o -name '*.xx' \) -print

Please note the use of blanks between the arguments!

find begins by processing the parenthesized specifications for each file. These comprise two primaries linked by a logical OR operator.

find first tests the -name tmp primary. If this expression is true (i.e. if the current file is named tmp), find does not process the expression -name ’*.xx’ at all; this is because the result of the expression in parentheses will be true in any case. If -name tmp evaluates to false, find tests the second primary, i.e. -name ’*.xx’. If this expression is true (i.e. the file name ends in .xx), the parenthesized expression will also evaluate to true; otherwise, the result of the expression in parentheses is false.

If the parenthesized expression is true, find then processes the -print expression, i.e. outputs the file names (AND operator; see Example 1). If false, find does not process the -print expression, i.e. remains silent.

Example 3

Search all entries in the /usr/santaclaus directory and its subdirectories and print the files not owned by santaclaus.

$ find /usr/santaclaus ! -user santaclaus -print

Example 4

Delete all files that,

• are named tmp or have names ending in .xx, and

• have not been accessed for more than 7 days.

Confirmation is to be requested before the removal of each file.

$ find / \( -name tmp -o -name '*.xx' \) -atime +7 -ok rm {} \;

Example 5

Recursively print all file names in the current directory and below, but skipping all SCCS directories:

$ find . -name SCCS -prune -o -print

See also

chmod, ln, test
stat() [4]