NAME

find - find files

 SYNOPSIS

find path... [operand_expression]

 DESCRIPTION

The find utility will recursively descend the directory hierarchy from each file specified by path, evaluating a Boolean expression composed of the primaries described in the OPERANDS section for each file encountered.

The find utility will be able to descend to arbitrary depths in a file hierarchy and will not fail due to path length limitations (unless a path operand specified by the application exceeds {PATH_MAX} requirements).

 OPTIONS

None.

 OPERANDS

The following operands are supported:

The path operand is a pathname of a starting point in the directory hierarchy.

The first argument that starts with a "-", or is a "!" or a "(", and all subsequent arguments will be interpreted as an expression made up of the following primaries and operators. In the descriptions, wherever n is used as a primary argument, it will be interpreted as a decimal integer optionally preceded by a plus (+) or minus (-) sign, as follows:

+n

more than n

n

exactly n

-n

less than n.

The following primaries are supported:

-name pattern

The primary will evaluate as true if the basename of the filename being examined matches pattern using the pattern matching notation described in Pattern Matching Notation

-nouser

The primary will evaluate as true if the file belongs to a user ID for which the XSH specification getpwuid() (or equivalent) function returns NULL.

-nogroup

The primary will evaluate as true if the file belongs to a group ID for which the XSH specification getgrgid() (or equivalent) function returns NULL.

-xdev

The primary always will evaluate as true; it will cause find not to continue descending past directories that have a different device ID (st_dev, see the XSH specification stat() function). If any -xdev primary is specified, it will apply to the entire expression even if the -xdev primary would not normally be evaluated.

-prune

The primary always will evaluate as true; it will cause find not to descend the current pathname if it is a directory. If the -depth primary is specified, the -prune primary will have no effect.

-perm [-]mode

The mode argument is used to represent file mode bits. It will be identical in format to the symbolic_mode operand described in Special Built-in Utilities and will be interpreted as follows. To start, a template will be assumed with all file mode bits cleared. An op symbol of "+" will set the appropriate mode bits in the template; "-" will clear the appropriate bits; "=" will set the appropriate mode bits, without regard to the contents of process' file mode creation mask. The op symbol of "-" cannot be the first character of mode; this avoids ambiguity with the optional leading hyphen. Since the initial mode is all bits off, there are not any symbolic modes that need to use "-" as the first character. If the hyphen is omitted, the primary will evaluate as true when the file permission bits exactly match the value of the resulting template. Otherwise, if mode is prefixed by a hyphen, the primary will evaluate as true if at least all the bits in the resulting template are set in the file permission bits.

-perm [-]onum

If the hyphen is omitted, the primary will evaluate as true when the file permission bits exactly match the value of the octal number onum and only the bits corresponding to the octal mask 07777 will be compared. (See the description of the octal mode in chmod.) Otherwise, if onum is prefixed by a hyphen, the primary will evaluate as true if at least all of the bits specified in onum that are also set in the octal mask 07777 are set.

-type c

The primary will evaluate as true if the type of the file is c, where c is b, c, d, p or f for block special file, character special file, directory, FIFO or regular file, respectively.

-links n

The primary will evaluate as true if the file has n links.

-user uname

The primary will evaluate as true if the file belongs to the user uname. If uname is a decimal integer and the getpwnam() (or equivalent) function does not return a valid user name, uname will be interpreted as a user ID.

-group gname

The primary will evaluate as true if the file belongs to the group gname. If gname is a decimal integer and the getgrnam() (or equivalent) function does not return a valid group name, gname will be interpreted as a group ID.

-size n[c]

The primary will evaluate as true if the file size in bytes, divided by 512 and rounded up to the next integer, is n. If n is followed by the character c, the size will be in bytes.

-atime n

The primary will evaluate as true if the file access time subtracted from the initialisation time is n-1 to n multiples of 24 hours. The initialisation time will be a time between the invocation of the find utility and the first access by that invocation of the find utility to any file specified by its path operands. For example, -atime 3 is true if the file was accessed any time in the period from 72 to 48 hours ago.

-mtime n

The primary will evaluate as true if the file modification time subtracted from the initialisation time is n-1 to n multiples of 24 hours. The initialisation time will be a time between the invocation of the find utility and the first access by that invocation of the find utility to any file specified by its path operands.

-ctime n

The primary will evaluate as true if the time of last change of file status information subtracted from the initialisation time is n-1 to n multiples of 24 hours. The initialisation time will be a time between the invocation of the find utility and the first access by that invocation of the find utility to any file specified by its path operands.

-exec utility_name [argument ...] ;

The primary will evaluate as true if the invoked utility utility_name returns a zero value as exit status. The end of the primary expression will be punctuated by a semicolon. A utility_name or argument containing only the two characters {} will be replaced by the current pathname. If a utility_name or argument string contains the two characters {}, but not just the two characters {}, it is implementation-dependent whether find replaces those two characters with the current pathname or uses the string without change. The current directory for the invocation of utility_name will be the same as the current directory when the find utility was started. If the utility_name names any of the special built-in utilities in Special Built-in Utilities , the results are undefined.

-ok utility_name [argument ...] ;

The -ok primary will be equivalent to -exec, except that find will request affirmation of the invocation of utility_name using the current file as an argument by writing to standard error as described in the STDERR section. If the response on standard input is affirmative, the utility will be invoked. Otherwise, the command will not be invoked and the value of the -ok operand will be false.

-print

The primary always will evaluate as true; it will cause the current pathname to be written to standard output.

-newer file

The primary will evaluate as true if the modification time of the current file is more recent than the modification time of the file named by the pathname file.

-depth

The primary always will evaluate as true; it will cause descent of the directory hierarchy to be done so that all entries in a directory are acted on before the directory itself. If a -depth primary is not specified, all entries in a directory will be acted on after the directory itself. If any -depth primary is specified, it will apply to the entire expression even if the -depth primary would not normally be evaluated.

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

(

True if expression is true.

! expression

Negation of a primary; the unary NOT operator.

expression [-a] expression

Conjunction of primaries; the AND operator will be implied by the juxtaposition of two primaries or made explicit by the optional -a operator. The second expression will not be evaluated if the first expression is false.

expression -o expression

Alternation of primaries; the OR operator. The second expression will not be evaluated if the first expression is true.

If no expression is present, -print will be used as the expression. Otherwise, if the given expression does not contain any of the primaries -exec, -ok or -print, the given expression will be effectively replaced by:

( given_expression ) -print

The -user, -group and -newer primaries each will evaluate their respective arguments only once.

 STDIN

If the -ok primary is used, the response will be read from the standard input. An entire line will be read as the response. Otherwise, the standard input will not be used.

 INPUT FILES

None.

 ENVIRONMENT VARIABLES

The following environment variables affect the execution of find:

LANG

Provide a default value for the internationalisation variables that are unset or null. If LANG is unset or null, the corresponding value from the implementation-dependent default locale will be used. If any of the internationalisation 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 internationalisation variables.

LC_COLLATE

Determine the locale for the behaviour of ranges, equivalence classes and multi-character collating elements used in the pattern matching notation for the -n option and in the extended regular expression defined for the yesexpr locale keyword in the LC_MESSAGES category.

LC_CTYPE

This variable will determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single- versus multi-byte characters in arguments), the behaviour of character classes within the pattern matching notation used for the -n option, and the behaviour of character classes within regular expressions used in the extended regular expression defined for the yesexpr locale keyword in the LC_MESSAGES category.

LC_MESSAGES

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

NLSPATH

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

PATH

Determine the location of the utility_name for the -exec and -ok primaries, as described in the XBD specification, Environment Variables  .

 ASYNCHRONOUS EVENTS

Default.

 STDOUT

The -print primary will cause the current pathnames to be written to standard output. The format will be:

"%s\n", <path>

 STDERR

The -ok primary will write a prompt to standard error containing at least the utility_name to be invoked and the current pathname. In the POSIX locale, the last non-blank character in the prompt will be "?". The exact format used is unspecified.

Otherwise, the standard error will be used only for diagnostic messages.

 OUTPUT FILES

None.

 EXTENDED DESCRIPTION

None.

 EXIT STATUS

The following exit values are returned:

0

All path operands were traversed successfully.

>0

An error occurred.

 CONSEQUENCES OF ERRORS

Default.

 APPLICATION USAGE

When used in operands, pattern matching notation, semicolons, opening parentheses, and closing parentheses are special to the shell and must be quoted (see Quoting ).

The bit that is traditionally used for sticky (historically 01000) is still specified in the -perm primary using the octal number argument form. Since this bit is not defined by this specification, applications must not assume that it actually refers to the traditional sticky bit.

The references to octal modes are marked EX because, although they are obsolescent in the ISO/IEC 9945-2:1993 standard, The Open Group is committed to maintaining them for portable applications until further notice.

 EXAMPLES

1. The following commands are equivalent:

   
   find .
   find . -print
   
   

   They both write out the entire directory hierarchy from the current directory.

2. The following command:

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

   removes all files named tmp or ending in .xx that have not been accessed for seven or more 24-hour periods.

3. The following command:

   
   find . -perm -o+w,+s
   
   

   prints (-print is assumed) the names of all files in or below the current directory, with all of the file permission bits S_ISUID, S_ISGID and S_IWOTH set.

4. The following command:

   
   find . -name SCCS -prune -o -print
   
   

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

5. The following command:

   
   find . -print -name SCCS -prune
   
   

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

6. The following command is roughly equivalent to the -nt extension to test:

   
   if [ -n "$(find file1 -prune -newer file2)" ]; then
       printf %s\\n "file1 is newer than file2"
   fi
   
   

7. The descriptions of -atime, -ctime and -mtime use the terminology n "24-hour periods". For example, a file accessed at 23:59 will be selected by:

   
   find . -atime -1 -print
   
   

   at 00:01 the next day (less than 24 hours later, not more than one day ago); the midnight boundary between days has no effect on the 24-hour calculation.

 FUTURE DIRECTIONS

The IEEE PASC 1003.2 Interpretations Committee has forwarded concerns about parts of this interface definition to the IEEE PASC Shell and Utilities Working Group which is identifying the corrections. A future revision of this specification will align with IEEE Std. 1003.2b when finalised.

 SEE ALSO

chmod, pax, sh, test, the XSH specification description of stat().