FIND(1) General Commands Manual FIND(1)

find — find files

find path ... [operand_expression ...]

The find utility shall recursively descend the directory hierarchy from each file specified by path, evaluating a Boolean expression composed of the primaries described in OPERANDS
for each file encountered. The find utility shall be able to descend to arbitrary depths in a file hierarchy and shall not fail due to path length limitations (unless a path operand specified by the application exceeds requirements). The find utility requires that the underlying system provides information equivalent to the st_dev, st_mode, st_nlink, st_uid, st_gid, st_size, st_atime, st_mtime, and st_ctime members of struct stat described by POSIX. 1 {8} 5.6 and conforming to the file times update definition in 2.2.2.69.

None.

The following operands shall be supported by the implementation: 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 shall 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 shall 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 Implementations shall recognize the following primaries: Editor’s Note: These primaries have been sorted alphabetically, without diff marks. −atime n The primary shall evaluate as true if the file access time subtracted from the initialization time is n−1 to n multiples of 24 hours. The initialization time shall 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 shall evaluate as true if the time of last change of file status information subtracted from the initialization time is n−1 to n multiples of 24 hours. The initialization time shall 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. −depth The primary always shall evaluate as true; it shall 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 shall be acted on after the directory itself. If any −depth primary is specified, it shall apply to the entire expression even if the −depth primary would not normally be evaluated. -exec utility_name [argument . . . ] ; The primary shall evaluate as true if the invoked utility utility_name returns a zero value as exit status. The end of the primary expression shall be punctuated by a semicolon. A utility_name or argument containing only the two characters {} shall 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 defined 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 shall 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 3.14, the results are undefined. −group gname The primary shall evaluate as true if the file belongs to the group gname. If gname is a decimal integer and the () (or equivalent) function does not return a valid group name, gname shall be interpreted as a group ID. −links n The primary shall evaluate as true if the file has n links. −mtime n The primary shall evaluate as true if the file modification time subtracted from the initialization time is n−1 to n multiples of 24 hours. The initialization time shall 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.

−name pattern The primary shall evaluate as true if the basename of the filename being examined matches pattern using the pattern matching notation described in 3.13. −newer file The primary shall 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. −nogroup The primary shall evaluate as true if the file belongs to a group ID for which the POSIX. 1 {8} () (or equivalent) function returns NULL. −nouser The primary shall evaluate as true if the file belongs to a user ID for which the POSIX. 1 {8} () (or equivalent) function returns NULL. -ok utility_name [argument . . . ] ; The −ok primary shall be equivalent to −exec, except that find shall request affirmation of the invocation of utility_name using the current file as an argument by writing to standard error as, described in STANDARD ERROR . If the response on standard input is affirmative, the utility shall be invoked. Otherwise, the command shall not be invoked and the value of the −ok operand shall be false. -perm [-]mode The mode argument is used to represent file mode bits. It shall be identical in format to the symbolic_mode operand described in chmod(1) , and shall be interpreted as follows. To start, a template shall be assumed with all file mode bits cleared. An op symbol of + shall set the appropriate mode bits in the template; - shall clear the appropriate bits; = shall set the appropriate mode bits, without regard to the contents of process’s file mode creation mask. The op symbol of - cannot be the first character of mode. If the hyphen is omitted, the primary shall 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 shall evaluate as true if at least all the bits in the resulting template are set in the file permission bits. -perm [-]onum (Obsolescent.) If the hyphen is omitted, the primary shall 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 shall be compared. (See the description of the octal mode in chmod(1) .) Otherwise, if onum is prefixed by a hyphen, the primary shall evaluate as true if at least all of the bits specified in onum that are also set it the octal mask 07777 are set.

−print The primary always shall evaluate as true; it shall cause the current pathname to be written to standard output. −prune The primary always shall evaluate as true; it shall cause find not to descend the current pathname if it is a directory. If the −depth primary is specified, the −prune primary shall have no effect. -size n[c] The primary shall 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 shall be in bytes. −type c The primary shall 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, , or regular file, respectively. −user uname The primary shall evaluate as true if the file belongs to the user uname. If uname is a decimal integer and the () (or equivalent) function does not return a valid user name, uname shall be interpreted as a user ID. −xdev The primary always shall evaluate as true; it shall cause find not to continue descending past directories that have a different device ID (st_dev, see POSIX. 1 {8} 5.6.2). If any −xdev primary is specified, it shall apply to the entire expression even if the −xdev primary would not normally be evaluated. The primaries can be combined using the following operators (in order of decreasing precedence): ( expression ) True if expression is true. ! expression Negation of a primary; the unary operator. expression [-a] expression Conjunction of primaries; the operator shall be implied by the juxtaposition of two primaries or made explicit by the optional −a operator. The second expression shall not be evaluated if the first expression is false. expression −o expression Alternation of primaries; the OR operator. The second expression shall not be evaluated if the first expression is true. If no expression is present, −print shall be used as the expression. Otherwise, if the given expression does not contain any of the primaries −exec, −ok, or −print, the given expression shall be effectively replaced by: ( given_expression ) -print The −user, −group, and −newer primaries each shall evaluate their respective arguments only once.

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

None.

The following environment variables shall affect the execution of find:

This variable shall determine the locale to use for the locale categories when both LC_ALL and the corresponding environment variable (beginning with LC_ ) do not specify a locale. See 2.6.

This variable shall determine the locale to be used to override any values for locale categories specified by the settings of LANG or any environment variables beginning with LC_.

This variable shall determine the locale for the behavior of ranges, equivalence classes, and multicharacter collating elements used in the pattern matching notation for the −name option and in the extended regular expression defined for the yesexpr locale keyword in the LC_MESSAGES category.

This variable shall determine the locale for the interpretation of sequences of bytes of text data as characters (e.g., single- versus multibyte characters in arguments), the behavior of character classes within the pattern matching notation used for the −name option, and the behavior of character classes within regular expressions used in the extended regular expression defined for the yesexpr locale keyword in the LC_MESSAGES category.

This variable shall determine the processing of affirmative responses and the language in which messages should be written.

This variable shall determine the location of the utility_name for the −exec and −ok primaries, as described in 2.6.

Default.

The −print primary shall cause the current pathnames to be written to standard output. The format shall be: "%s\n", <path>

The −ok primary shall 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 shall be ?. The exact format used is unspecified. Otherwise, the standard error shall be used only for diagnostic messages.

None.

None.

The find utility shall exit with one of the following values:

All path operands were traversed successfully.

An error occurred.

Default.

When used in operands, pattern matching notation, semicolons, opening parentheses, and closing parentheses are special to the shell and must be quoted (see 3.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. 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 , , and set. The −prune primary was adopted from later releases of bc(1) BSD and the third edition of the SVID. The following command recursively prints pathnames of all files in the current directory and below, but skips directories named SCCS and files in them. find . -name SCCS -prune -o -print The following command behaves as in the previous example, but prints the names of the SCCS directories. find . -print -name SCCS -prune 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

The historical −a operator is kept as an optional operator for compatibility with existing shell scripts even though it is redundant with expression concatenation. The symbolic means of specifying file permission bits, based on chmod, was added in response to numerous balloting objections that find was the only remaining utility to not support this method. The warning about a leading Op of - is to avoid 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. 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 POSIX. 1 {8} or POSIX. 2, applications must not assume that it actually refers to the traditional sticky bit.

The descriptions of how the - modifier on the mode and onum arguments to the −perm primary affects processing has been documented here to match the way it behaves in practice on historical BSD and System V implementations. System V and BSD documentation both describe it in terms of checking additional bits; in fact, it uses the same bits, but checks for having at least all of the matching bits set instead of having exactly the matching bits set. The exact format of the interactive prompts is unspecified. Only the general nature of the contents of prompts are specified, because:

  1. Implementations may desire more descriptive prompts than those used on historical implementations.
  2. Since the traditional prompt strings do not terminate with <newline>s, there is no portable way for another program to interact with the prompts of this utility via pipes.

Therefore, an application using this prompting option relies on the system to provide the most suitable dialogue directly with the user, based on the general guidelines specified. The −name file operand was changed to use the shell pattern matching notation so that find is consistent with other utilities using pattern matching. For the −type c operand, implementors of symbolic links should consider l (the letter ell) for symbolic links. Implementations that support sockets also use −type s for sockets. Implementations planning to add options to allow find to follow symbolic links or treat them as special files, should consider using −follow as used in BSD and System V Release 4 as a guide. The −size operand refers to the size of a file, rather than the number of blocks it may occupy in the file system. The intent is that the POSIX. 1 {8} st_size field should be used, not the st_blocks found in historical implementations. There are at least two reasons for this:

  • In both System V and BSD, find only uses st_size in size calculations for the operands specified by POSIX. 2. ( BSD uses st_blocks only when processing the −ls primary.)
  • Users will usually be thinking of size in terms of the size of the file in bytes, which is also used by the ls utility for the output from the −l option. (In both System V in BSD, ls uses st_size for the −l option size field and uses st_blocks for the ls −s calculations. POSIX. 2 does not specify ls −s.)

The descriptions of −atime, −ctime, and −mtime were changed from the SVID ’s description of n ‘‘days’’ to ‘‘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. The description is also different in terms of the exact timeframe for the n case (versus the +n or −n), but it matches all known historical implementations. It refers to

one 24-hour period in the past, not any time from the beginning of that period to the current time. For example, −atime 3 is true if the file was accessed any time in the period from 72 to 48 hours ago.

Historical implementations do not modify {} when it appears as a substring of an −exec or −ok utility_name or argument string. There have been numerous user requests for this extension, so this standard allows the desired behavior. At least one recent implementation does support this feature, but ran into several problems in managing memory allocation and dealing with multiple occurrences of {} in a string while it was being developed, so it is not yet required behavior. Assuming the presence of −print was added at the request of several working group members to correct a historical pitfall that plagues novice users. It is entirely upward compatible from the historical System V find utility and should be easy to implement. In its simplest form ( find directory), it could be confused with the historical BSD fast find. The BSD developers agree that adding −print as a default expression is the right thing to do and believe that the fast find functionality should have been/should be provided by a separate utility. They suggest that the new utility be called locate.

September 1991 posix.fail