find(1posix)
NAME
find --- find files
SYNOPSIS
find [H|L] path... [operand_expression...]
DESCRIPTION
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.
OPTIONS
The find utility shall conform to the Base Definitions volume of
POSIX.12008, Section 12.2, Utility Syntax Guidelines.
The following options shall be supported by the implementation:
H Cause the file information and file type evaluated for each
symbolic link encountered as a path operand on the command
line to be those of the file referenced by the link, and not
the link itself. If the referenced file does not exist, the
file information and type shall be for the link itself. File
information and type for symbolic links encountered during
the traversal of a file hierarchy shall be that of the link
itself.
L Cause the file information and file type evaluated for each
symbolic link encountered as a path operand on the command
line or encountered during the traversal of a file hierarchy
to be those of the file referenced by the link, and not the
link itself. If the referenced file does not exist, the file
information and type shall be for the link itself.
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.
OPERANDS
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 ('+') or minus-sign ('') sign,
as follows:
+n More than n.
n Exactly n.
n Less than n.
The following primaries shall be supported:
name pattern
The primary shall evaluate as true if the basename of the
current pathname matches pattern using the pattern matching
notation described in Section 2.13, Pattern Matching
Notation. The additional rules in Section 2.13.3, Patterns
Used for Filename Expansion do not apply as this is a
matching operation, not an expansion.
path pattern
The primary shall evaluate as true if the current pathname
matches pattern using the pattern matching notation described
in Section 2.13, Pattern Matching Notation. The additional
rules in Section 2.13.3, Patterns Used for Filename Expansion
do not apply as this is a matching operation, not an
expansion.
nouser The primary shall evaluate as true if the file belongs to a
user ID for which the getpwuid() function defined in the
System Interfaces volume of POSIX.12008 (or equivalent)
returns NULL.
nogroup The primary shall evaluate as true if the file belongs to a
group ID for which the getgrgid() function defined in the
System Interfaces volume of POSIX.12008 (or equivalent)
returns NULL.
xdev The primary shall always evaluate as true; it shall cause
find not to continue descending past directories that have a
different device ID (st_dev, see the stat() function defined
in the System Interfaces volume of POSIX.12008). If any
xdev primary is specified, it shall apply to the entire
expression even if the xdev primary would not normally be
evaluated.
prune The primary shall always 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.
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, 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 the file mode creation mask of the process.
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 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
If the <hyphen> is omitted, the primary shall evaluate as
true when the file mode bits exactly match the value of the
octal number onum (see the description of the octal mode in
chmod). Otherwise, if onum is prefixed by a <hyphen>, the
primary shall evaluate as true if at least all of the bits
specified in onum are set. In both cases, the behavior is
unspecified when onum exceeds 07777.
type c The primary shall evaluate as true if the type of the file is
c, where c is 'b', 'c', 'd', 'l', 'p', 'f', or 's' for block
special file, character special file, directory, symbolic
link, FIFO, regular file, or socket, respectively.
links n The primary shall evaluate as true if the file has n links.
user uname
The primary shall 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 shall be interpreted as a user ID.
group gname
The primary shall 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 shall be interpreted as a group ID.
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.
atime n The primary shall evaluate as true if the file access time
subtracted from the initialization time, divided by 86400
(with any remainder discarded), is n.
ctime n The primary shall evaluate as true if the time of last change
of file status information subtracted from the initialization
time, divided by 86400 (with any remainder discarded), is n.
mtime n The primary shall evaluate as true if the file modification
time subtracted from the initialization time, divided by
86400 (with any remainder discarded), is n.
exec utility_name [argument ...] ;
exec utility_name [argument ...] {} +
The end of the primary expression shall be punctuated by a
<semicolon> or by a <plus-sign>. Only a <plus-sign> that
immediately follows an argument containing only the two
characters "{}" shall punctuate the end of the primary
expression. Other uses of the <plus-sign> shall not be
treated as special.
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.
ok utility_name [argument ...] ;
The ok primary shall be equivalent to exec, except that the
use of a <plus-sign> to punctuate the end of the primary
expression need not be supported, and 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 the STDERR section. 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.
print The primary shall always evaluate as true; it shall cause the
current pathname to be written to standard output.
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.
depth The primary shall always 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.
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 NOT operator.
expression [a] expression
Conjunction of primaries; the AND operator is 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.
When the file type evaluated for the current file is a symbolic link,
the results of evaluating the perm primary are implementation-defined.
STDIN
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.
INPUT FILES
None.
ENVIRONMENT VARIABLES
The following environment variables shall affect the execution of find:
LANG Provide a default value for the internationalization
variables that are unset or null. (See the Base Definitions
volume of POSIX.12008, Section 8.2, Internationalization
Variables for the precedence of internationalization
variables used to determine the values of locale categories.)
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 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 determines the locale for the interpretation of
sequences of bytes of text data as characters (for example,
single-byte as opposed to multi-byte characters in
arguments), the behavior of character classes within the
pattern matching notation used for the n 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.
LC_MESSAGES
Determine the locale used to process affirmative responses,
and the locale used to affect the format and contents of
diagnostic messages and prompts written to standard error.
NLSPATH Determine the location of message catalogs for the processing
of LC_MESSAGES.
PATH Determine the location of the utility_name for the exec and
ok primaries, as described in the Base Definitions volume of
POSIX.12008, Chapter 8, Environment Variables.
ASYNCHRONOUS EVENTS
Default.
STDOUT
The print primary shall cause the current pathnames to be written to
standard output. The format shall be:
"%s\n", <path>
STDERR
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.
OUTPUT FILES
None.
EXTENDED DESCRIPTION
None.
EXIT STATUS
The following exit values shall be returned:
0 All path operands were traversed successfully.
>0 An error occurred.
CONSEQUENCES OF ERRORS
Default. The following sections are informative.
APPLICATION USAGE
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.12008, applications must not assume that it actually refers to the traditional sticky bit.
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 ``86400 second periods (days)''. For example, a file accessed at
23:59 is 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.
8. The following command:
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.
9. On systems configured to mount removable media on directories under
/media, the following command searches the file hierarchy for files
larger than 100000 KB without searching any mounted removable
media:
find / path /media prune o size +200000 print
10. Except for the root directory, and "//" on implementations where
"//" does not refer to the root directory, no pattern given to
name will match a <slash>, because trailing <slash> characters are
ignored when computing the basename of the file under evaluation.
Given two empty directories named foo and bar, the following
command:
find foo/// bar/// name foo o name 'bar?*'
prints only the line "foo///".
RATIONALE
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:
* Implementations may desire more descriptive prompts than those used
on historical implementations.
* Since the historical prompt strings do not terminate with <newline>
characters, 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 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.12008
should be used, not the st_blocks found in historical implementations.
There are at least two reasons for this:
1. In both System V and BSD, find only uses st_size in size
calculations for the operands specified by this volume of
POSIX.12008. (BSD uses st_blocks only when processing the ls
primary.)
2. Users usually think of file size in terms of bytes, which is also
the unit used by the ls utility for the output from the l option.
(In both System V and BSD, ls uses st_size for the l option size
field and uses st_blocks for the ls s calculations. This volume of
POSIX.12008 does not specify ls s.)
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.12008 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.21992. 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.
FUTURE DIRECTIONS
None.
SEE ALSO
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.12008, Chapter 8, Environment Variables, Section 12.2, Utility Syntax Guidelines The System Interfaces volume of POSIX.12008, fstatat(), getgrgid(), getpwuid()
COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 7, Copyright (C) 2013 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. (This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) 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.unix.org/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 .
Opportunity
Personal Opportunity - Free software gives you access to billions of dollars of software at no cost. Use this software for your business, personal use or to develop a profitable skill. Access to source code provides access to a level of capabilities/information that companies protect though copyrights. Open source is a core component of the Internet and it is available to you. Leverage the billions of dollars in resources and capabilities to build a career, establish a business or change the world. The potential is endless for those who understand the opportunity.
Business Opportunity - Goldman Sachs, IBM and countless large corporations are leveraging open source to reduce costs, develop products and increase their bottom lines. Learn what these companies know about open source and how open source can give you the advantage.
Free Software
Free Software provides computer programs and capabilities at no cost but more importantly, it provides the freedom to run, edit, contribute to, and share the software. The importance of free software is a matter of access, not price. Software at no cost is a benefit but ownership rights to the software and source code is far more significant.
Free Office Software - The Libre Office suite provides top desktop productivity tools for free. This includes, a word processor, spreadsheet, presentation engine, drawing and flowcharting, database and math applications. Libre Office is available for Linux or Windows.
Free Books
The Free Books Library is a collection of thousands of the most popular public domain books in an online readable format. The collection includes great classical literature and more recent works where the U.S. copyright has expired. These books are yours to read and use without restrictions.
Source Code - Want to change a program or know how it works? Open Source provides the source code for its programs so that anyone can use, modify or learn how to write those programs themselves. Visit the GNU source code repositories to download the source.
Education
Study at Harvard, Stanford or MIT - Open edX provides free online courses from Harvard, MIT, Columbia, UC Berkeley and other top Universities. Hundreds of courses for almost all major subjects and course levels. Open edx also offers some paid courses and selected certifications.
Linux Manual Pages - A man or manual page is a form of software documentation found on Linux/Unix operating systems. Topics covered include computer programs (including library and system calls), formal standards and conventions, and even abstract concepts.
