find -- find files within file tree

find find files within file tree	Command

find walks down the given file hierarchy starting at directory, and finds files which match the criteria given by expression. Each directory, file, and special file is checked against expression. If you use the -exec, -ok, or -cpio primaries, expression has the side-effect of invoking a specified command on each file found. A non-existent expression or an expression with no side-effects automatically uses the -print primary to display the name of any file that matches the criteria of expression.

find builds expression from a set of primaries and operators. The juxtaposition of two primaries implies the logical AND operator. You can group primaries and operators using parentheses.

Note:: Parentheses, semi-colons and braces are shell metacharacters. You must quote them to use them in an expression.

You must delimit all primaries, operators, numbers, arguments, and parentheses with white space. Each number noted in the primary list is a decimal number, optionally preceded by a plus (+) or minus (-) sign. If a number is given without a sign, find tests for equality; a plus sign implies greater than or older than and a minus sign implies less than or newer than.

Operators

find accepts the following operators:

-a: is used between primaries for logical AND. This operator can be omitted with the same result since logical AND is assumed when no operator is used between two primaries.
-o: is used between primaries for logical OR.
!: negates expression which follows it.

Primaries

find accepts the following primaries:

-acl user-pattern [:[+-=]access-mask]

matches if the file has a name in its Access Control List which matches user-pattern and the optional access-mask information also matches. The user-pattern uses the same syntax as file name generation (see sh). For example,

find c:/ -acl '*Administrator'

finds files with an ACL for Administrator in any domain.

You can optionally specify an access mask where the different permissions are separated by spaces. The following symbols determine how the access-mask matches the ACL:

=     matches if only the specified permission bits are on.
-     matches if only the specified permission bits are off.
+     matches if at least the specified permission bits are on.

For example,

find c:/ -acl '*Administrator:+r w'

finds files with an ACL for Administrator in any domain which have read and write permissions.

-atime number

matches if someone accessed the file during the 24-hour period beginning number days ago.

-cpio cpio-file

writes the file found to the target file cpio-file in cpio format. This is equivalent to

find ... | cpio -o >cpio-file

This primary matches if the command succeeds.

-ctime number

matches if someone changed the attributes of the file during the 24-hour period beginning number days ago.

-depth

processes directories after their contents. If present, this primary always matches.

-exec command ;

takes all arguments between -exec and the semicolon as a command line, replacing any argument which is exactly {} (that is, the two brace characters) with the current path name. It then executes the resulting command line, treating a return status of zero from this command as a successful match, non-zero as failure. You must delimit the terminal semicolon with white space.

-follow

follows symbolic links. If present, this primary always matches.

-group name

matches if the group owner is name. If name is not a valid group name, it is treated as a group ID.

-inum number

matches if the file has inode number number. (See stat)

-level number

does not descend below number levels.

Note:: find only recognizes one -level primary on a command line (even when it appears on different sides of a logical operator). If you do specify -level multiple times, find only uses the last one.

-links number

matches if there are number links to the file.

-mtime number

matches if someone modified the file during the 24-hour period beginning number days ago.

-name pattern

compares the current file name to pattern. If there is no match, expression fails. The pattern uses the same syntax as file name generation (see sh). It attempts to match as many trailing path name components as specified in pattern.

-ncpio cpio-file

writes the file found to the target file cpio-file in cpio -c format. This is equivalent to

find ... | cpio -oc >cpio-file

This primary matches if the command succeeds.

-newer file

compares the modification date of the found file to that of the file given. This matches if someone has modified the found file more recently than file.

-nogroup

matches if no group with a name in the group database (traditionally the file /etc/group) owns the file.

-none

indicates that some action has been taken; thus find does not invoke the default -print action. If present, this primary always matches.

-nouser

matches if no user with a name in the user database (traditionally the file /etc/passwd) owns the file.

-ok command ;

is similar to -exec, but before find executes the command, it displays the command to confirm that you want to go ahead. find only executes the command line if your input matches the expression for yes. If you type the expression for no, the primary does not match. You must delimit the terminal semicolon with white space.

-perm [-]mask

by default, matches if the permissions on the file are identical to the ones given in mask. You may specify mask in octal or in symbolic mode (see chmod). If you use symbolic mode, find assumes that you begin with no bits set in mask, and the symbolic mode is a recipe for turning the bits you want on and off. A leading minus sign (-) is special. It means that a file matches if at least all the bits in mask are set. As a result, with symbolic mode, you cannot use a mask value which begins with a minus sign (-).

If you use octal mode, find only uses the bottom twelve bits of the mask. With an initial minus sign (-), find again matches only if at least all the limits in mask are set in the file permissions lists.

-print

displays the current file name. This primary always matches.

-prune

stops traversing deeper into the tree at this point. If present, this primary always matches. -prune has no effect if -depth is also specified.

-size number[c]

matches if the size of the file is number blocks long, where a block is 512 bytes. If you include the suffix c, the file size is number bytes.

-type c

matches if the type of the file is the same as the type given by the character c. Possible values of the character are:

b   block-special
c   char-special
d   directory
f   regular file
l   symbolic link
n   network file
p   FIFO (named pipe)
s   socket

-user name

matches if the owner of the file is name. Name can also be a user ID number.

-xdev

does not cross device boundaries from the root of the tree traversal. If present, this primary always matches.

EXAMPLES

To find all files with the extensions .c and .h, starting at the current point in the directory hierarchy:

find . -name "*.[ch]"

p> To find all files which have the extension .Z and which were last modified three days ago:

find . -name "*.Z" -mtime 3

To find all files which have the extension .c and which were modified more than three days ago and less than nine days ago:

find . -name "*.c" -a "(" -mtime +3 -a -mtime -9 ")"

To run ls -l on all files over 10 days old:

find . -mtime +10 -exec ls -l "{}" ";"

Here is an extreme example:

find . "(" -name "tmp.*" -o -name "*.tmp" ")"
      -perm =rx -exec rm "{}" ";"

This finds all read-only files which have tmp in either part of their names and deletes all such files. Various parts of this expression are quoted to protect them from interpretation by the shell.

ENVIRONMENT VARIABLES

PATH: determines the location of the command specified with the -exec or -ok primaries.

FILES

/etc/group: for group names for the -group and -nogroup options.
/etc/passwd: for user names for the -user and -nouser options.

DIAGNOSTICS

Possible exit status values are:

0

Successful completion.

1

Failure due to any of the following:

— insufficient memory

— invalid character specified after -type

— cannot obtain information on a file for -newer

— invalid permissions for -perm

— cannot open a file for the -cpio option

— unknown user or group name

— cannot access the PATH variable

— cannot execute a command specified for -exec or -ok

— syntax error

— stack overflow caused by an expression that is too complex

2

Invalid command line option, not enough arguments on command line, missing argument, or argument list that isn't properly terminated.

Messages

bad number specification in "string": You specified an option that takes a numeric value (for example, -atime, -ctime), but did not specify a valid number after the option.
cannot stat file "name" for -newer: You used a -newer option to compare one file to another; however, find could not obtain a modification time for the specified file. Typically, this happens because the file does not exist or you do not have appropriate permissions to obtain this information.

PORTABILITY

POSIX.2. x/OPEN Portability Guide 4.0.

Most UNIX systems do not have a default action of -print; hence, they do not need the -none option. The -a operator is undocumented on many UNIX systems. The -cpio, -follow, -inum, -level, -ncpio, and -none primaries are extensions to the POSIX standard.

find

Command

SYNOPSIS

DESCRIPTION