1FIND(1P) POSIX Programmer's Manual FIND(1P)
2
6 This manual page is part of the POSIX Programmer's Manual. The Linux
7 implementation of this interface may differ (consult the corresponding
8 Linux manual page for details of Linux behavior), or the interface may
9 not be implemented on Linux.
10
13 find — find files
14
16 find [−H|−L] path... [operand_expression...]
17
19 The find utility shall recursively descend the directory hierarchy from
20 each file specified by path, evaluating a Boolean expression composed
21 of the primaries described in the OPERANDS section for each file
22 encountered. Each path operand shall be evaluated unaltered as it was
23 provided, including all trailing <slash> characters; all pathnames for
24 other files encountered in the hierarchy shall consist of the concate‐
25 nation of the current path operand, a <slash> if the current path oper‐
26 and did not end in one, and the filename relative to the path operand.
27 The relative portion shall contain no dot or dot-dot components, no
28 trailing <slash> characters, and only single <slash> characters between
29 pathname components.
30 The find utility shall be able to descend to arbitrary depths in a file
32 hierarchy and shall not fail due to path length limitations (unless a
33 path operand specified by the application exceeds {PATH_MAX} require‐
34 ments).
35 The find utility shall detect infinite loops; that is, entering a pre‐
37 viously visited directory that is an ancestor of the last file encoun‐
38 tered. When it detects an infinite loop, find shall write a diagnostic
39 message to standard error and shall either recover its position in the
40 hierarchy or terminate.
41 If a file is removed from or added to the directory hierarchy being
43 searched it is unspecified whether or not find includes that file in
44 its search.
45
47 The find utility shall conform to the Base Definitions volume of
48 POSIX.1‐2008, Section 12.2, Utility Syntax Guidelines.
49 The following options shall be supported by the implementation:
51 −H Cause the file information and file type evaluated for each
53 symbolic link encountered as a path operand on the command
54 line to be those of the file referenced by the link, and not
55 the link itself. If the referenced file does not exist, the
56 file information and type shall be for the link itself. File
57 information and type for symbolic links encountered during
58 the traversal of a file hierarchy shall be that of the link
59 itself.
60 −L Cause the file information and file type evaluated for each
62 symbolic link encountered as a path operand on the command
63 line or encountered during the traversal of a file hierarchy
64 to be those of the file referenced by the link, and not the
65 link itself. If the referenced file does not exist, the file
66 information and type shall be for the link itself.
67 Specifying more than one of the mutually-exclusive options −H and −L
69 shall not be considered an error. The last option specified shall
70 determine the behavior of the utility. If neither the −H nor the −L
71 option is specified, then the file information and type for symbolic
72 links encountered as a path operand on the command line or encountered
73 during the traversal of a file hierarchy shall be that of the link
74 itself.
75
77 The following operands shall be supported:
78 The first operand and subsequent operands up to but not including the
80 first operand that starts with a '−', or is a '!' or a '(', shall be
81 interpreted as path operands. If the first operand starts with a '−',
82 or is a '!' or a '(', the behavior is unspecified. Each path operand
83 is a pathname of a starting point in the file hierarchy.
84 The first operand that starts with a '−', or is a '!' or a '(', and
86 all subsequent arguments shall be interpreted as an expression made up
87 of the following primaries and operators. In the descriptions, wherever
88 n is used as a primary argument, it shall be interpreted as a decimal
89 integer optionally preceded by a plus ('+') or minus-sign ('−') sign,
90 as follows:
91 +n More than n.
93 n Exactly n.
95 −n Less than n.
97 The following primaries shall be supported:
99 −name pattern
101 The primary shall evaluate as true if the basename of the
102 current pathname matches pattern using the pattern matching
103 notation described in Section 2.13, Pattern Matching Nota‐
104 tion. The additional rules in Section 2.13.3, Patterns Used
105 for Filename Expansion do not apply as this is a matching
106 operation, not an expansion.
107 −path pattern
109 The primary shall evaluate as true if the current pathname
110 matches pattern using the pattern matching notation described
111 in Section 2.13, Pattern Matching Notation. The additional
112 rules in Section 2.13.3, Patterns Used for Filename Expansion
113 do not apply as this is a matching operation, not an expan‐
114 sion.
115 −nouser The primary shall evaluate as true if the file belongs to a
117 user ID for which the getpwuid() function defined in the Sys‐
118 tem Interfaces volume of POSIX.1‐2008 (or equivalent) returns
119 NULL.
120 −nogroup The primary shall evaluate as true if the file belongs to a
122 group ID for which the getgrgid() function defined in the
123 System Interfaces volume of POSIX.1‐2008 (or equivalent)
124 returns NULL.
125 −xdev The primary shall always evaluate as true; it shall cause
127 find not to continue descending past directories that have a
128 different device ID (st_dev, see the stat() function defined
129 in the System Interfaces volume of POSIX.1‐2008). If any
130 −xdev primary is specified, it shall apply to the entire
131 expression even if the −xdev primary would not normally be
132 evaluated.
133 −prune The primary shall always evaluate as true; it shall cause
135 find not to descend the current pathname if it is a direc‐
136 tory. If the −depth primary is specified, the −prune primary
137 shall have no effect.
138 −perm [−]mode
140 The mode argument is used to represent file mode bits. It
141 shall be identical in format to the symbolic_mode operand
142 described in chmod, and shall be interpreted as follows. To
143 start, a template shall be assumed with all file mode bits
144 cleared. An op symbol of '+' shall set the appropriate mode
145 bits in the template; '−' shall clear the appropriate bits;
146 '=' shall set the appropriate mode bits, without regard to
147 the contents of the file mode creation mask of the process.
148 The op symbol of '−' cannot be the first character of mode;
149 this avoids ambiguity with the optional leading <hyphen>.
150 Since the initial mode is all bits off, there are not any
151 symbolic modes that need to use '−' as the first character.
152 If the <hyphen> is omitted, the primary shall evaluate as
154 true when the file permission bits exactly match the value of
155 the resulting template.
156 Otherwise, if mode is prefixed by a <hyphen>, the primary
158 shall evaluate as true if at least all the bits in the
159 resulting template are set in the file permission bits.
160 −perm [−]onum
162 If the <hyphen> is omitted, the primary shall evaluate as
163 true when the file mode bits exactly match the value of the
164 octal number onum (see the description of the octal mode in
165 chmod). Otherwise, if onum is prefixed by a <hyphen>, the
166 primary shall evaluate as true if at least all of the bits
167 specified in onum are set. In both cases, the behavior is
168 unspecified when onum exceeds 07777.
169 −type c The primary shall evaluate as true if the type of the file is
171 c, where c is 'b', 'c', 'd', 'l', 'p', 'f', or 's' for block
172 special file, character special file, directory, symbolic
173 link, FIFO, regular file, or socket, respectively.
174 −links n The primary shall evaluate as true if the file has n links.
176 −user uname
178 The primary shall evaluate as true if the file belongs to the
179 user uname. If uname is a decimal integer and the getpwnam()
180 (or equivalent) function does not return a valid user name,
181 uname shall be interpreted as a user ID.
182 −group gname
184 The primary shall evaluate as true if the file belongs to the
185 group gname. If gname is a decimal integer and the getgr‐
186 nam() (or equivalent) function does not return a valid group
187 name, gname shall be interpreted as a group ID.
188 −size n[c]
190 The primary shall evaluate as true if the file size in bytes,
191 divided by 512 and rounded up to the next integer, is n. If
192 n is followed by the character 'c', the size shall be in
193 bytes.
194 −atime n The primary shall evaluate as true if the file access time
196 subtracted from the initialization time, divided by 86400
197 (with any remainder discarded), is n.
198 −ctime n The primary shall evaluate as true if the time of last change
200 of file status information subtracted from the initialization
201 time, divided by 86400 (with any remainder discarded), is n.
202 −mtime n The primary shall evaluate as true if the file modification
204 time subtracted from the initialization time, divided by
205 86400 (with any remainder discarded), is n.
206 −exec utility_name [argument ...] ;
208 −exec utility_name [argument ...] {} +
210 The end of the primary expression shall be punctuated by a
211 <semicolon> or by a <plus-sign>. Only a <plus-sign> that
212 immediately follows an argument containing only the two char‐
213 acters "{}" shall punctuate the end of the primary expres‐
214 sion. Other uses of the <plus-sign> shall not be treated as
215 special.
216 If the primary expression is punctuated by a <semicolon>, the
218 utility utility_name shall be invoked once for each pathname
219 and the primary shall evaluate as true if the utility returns
220 a zero value as exit status. A utility_name or argument con‐
221 taining only the two characters "{}" shall be replaced by the
222 current pathname. If a utility_name or argument string con‐
223 tains the two characters "{}", but not just the two charac‐
224 ters "{}", it is implementation-defined whether find replaces
225 those two characters or uses the string without change.
226 If the primary expression is punctuated by a <plus-sign>, the
228 primary shall always evaluate as true, and the pathnames for
229 which the primary is evaluated shall be aggregated into sets.
230 The utility utility_name shall be invoked once for each set
231 of aggregated pathnames. Each invocation shall begin after
232 the last pathname in the set is aggregated, and shall be com‐
233 pleted before the find utility exits and before the first
234 pathname in the next set (if any) is aggregated for this pri‐
235 mary, but it is otherwise unspecified whether the invocation
236 occurs before, during, or after the evaluations of other pri‐
237 maries. If any invocation returns a non-zero value as exit
238 status, the find utility shall return a non-zero exit status.
239 An argument containing only the two characters "{}" shall be
240 replaced by the set of aggregated pathnames, with each path‐
241 name passed as a separate argument to the invoked utility in
242 the same order that it was aggregated. The size of any set of
243 two or more pathnames shall be limited such that execution of
244 the utility does not cause the system's {ARG_MAX} limit to be
245 exceeded. If more than one argument containing the two char‐
246 acters "{}" is present, the behavior is unspecified.
247 The current directory for the invocation of utility_name
249 shall be the same as the current directory when the find
250 utility was started. If the utility_name names any of the
251 special built-in utilities (see Section 2.14, Special Built-
252 In Utilities), the results are undefined.
253 −ok utility_name [argument ...] ;
255 The −ok primary shall be equivalent to −exec, except that the
256 use of a <plus-sign> to punctuate the end of the primary
257 expression need not be supported, and find shall request
258 affirmation of the invocation of utility_name using the cur‐
259 rent file as an argument by writing to standard error as
260 described in the STDERR section. If the response on standard
261 input is affirmative, the utility shall be invoked. Other‐
262 wise, the command shall not be invoked and the value of the
263 −ok operand shall be false.
264 −print The primary shall always evaluate as true; it shall cause the
266 current pathname to be written to standard output.
267 −newer file
269 The primary shall evaluate as true if the modification time
270 of the current file is more recent than the modification time
271 of the file named by the pathname file.
272 −depth The primary shall always evaluate as true; it shall cause
274 descent of the directory hierarchy to be done so that all
275 entries in a directory are acted on before the directory
276 itself. If a −depth primary is not specified, all entries in
277 a directory shall be acted on after the directory itself. If
278 any −depth primary is specified, it shall apply to the entire
279 expression even if the −depth primary would not normally be
280 evaluated.
281 The primaries can be combined using the following operators (in order
283 of decreasing precedence):
284 ( expression )
286 True if expression is true.
287 ! expression
289 Negation of a primary; the unary NOT operator.
290 expression [−a] expression
292 Conjunction of primaries; the AND operator is implied by the
293 juxtaposition of two primaries or made explicit by the
294 optional −a operator. The second expression shall not be
295 evaluated if the first expression is false.
296 expression −o expression
298 Alternation of primaries; the OR operator. The second expres‐
299 sion shall not be evaluated if the first expression is true.
300 If no expression is present, −print shall be used as the expression.
302 Otherwise, if the given expression does not contain any of the pri‐
303 maries −exec, −ok, or −print, the given expression shall be effectively
304 replaced by:
305 ( given_expression ) −print
307 The −user, −group, and −newer primaries each shall evaluate their
309 respective arguments only once.
310 When the file type evaluated for the current file is a symbolic link,
312 the results of evaluating the −perm primary are implementation-defined.
313
315 If the −ok primary is used, the response shall be read from the stan‐
316 dard input. An entire line shall be read as the response. Otherwise,
317 the standard input shall not be used.
318
320 None.
321
323 The following environment variables shall affect the execution of find:
324 LANG Provide a default value for the internationalization vari‐
326 ables that are unset or null. (See the Base Definitions vol‐
327 ume of POSIX.1‐2008, Section 8.2, Internationalization Vari‐
328 ables for the precedence of internationalization variables
329 used to determine the values of locale categories.)
330 LC_ALL If set to a non-empty string value, override the values of
332 all the other internationalization variables.
333 LC_COLLATE
335 Determine the locale for the behavior of ranges, equivalence
336 classes, and multi-character collating elements used in the
337 pattern matching notation for the −n option and in the
338 extended regular expression defined for the yesexpr locale
339 keyword in the LC_MESSAGES category.
340 LC_CTYPE This variable determines the locale for the interpretation of
342 sequences of bytes of text data as characters (for example,
343 single-byte as opposed to multi-byte characters in argu‐
344 ments), the behavior of character classes within the pattern
345 matching notation used for the −n option, and the behavior of
346 character classes within regular expressions used in the
347 extended regular expression defined for the yesexpr locale
348 keyword in the LC_MESSAGES category.
349 LC_MESSAGES
351 Determine the locale used to process affirmative responses,
352 and the locale used to affect the format and contents of
353 diagnostic messages and prompts written to standard error.
354 NLSPATH Determine the location of message catalogs for the processing
356 of LC_MESSAGES.
357 PATH Determine the location of the utility_name for the −exec and
359 −ok primaries, as described in the Base Definitions volume of
360 POSIX.1‐2008, Chapter 8, Environment Variables.
361
363 Default.
364
366 The −print primary shall cause the current pathnames to be written to
367 standard output. The format shall be:
368 "%s\n", <path>
370
372 The −ok primary shall write a prompt to standard error containing at
373 least the utility_name to be invoked and the current pathname. In the
374 POSIX locale, the last non-<blank> in the prompt shall be '?'. The
375 exact format used is unspecified.
376 Otherwise, the standard error shall be used only for diagnostic mes‐
378 sages.
379
381 None.
382
384 None.
385
387 The following exit values shall be returned:
388 0 All path operands were traversed successfully.
390 >0 An error occurred.
392
394 Default.
395 The following sections are informative.
397
399 When used in operands, pattern matching notation, <semicolon>, <left-
400 parenthesis>, and <right-parenthesis> characters are special to the
401 shell and must be quoted (see Section 2.2, Quoting).
402 The bit that is traditionally used for sticky (historically 01000) is
404 specified in the −perm primary using the octal number argument form.
405 Since this bit is not defined by this volume of POSIX.1‐2008, applica‐
406 tions must not assume that it actually refers to the traditional sticky
407 bit.
408
410 1. The following commands are equivalent:
411 find .
413 find . −print
414 They both write out the entire directory hierarchy from the current
416 directory.
417 2. The following command:
419 find / \( −name tmp −o −name '*.xx' \) −atime +7 −exec rm {} \;
421 removes all files named tmp or ending in .xx that have not been
423 accessed for seven or more 24-hour periods.
424 3. The following command:
426 find . −perm −o+w,+s
428 prints (−print is assumed) the names of all files in or below the
430 current directory, with all of the file permission bits S_ISUID,
431 S_ISGID, and S_IWOTH set.
432 4. The following command:
434 find . −name SCCS −prune −o −print
436 recursively prints pathnames of all files in the current directory
438 and below, but skips directories named SCCS and files in them.
439 5. The following command:
441 find . −print −name SCCS −prune
443 behaves as in the previous example, but prints the names of the
445 SCCS directories.
446 6. The following command is roughly equivalent to the −nt extension to
448 test:
449 if [ −n "$(find file1 −prune −newer file2)" ]; then
451 printf %s\\n "file1 is newer than file2"
452 fi
453 7. The descriptions of −atime, −ctime, and −mtime use the terminology
455 n ``86400 second periods (days)''. For example, a file accessed at
456 23:59 is selected by:
457 find . −atime −1 −print
459 at 00:01 the next day (less than 24 hours later, not more than one
461 day ago); the midnight boundary between days has no effect on the
462 24-hour calculation.
463 8. The following command:
465 find . ! −name . −prune −name '*.old' −exec \
467 sh −c 'mv "$@" ../old/' sh {} +
468 performs the same task as:
470 mv ./*.old ./.old ./.*.old ../old/
472 while avoiding an ``Argument list too long'' error if there are a
474 large number of files ending with .old and without running mv if
475 there are no such files (and avoiding ``No such file or directory''
476 errors if ./.old does not exist or no files match ./*.old or
477 ./.*.old).
478 The alternative:
480 find . ! −name . −prune −name '*.old' −exec mv {} ../old/ \;
482 is less efficient if there are many files to move because it exe‐
484 cutes one mv command per file.
485 9. On systems configured to mount removable media on directories under
487 /media, the following command searches the file hierarchy for files
488 larger than 100000 KB without searching any mounted removable
489 media:
490 find / −path /media −prune −o −size +200000 −print
492 10. Except for the root directory, and "//" on implementations where
494 "//" does not refer to the root directory, no pattern given to
495 −name will match a <slash>, because trailing <slash> characters are
496 ignored when computing the basename of the file under evaluation.
497 Given two empty directories named foo and bar, the following com‐
498 mand:
499 find foo/// bar/// −name foo −o −name 'bar?*'
501 prints only the line "foo///".
503
505 The −a operator was retained as an optional operator for compatibility
506 with historical shell scripts, even though it is redundant with expres‐
507 sion concatenation.
508 The descriptions of the '−' modifier on the mode and onum arguments to
510 the −perm primary agree with historical practice on BSD and System V
511 implementations. System V and BSD documentation both describe it in
512 terms of checking additional bits; in fact, it uses the same bits, but
513 checks for having at least all of the matching bits set instead of hav‐
514 ing exactly the matching bits set.
515 The exact format of the interactive prompts is unspecified. Only the
517 general nature of the contents of prompts are specified because:
518 * Implementations may desire more descriptive prompts than those used
520 on historical implementations.
521 * Since the historical prompt strings do not terminate with <newline>
523 characters, there is no portable way for another program to inter‐
524 act with the prompts of this utility via pipes.
525 Therefore, an application using this prompting option relies on the
527 system to provide the most suitable dialog directly with the user,
528 based on the general guidelines specified.
529 The −name file operand was changed to use the shell pattern matching
531 notation so that find is consistent with other utilities using pattern
532 matching.
533 The −size operand refers to the size of a file, rather than the number
535 of blocks it may occupy in the file system. The intent is that the
536 st_size field defined in the System Interfaces volume of POSIX.1‐2008
537 should be used, not the st_blocks found in historical implementations.
538 There are at least two reasons for this:
539 1. In both System V and BSD, find only uses st_size in size calcula‐
541 tions for the operands specified by this volume of POSIX.1‐2008.
542 (BSD uses st_blocks only when processing the −ls primary.)
543 2. Users usually think of file size in terms of bytes, which is also
545 the unit used by the ls utility for the output from the −l option.
546 (In both System V and BSD, ls uses st_size for the −l option size
547 field and uses st_blocks for the ls −s calculations. This volume of
548 POSIX.1‐2008 does not specify ls −s.)
549 The descriptions of −atime, −ctime, and −mtime were changed from the
551 SVID description of n ``days'' to n being the result of the integer
552 division of the time difference in seconds by 86400. The description is
553 also different in terms of the exact timeframe for the n case (versus
554 the +n or −n), but it matches all known historical implementations. It
555 refers to one 86400 second period in the past, not any time from the
556 beginning of that period to the current time. For example, −atime 2 is
557 true if the file was accessed any time in the period from 72 hours to
558 48 hours ago.
559 Historical implementations do not modify "{}" when it appears as a sub‐
561 string of an −exec or −ok utility_name or argument string. There have
562 been numerous user requests for this extension, so this volume of
563 POSIX.1‐2008 allows the desired behavior. At least one recent implemen‐
564 tation does support this feature, but encountered several problems in
565 managing memory allocation and dealing with multiple occurrences of
566 "{}" in a string while it was being developed, so it is not yet
567 required behavior.
568 Assuming the presence of −print was added to correct a historical pit‐
570 fall that plagues novice users, it is entirely upwards-compatible from
571 the historical System V find utility. In its simplest form (find direc‐
572 tory), it could be confused with the historical BSD fast find. The BSD
573 developers agreed that adding −print as a default expression was the
574 correct decision and have added the fast find functionality within a
575 new utility called locate.
576 Historically, the −L option was implemented using the primary −follow.
578 The −H and −L options were added for two reasons. First, they offer a
579 finer granularity of control and consistency with other programs that
580 walk file hierarchies. Second, the −follow primary always evaluated to
581 true. As they were historically really global variables that took
582 effect before the traversal began, some valid expressions had unex‐
583 pected results. An example is the expression −print −o −follow.
584 Because −print always evaluates to true, the standard order of evalua‐
585 tion implies that −follow would never be evaluated. This was never the
586 case. Historical practice for the −follow primary, however, is not con‐
587 sistent. Some implementations always follow symbolic links on the com‐
588 mand line whether −follow is specified or not. Others follow symbolic
589 links on the command line only if −follow is specified. Both behaviors
590 are provided by the −H and −L options, but scripts using the current
591 −follow primary would be broken if the −follow option is specified to
592 work either way.
593 Since the −L option resolves all symbolic links and the −type l primary
595 is true for symbolic links that still exist after symbolic links have
596 been resolved, the command:
597 find −L . −type l
599 prints a list of symbolic links reachable from the current directory
601 that do not resolve to accessible files.
602 A feature of SVR4's find utility was the −exec primary's + terminator.
604 This allowed filenames containing special characters (especially <new‐
605 line> characters) to be grouped together without the problems that
606 occur if such filenames are piped to xargs. Other implementations have
607 added other ways to get around this problem, notably a −print0 primary
608 that wrote filenames with a null byte terminator. This was considered
609 here, but not adopted. Using a null terminator meant that any utility
610 that was going to process find's −print0 output had to add a new option
611 to parse the null terminators it would now be reading.
612 The "−exec...{}+" syntax adopted was a result of IEEE PASC Interpreta‐
614 tion 1003.2 #210. It should be noted that this is an incompatible
615 change to IEEE Std 1003.2‐1992. For example, the following command
616 printed all files with a '−' after their name if they are regular
617 files, and a '+' otherwise:
618 find / −type f −exec echo {} − ';' −o −exec echo {} + ';'
620 The change invalidates usage like this. Even though the previous stan‐
622 dard stated that this usage would work, in practice many did not sup‐
623 port it and the standard developers felt it better to now state that
624 this was not allowable.
625
627 None.
628
630 Section 2.2, Quoting, Section 2.13, Pattern Matching Notation, Section
631 2.14, Special Built-In Utilities, chmod, mv, pax, sh, test
632 The Base Definitions volume of POSIX.1‐2008, Chapter 8, Environment
634 Variables, Section 12.2, Utility Syntax Guidelines
635 The System Interfaces volume of POSIX.1‐2008, fstatat(), getgrgid(),
637 getpwuid()
638
640 Portions of this text are reprinted and reproduced in electronic form
641 from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
642 -- Portable Operating System Interface (POSIX), The Open Group Base
643 Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
644 cal and Electronics Engineers, Inc and The Open Group. (This is
645 POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the
646 event of any discrepancy between this version and the original IEEE and
647 The Open Group Standard, the original IEEE and The Open Group Standard
648 is the referee document. The original Standard can be obtained online
649 at http://www.unix.org/online.html .
650 Any typographical or formatting errors that appear in this page are
652 most likely to have been introduced during the conversion of the source
653 files to man page format. To report such errors, see https://www.ker‐
654 nel.org/doc/man-pages/reporting_bugs.html .
655IEEE/The Open Group 2013 FIND(1P)