PROLOG | NAME | SYNOPSIS | DESCRIPTION | OPTIONS | OPERANDS | STDIN | INPUT FILES | ENVIRONMENT VARIABLES | ASYNCHRONOUS EVENTS | STDOUT | STDERR | OUTPUT FILES | EXTENDED DESCRIPTION | EXIT STATUS | CONSEQUENCES OF ERRORS | APPLICATION USAGE | EXAMPLES | RATIONALE | FUTURE DIRECTIONS | SEE ALSO | COPYRIGHT

FIND(1P)                  POSIX Programmer's Manual                 FIND(1P)

PROLOG         top

       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.

NAME         top

       find — find files

SYNOPSIS         top

       find [−H|−L] path... [operand_expression...]

DESCRIPTION         top

       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         top

       The find utility shall conform to the Base Definitions volume of
       POSIX.1‐2008, 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         top

       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.1‐2008 (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.1‐2008 (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.1‐2008).
                 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         top

       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         top

       None.

ENVIRONMENT VARIABLES         top

       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.1‐2008, 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.1‐2008, Chapter 8, Environment Variables.

ASYNCHRONOUS EVENTS         top

       Default.

STDOUT         top

       The −print primary shall cause the current pathnames to be written to
       standard output. The format shall be:

           "%s\n", <path>

STDERR         top

       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         top

       None.

EXTENDED DESCRIPTION         top

       None.

EXIT STATUS         top

       The following exit values shall be returned:

        0    All path operands were traversed successfully.

       >0    An error occurred.

CONSEQUENCES OF ERRORS         top

       Default.

       The following sections are informative.

APPLICATION USAGE         top

       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‐2008,
       applications must not assume that it actually refers to the
       traditional sticky bit.

EXAMPLES         top

        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         top

       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.1‐2008 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.1‐2008. (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.1‐2008 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.1‐2008 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.

FUTURE DIRECTIONS         top

       None.

SEE ALSO         top

       Section 2.2, Quoting, Section 2.13, Pattern Matching Notation,
       Section 2.14, Special Built-In Utilities, chmod(1p), mv(1p), pax(1p),
       sh(1p), test(1p)

       The Base Definitions volume of POSIX.1‐2008, Chapter 8, Environment
       Variables, Section 12.2, Utility Syntax Guidelines

       The System Interfaces volume of POSIX.1‐2008, fstatat(3p),
       getgrgid(3p), getpwuid(3p)

COPYRIGHT         top

       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 .

IEEE/The Open Group                 2013                            FIND(1P)

Pages that refer to this page: cp(1p)df(1p)diff(1p)ln(1p)ls(1p)test(1p)xargs(1p)