| FIND(1P) | POSIX Programmer's Manual | FIND(1P) |
This manual page is part of the POSIX Programmer's Manual. The Linux implementation of this interface may differ (consult the corresponding Linux manual page for details of Linux behavior), or the interface may not be implemented on Linux.
find — find files
find [-H|-L] 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 the OPERANDS section for each file encountered. Each path operand shall be evaluated unaltered as it was provided, including all trailing <slash> characters; all pathnames for other files encountered in the hierarchy shall consist of the concatenation of the current path operand, a <slash> if the current path operand did not end in one, and the filename relative to the path operand. The relative portion shall contain no dot or dot-dot components, no trailing <slash> characters, and only single <slash> characters between pathname components.
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 {PATH_MAX} requirements).
The find utility shall detect infinite loops; that is, entering a previously visited directory that is an ancestor of the last file encountered. When it detects an infinite loop, find shall write a diagnostic message to standard error and shall either recover its position in the hierarchy or terminate.
If a file is removed from or added to the directory hierarchy being searched it is unspecified whether or not find includes that file in its search.
The find utility shall conform to the Base Definitions volume of POSIX.1‐2017, Section 12.2, Utility Syntax Guidelines.
The following options shall be supported by the implementation:
Specifying more than one of the mutually-exclusive options -H and -L shall not be considered an error. The last option specified shall determine the behavior of the utility. If neither the -H nor the -L option is specified, then the file information and type for symbolic links encountered as a path operand on the command line or encountered during the traversal of a file hierarchy shall be that of the link itself.
The following operands shall be supported:
The first operand and subsequent operands up to but not including the first operand that starts with a '-', or is a '!' or a '(', shall be interpreted as path operands. If the first operand starts with a '-', or is a '!' or a '(', the behavior is unspecified. Each path operand is a pathname of a starting point in the file hierarchy.
The first operand 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-sign> ('+') or <hyphen-minus> ('-'), as follows:
The following primaries shall be supported:
If the <hyphen-minus> 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-minus>, the primary shall evaluate as true if at least all the bits in the resulting template are set in the file permission bits.
If the primary expression is punctuated by a <semicolon>, the utility utility_name shall be invoked once for each pathname and the primary shall evaluate as true if the utility returns a zero value as exit status. 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 or uses the string without change.
If the primary expression is punctuated by a <plus-sign>, the primary shall always evaluate as true, and the pathnames for which the primary is evaluated shall be aggregated into sets. The utility utility_name shall be invoked once for each set of aggregated pathnames. Each invocation shall begin after the last pathname in the set is aggregated, and shall be completed before the find utility exits and before the first pathname in the next set (if any) is aggregated for this primary, but it is otherwise unspecified whether the invocation occurs before, during, or after the evaluations of other primaries. If any invocation returns a non-zero value as exit status, the find utility shall return a non-zero exit status. An argument containing only the two characters "{}" shall be replaced by the set of aggregated pathnames, with each pathname passed as a separate argument to the invoked utility in the same order that it was aggregated. The size of any set of two or more pathnames shall be limited such that execution of the utility does not cause the system's {ARG_MAX} limit to be exceeded. If more than one argument containing the two characters "{}" is present, the behavior is unspecified.
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 (see Section 2.14, Special Built-In Utilities), the results are undefined.
The primaries can be combined using the following operators (in order of decreasing precedence):
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.
When the file type evaluated for the current file is a symbolic link, the results of evaluating the -perm primary are implementation-defined.
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:
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> 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 following exit values shall be returned:
Default.
The following sections are informative.
When used in operands, pattern matching notation, <semicolon>, <left-parenthesis>, and <right-parenthesis> characters are special to the shell and must be quoted (see Section 2.2, Quoting).
The bit that is traditionally used for sticky (historically 01000) is specified in the -perm primary using the octal number argument form. Since this bit is not defined by this volume of POSIX.1‐2017, applications must not assume that it actually refers to the traditional sticky bit.
find . find . -print
They both write out the entire directory hierarchy from the current directory.
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.
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.
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.
find . -print -name SCCS -prune
behaves as in the previous example, but prints the names of the SCCS directories.
if [ -n "$(find file1 -prune -newer file2)" ]; then
printf %s\\n "file1 is newer than file2" fi
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.
find . ! -name . -prune -name '*.old' -exec \
sh -c 'mv "$@" ../old/' sh {} +
performs the same task as:
mv ./*.old ./.old ./.*.old ../old/
while avoiding an ``Argument list too long'' error if there are a large number of files ending with .old and without running mv if there are no such files (and avoiding ``No such file or directory'' errors if ./.old does not exist or no files match ./*.old or ./.*.old).
The alternative:
find . ! -name . -prune -name '*.old' -exec mv {} ../old/ \;
is less efficient if there are many files to move because it executes one mv command per file.
find / -path /media -prune -o -size +200000 -print
find foo/// bar/// -name foo -o -name 'bar?*'
prints only the line "foo///".
The -a operator was retained as an optional operator for compatibility with historical shell scripts, even though it is redundant with expression concatenation.
The descriptions of the '-' modifier on the mode and onum arguments to the -perm primary agree with historical practice on 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:
Therefore, an application using this prompting option relies on the system to provide the most suitable dialog 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.
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 st_size field defined in the System Interfaces volume of POSIX.1‐2017 should be used, not the st_blocks found in historical implementations. There are at least two reasons for this:
The descriptions of -atime, -ctime, and -mtime were changed from the SVID description of n ``days'' to n being the result of the integer division of the time difference in seconds by 86400. 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 86400 second period in the past, not any time from the beginning of that period to the current time. For example, -atime 2 is true if the file was accessed any time in the period from 72 hours 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 volume of POSIX.1‐2017 allows the desired behavior. At least one recent implementation does support this feature, but encountered 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 to correct a historical pitfall that plagues novice users, it is entirely upwards-compatible from the historical System V find utility. In its simplest form (find directory), it could be confused with the historical BSD fast find. The BSD developers agreed that adding -print as a default expression was the correct decision and have added the fast find functionality within a new utility called locate.
Historically, the -L option was implemented using the primary -follow. The -H and -L options were added for two reasons. First, they offer a finer granularity of control and consistency with other programs that walk file hierarchies. Second, the -follow primary always evaluated to true. As they were historically really global variables that took effect before the traversal began, some valid expressions had unexpected results. An example is the expression -print -o -follow. Because -print always evaluates to true, the standard order of evaluation implies that -follow would never be evaluated. This was never the case. Historical practice for the -follow primary, however, is not consistent. Some implementations always follow symbolic links on the command line whether -follow is specified or not. Others follow symbolic links on the command line only if -follow is specified. Both behaviors are provided by the -H and -L options, but scripts using the current -follow primary would be broken if the -follow option is specified to work either way.
Since the -L option resolves all symbolic links and the -type l primary is true for symbolic links that still exist after symbolic links have been resolved, the command:
find -L . -type l
prints a list of symbolic links reachable from the current directory that do not resolve to accessible files.
A feature of SVR4's find utility was the -exec primary's + terminator. This allowed filenames containing special characters (especially <newline> characters) to be grouped together without the problems that occur if such filenames are piped to xargs. Other implementations have added other ways to get around this problem, notably a -print0 primary that wrote filenames with a null byte terminator. This was considered here, but not adopted. Using a null terminator meant that any utility that was going to process find's -print0 output had to add a new option to parse the null terminators it would now be reading.
The "-exec...{}+" syntax adopted was a result of IEEE PASC Interpretation 1003.2 #210. It should be noted that this is an incompatible change to IEEE Std 1003.2‐1992. For example, the following command printed all files with a '-' after their name if they are regular files, and a '+' otherwise:
find / -type f -exec echo {} - ';' -o -exec echo {} + ';'
The change invalidates usage like this. Even though the previous standard stated that this usage would work, in practice many did not support it and the standard developers felt it better to now state that this was not allowable.
None.
Section 2.2, Quoting, Section 2.13, Pattern Matching Notation, Section 2.14, Special Built-In Utilities, chmod, mv, pax, sh, test
The Base Definitions volume of POSIX.1‐2017, Chapter 8, Environment Variables, Section 12.2, Utility Syntax Guidelines
The System Interfaces volume of POSIX.1‐2017, fstatat(), getgrgid(), getpwuid()
Portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1-2017, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 7, 2018 Edition, Copyright (C) 2018 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between this version and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html .
Any typographical or formatting errors that appear in this page are most likely to have been introduced during the conversion of the source files to man page format. To report such errors, see https://www.kernel.org/doc/man-pages/reporting_bugs.html .
| 2017 | IEEE/The Open Group |