1FIND(P) POSIX Programmer's Manual FIND(P)
2
6 find - find files
7
9 find [-H | -L] path ... [operand_expression ...]
10
12 The find utility shall recursively descend the directory hierarchy from
13 each file specified by path, evaluating a Boolean expression composed
14 of the primaries described in the OPERANDS section for each file
15 encountered.
16 The find utility shall be able to descend to arbitrary depths in a file
18 hierarchy and shall not fail due to path length limitations (unless a
19 path operand specified by the application exceeds {PATH_MAX} require‐
20 ments).
21 The find utility shall detect infinite loops; that is, entering a pre‐
23 viously visited directory that is an ancestor of the last file encoun‐
24 tered. When it detects an infinite loop, find shall write a diagnostic
25 message to standard error and shall either recover its position in the
26 hierarchy or terminate.
27
29 The find utility shall conform to the Base Definitions volume of
30 IEEE Std 1003.1-2001, Section 12.2, Utility Syntax Guidelines.
31 The following options shall be supported by the implementation:
33 -H Cause the file information and file type evaluated for each sym‐
35 bolic link encountered on the command line to be those of the
36 file referenced by the link, and not the link itself. If the
37 referenced file does not exist, the file information and type
38 shall be for the link itself. File information for all symbolic
39 links not on the command line shall be that of the link itself.
40 -L Cause the file information and file type evaluated for each sym‐
42 bolic link to be those of the file referenced by the link, and
43 not the link itself.
44 Specifying more than one of the mutually-exclusive options -H and -L
47 shall not be considered an error. The last option specified shall
48 determine the behavior of the utility.
49
51 The following operands shall be supported:
52 The path operand is a pathname of a starting point in the directory
54 hierarchy.
55 The first argument that starts with a '-' , or is a '!' or a '(' , and
57 all subsequent arguments shall be interpreted as an expression made up
58 of the following primaries and operators. In the descriptions, wherever
59 n is used as a primary argument, it shall be interpreted as a decimal
60 integer optionally preceded by a plus ( '+' ) or minus ( '-' ) sign, as
61 follows:
62 +n More than n.
64 n Exactly n.
66 -n Less than n.
68 The following primaries shall be supported:
71 -name pattern
73 The primary shall evaluate as true if the basename of the file‐
75 name being examined matches pattern using the pattern matching
76 notation described in Pattern Matching Notation .
77 -nouser
79 The primary shall evaluate as true if the file belongs to a user
80 ID for which the getpwuid() function defined in the System
81 Interfaces volume of IEEE Std 1003.1-2001 (or equivalent)
82 returns NULL.
83 -nogroup
85 The primary shall evaluate as true if the file belongs to a
86 group ID for which the getgrgid() function defined in the System
87 Interfaces volume of IEEE Std 1003.1-2001 (or equivalent)
88 returns NULL.
89 -xdev The primary shall always evaluate as true; it shall cause find
91 not to continue descending past directories that have a differ‐
92 ent device ID ( st_dev, see the stat() function defined in the
93 System Interfaces volume of IEEE Std 1003.1-2001). If any -xdev
94 primary is specified, it shall apply to the entire expression
95 even if the -xdev primary would not normally be evaluated.
96 -prune The primary shall always evaluate as true; it shall cause find
98 not to descend the current pathname if it is a directory. If
99 the -depth primary is specified, the -prune primary shall have
100 no effect.
101 -perm [-]mode
103 The mode argument is used to represent file mode bits. It shall
105 be identical in format to the symbolic_mode operand described in
106 chmod() , and shall be interpreted as follows. To start, a tem‐
107 plate shall be assumed with all file mode bits cleared. An op
108 symbol of '+' shall set the appropriate mode bits in the tem‐
109 plate; '-' shall clear the appropriate bits; '=' shall set the
110 appropriate mode bits, without regard to the contents of
111 process' file mode creation mask. The op symbol of '-' cannot be
112 the first character of mode; this avoids ambiguity with the
113 optional leading hyphen. Since the initial mode is all bits off,
114 there are not any symbolic modes that need to use '-' as the
115 first character.
116 If the hyphen is omitted, the primary shall evaluate as true when the
118 file permission bits exactly match the value of the resulting template.
119 Otherwise, if mode is prefixed by a hyphen, the primary shall evaluate
121 as true if at least all the bits in the resulting template are set in
122 the file permission bits.
123 -perm [-]onum
125 If the hyphen is omitted, the primary shall evaluate as true
127 when the file permission bits exactly match the value of the
128 octal number onum and only the bits corresponding to the octal
129 mask 07777 shall be compared. (See the description of the octal
130 mode in chmod() .) Otherwise, if onum is prefixed by a hyphen,
131 the primary shall evaluate as true if at least all of the bits
132 specified in onum that are also set in the octal mask 07777 are
133 set.
134 -type c
136 The primary shall evaluate as true if the type of the file is c,
137 where c is 'b' , 'c' , 'd' , 'l' , 'p' , 'f' , or 's' for block
138 special file, character special file, directory, symbolic link,
139 FIFO, regular file, or socket, respectively.
140 -links n
142 The primary shall evaluate as true if the file has n links.
143 -user uname
145 The primary shall evaluate as true if the file belongs to the
146 user uname. If uname is a decimal integer and the getpwnam() (or
147 equivalent) function does not return a valid user name, uname
148 shall be interpreted as a user ID.
149 -group gname
151 The primary shall evaluate as true if the file belongs to the
153 group gname. If gname is a decimal integer and the getgrnam()
154 (or equivalent) function does not return a valid group name,
155 gname shall be interpreted as a group ID.
156 -size n[c]
158 The primary shall evaluate as true if the file size in bytes,
159 divided by 512 and rounded up to the next integer, is n. If n
160 is followed by the character 'c' , the size shall be in bytes.
161 -atime n
163 The primary shall evaluate as true if the file access time sub‐
164 tracted from the initialization time, divided by 86400 (with any
165 remainder discarded), is n.
166 -ctime n
168 The primary shall evaluate as true if the time of last change of
169 file status information subtracted from the initialization time,
170 divided by 86400 (with any remainder discarded), is n.
171 -mtime n
173 The primary shall evaluate as true if the file modification time
174 subtracted from the initialization time, divided by 86400 (with
175 any remainder discarded), is n.
176 -exec utility_name [argument ...] ;
178 -exec utility_name [argument ...]
180 {} +
181 The end of the primary expression shall be punctuated by a semi‐
183 colon or by a plus sign. Only a plus sign that follows an argu‐
184 ment containing the two characters "{}" shall punctuate the end
185 of the primary expression. Other uses of the plus sign shall not
186 be treated as special.
187 If the primary expression is punctuated by a semicolon, the utility
189 utility_name shall be invoked once for each pathname and the primary
190 shall evaluate as true if the utility returns a zero value as exit sta‐
191 tus. A utility_name or argument containing only the two characters "{}"
192 shall be replaced by the current pathname.
193 If the primary expression is punctuated by a plus sign, the primary
195 shall always evaluate as true, and the pathnames for which the primary
196 is evaluated shall be aggregated into sets. The utility utility_name
197 shall be invoked once for each set of aggregated pathnames. Each invo‐
198 cation shall begin after the last pathname in the set is aggregated,
199 and shall be completed before the find utility exits and before the
200 first pathname in the next set (if any) is aggregated for this primary,
201 but it is otherwise unspecified whether the invocation occurs before,
202 during, or after the evaluations of other primaries. If any invocation
203 returns a non-zero value as exit status, the find utility shall return
204 a non-zero exit status. An argument containing only the two characters
205 "{}" shall be replaced by the set of aggregated pathnames, with each
206 pathname passed as a separate argument to the invoked utility in the
207 same order that it was aggregated. The size of any set of two or more
208 pathnames shall be limited such that execution of the utility does not
209 cause the system's {ARG_MAX} limit to be exceeded. If more than one
210 argument containing only the two characters "{}" is present, the behav‐
211 ior is unspecified.
212 If a utility_name or argument string contains the two characters "{}" ,
214 but not just the two characters "{}" , it is implementation-defined
215 whether find replaces those two characters or uses the string without
216 change. The current directory for the invocation of utility_name shall
217 be the same as the current directory when the find utility was started.
218 If the utility_name names any of the special built-in utilities (see
219 Special Built-In Utilities ), the results are undefined.
220 -ok utility_name [argument ...] ;
222 The -ok primary shall be equivalent to -exec, except that the
224 use of a plus sign to punctuate the end of the primary expres‐
225 sion need not be supported, and find shall request affirmation
226 of the invocation of utility_name using the current file as an
227 argument by writing to standard error as described in the STDERR
228 section. If the response on standard input is affirmative, the
229 utility shall be invoked. Otherwise, the command shall not be
230 invoked and the value of the -ok operand shall be false.
231 -print The primary shall always evaluate as true; it shall cause the
233 current pathname to be written to standard output.
234 -newer file
236 The primary shall evaluate as true if the modification time of
237 the current file is more recent than the modification time of
238 the file named by the pathname file.
239 -depth The primary shall always evaluate as true; it shall cause
241 descent of the directory hierarchy to be done so that all
242 entries in a directory are acted on before the directory itself.
243 If a -depth primary is not specified, all entries in a directory
244 shall be acted on after the directory itself. If any -depth pri‐
245 mary is specified, it shall apply to the entire expression even
246 if the -depth primary would not normally be evaluated.
247 The primaries can be combined using the following operators (in order
250 of decreasing precedence):
251 ( expression )
253 True if expression is true.
254 ! expression
256 Negation of a primary; the unary NOT operator.
257 expression [-a] expression
259 Conjunction of primaries; the AND operator is implied by the
261 juxtaposition of two primaries or made explicit by the optional
262 -a operator. The second expression shall not be evaluated if the
263 first expression is false.
264 expression -o expression
266 Alternation of primaries; the OR operator. The second expression
268 shall not be evaluated if the first expression is true.
269 If no expression is present, -print shall be used as the expression.
272 Otherwise, if the given expression does not contain any of the pri‐
273 maries -exec, -ok, or -print, the given expression shall be effectively
274 replaced by:
275 ( given_expression ) -print
278 The -user, -group, and -newer primaries each shall evaluate their
280 respective arguments only once.
281
283 If the -ok primary is used, the response shall be read from the stan‐
284 dard input. An entire line shall be read as the response. Otherwise,
285 the standard input shall not be used.
286
288 None.
289
291 The following environment variables shall affect the execution of find:
292 LANG Provide a default value for the internationalization variables
294 that are unset or null. (See the Base Definitions volume of
295 IEEE Std 1003.1-2001, Section 8.2, Internationalization Vari‐
296 ables for the precedence of internationalization variables used
297 to determine the values of locale categories.)
298 LC_ALL If set to a non-empty string value, override the values of all
300 the other internationalization variables.
301 LC_COLLATE
303 Determine the locale for the behavior of ranges, equivalence
305 classes, and multi-character collating elements used in the pat‐
306 tern matching notation for the -n option and in the extended
307 regular expression defined for the yesexpr locale keyword in the
308 LC_MESSAGES category.
309 LC_CTYPE
311 This variable determines the locale for the interpretation of
312 sequences of bytes of text data as characters (for example, sin‐
313 gle-byte as opposed to multi-byte characters in arguments), the
314 behavior of character classes within the pattern matching nota‐
315 tion used for the -n option, and the behavior of character
316 classes within regular expressions used in the extended regular
317 expression defined for the yesexpr locale keyword in the LC_MES‐
318 SAGES category.
319 LC_MESSAGES
321 Determine the locale for the processing of affirmative responses
322 that should be used to affect the format and contents of diag‐
323 nostic messages written to standard error.
324 NLSPATH
326 Determine the location of message catalogs for the processing of
327 LC_MESSAGES .
328 PATH Determine the location of the utility_name for the -exec and -ok
330 primaries, as described in the Base Definitions volume of
331 IEEE Std 1003.1-2001, Chapter 8, Environment Variables.
332
335 Default.
336
338 The -print primary shall cause the current pathnames to be written to
339 standard output. The format shall be:
340 "%s\n", <path>
343
345 The -ok primary shall write a prompt to standard error containing at
346 least the utility_name to be invoked and the current pathname. In the
347 POSIX locale, the last non- <blank> in the prompt shall be '?' . The
348 exact format used is unspecified.
349 Otherwise, the standard error shall be used only for diagnostic mes‐
351 sages.
352
354 None.
355
357 None.
358
360 The following exit values shall be returned:
361 0 All path operands were traversed successfully.
363 >0 An error occurred.
365
368 Default.
369 The following sections are informative.
371
373 When used in operands, pattern matching notation, semicolons, opening
374 parentheses, and closing parentheses are special to the shell and must
375 be quoted (see Quoting ).
376 The bit that is traditionally used for sticky (historically 01000) is
378 specified in the -perm primary using the octal number argument form.
379 Since this bit is not defined by this volume of IEEE Std 1003.1-2001,
380 applications must not assume that it actually refers to the traditional
381 sticky bit.
382
384 1. The following commands are equivalent:
385 find .
388 find . -print
389 They both write out the entire directory hierarchy from the current
391 directory.
392 2. The following command:
394 find / \( -name tmp -o -name '*.xx' \) -atime +7 -exec rm {} \;
397 removes all files named tmp or ending in .xx that have not been
399 accessed for seven or more 24-hour periods.
400 3. The following command:
402 find . -perm -o+w,+s
405 prints ( -print is assumed) the names of all files in or below the cur‐
407 rent directory, with all of the file permission bits S_ISUID, S_ISGID,
408 and S_IWOTH set.
409 4. The following command:
411 find . -name SCCS -prune -o -print
414 recursively prints pathnames of all files in the current directory and
416 below, but skips directories named SCCS and files in them.
417 5. The following command:
419 find . -print -name SCCS -prune
422 behaves as in the previous example, but prints the names of the SCCS
424 directories.
425 6. The following command is roughly equivalent to the -nt extension to
427 test:
428 if [ -n "$(find file1 -prune -newer file2)" ]; then
431 printf %s\\n "file1 is newer than file2"
432 fi
433 7. The descriptions of -atime, -ctime, and -mtime use the terminology
435 n "86400 second periods (days)". For example, a file accessed at
436 23:59 is selected by:
437 find . -atime -1 -print
440 at 00:01 the next day (less than 24 hours later, not more than one day
442 ago); the midnight boundary between days has no effect on the 24-hour
443 calculation.
444
446 The -a operator was retained as an optional operator for compatibility
447 with historical shell scripts, even though it is redundant with expres‐
448 sion concatenation.
449 The descriptions of the '-' modifier on the mode and onum arguments to
451 the -perm primary agree with historical practice on BSD and System V
452 implementations. System V and BSD documentation both describe it in
453 terms of checking additional bits; in fact, it uses the same bits, but
454 checks for having at least all of the matching bits set instead of hav‐
455 ing exactly the matching bits set.
456 The exact format of the interactive prompts is unspecified. Only the
458 general nature of the contents of prompts are specified because:
459 * Implementations may desire more descriptive prompts than those used
461 on historical implementations.
462 * Since the historical prompt strings do not terminate with <new‐
464 line>s, there is no portable way for another program to interact
465 with the prompts of this utility via pipes.
466 Therefore, an application using this prompting option relies on the
468 system to provide the most suitable dialog directly with the user,
469 based on the general guidelines specified.
470 The -name file operand was changed to use the shell pattern matching
472 notation so that find is consistent with other utilities using pattern
473 matching.
474 The -size operand refers to the size of a file, rather than the number
476 of blocks it may occupy in the file system. The intent is that the
477 st_size field defined in the System Interfaces volume of
478 IEEE Std 1003.1-2001 should be used, not the st_blocks found in histor‐
479 ical implementations. There are at least two reasons for this:
480 1. In both System V and BSD, find only uses st_size in size calcula‐
482 tions for the operands specified by this volume of
483 IEEE Std 1003.1-2001. (BSD uses st_blocks only when processing the
484 -ls primary.)
485 2. Users usually think of file size in terms of bytes, which is also
487 the unit used by the ls utility for the output from the -l option.
488 (In both System V and BSD, ls uses st_size for the -l option size
489 field and uses st_blocks for the ls -s calculations. This volume of
490 IEEE Std 1003.1-2001 does not specify ls -s.)
491 The descriptions of -atime, -ctime, and -mtime were changed from the
493 SVID description of n "days'' to "24-hour periods". The description is
494 also different in terms of the exact timeframe for the n case (versus
495 the +n or -n), but it matches all known historical implementations. It
496 refers to one 86400 second period in the past, not any time from the
497 beginning of that period to the current time. For example, -atime 3 is
498 true if the file was accessed any time in the period from 72 hours to
499 48 hours ago.
500 Historical implementations do not modify "{}" when it appears as a sub‐
502 string of an -exec or -ok utility_name or argument string. There have
503 been numerous user requests for this extension, so this volume of
504 IEEE Std 1003.1-2001 allows the desired behavior. At least one recent
505 implementation does support this feature, but encountered several prob‐
506 lems in managing memory allocation and dealing with multiple occur‐
507 rences of "{}" in a string while it was being developed, so it is not
508 yet required behavior.
509 Assuming the presence of -print was added to correct a historical pit‐
511 fall that plagues novice users, it is entirely upwards-compatible from
512 the historical System V find utility. In its simplest form ( find
513 directory), it could be confused with the historical BSD fast find. The
514 BSD developers agreed that adding -print as a default expression was
515 the correct decision and have added the fast find functionality within
516 a new utility called locate.
517 Historically, the -L option was implemented using the primary -follow.
519 The -H and -L options were added for two reasons. First, they offer a
520 finer granularity of control and consistency with other programs that
521 walk file hierarchies. Second, the -follow primary always evaluated to
522 true. As they were historically really global variables that took
523 effect before the traversal began, some valid expressions had unex‐
524 pected results. An example is the expression -print -o -follow. Because
525 -print always evaluates to true, the standard order of evaluation
526 implies that -follow would never be evaluated. This was never the case.
527 Historical practice for the -follow primary, however, is not consis‐
528 tent. Some implementations always follow symbolic links on the command
529 line whether -follow is specified or not. Others follow symbolic links
530 on the command line only if -follow is specified. Both behaviors are
531 provided by the -H and -L options, but scripts using the current -fol‐
532 low primary would be broken if the -follow option is specified to work
533 either way.
534 Since the -L option resolves all symbolic links and the -type l primary
536 is true for symbolic links that still exist after symbolic links have
537 been resolved, the command:
538 find -L . -type l
541 prints a list of symbolic links reachable from the current directory
543 that do not resolve to accessible files.
544 A feature of SVR4's find utility was the -exec primary's + terminator.
546 This allowed filenames containing special characters (especially <new‐
547 line>s) to be grouped together without the problems that occur if such
548 filenames are piped to xargs. Other implementations have added other
549 ways to get around this problem, notably a -print0 primary that wrote
550 filenames with a null byte terminator. This was considered here, but
551 not adopted. Using a null terminator meant that any utility that was
552 going to process find's -print0 output had to add a new option to parse
553 the null terminators it would now be reading.
554 The "-exec ... {} +" syntax adopted was a result of IEEE PASC Interpre‐
556 tation 1003.2 #210. It should be noted that this is an incompatible
557 change to the ISO/IEC 9899:1999 standard. For example, the following
558 command prints all files with a '-' after their name if they are regu‐
559 lar files, and a '+' otherwise:
560 find / -type f -exec echo {} - ';' -o -exec echo {} + ';'
563 The change invalidates usage like this. Even though the previous stan‐
565 dard stated that this usage would work, in practice many did not sup‐
566 port it and the standard developers felt it better to now state that
567 this was not allowable.
568
570 None.
571
573 Quoting , Pattern Matching Notation , Special Built-In Utilities ,
574 chmod() , pax , sh , test , the System Interfaces volume of
575 IEEE Std 1003.1-2001, getgrgid(), getpwuid(), stat()
576
578 Portions of this text are reprinted and reproduced in electronic form
579 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
580 -- Portable Operating System Interface (POSIX), The Open Group Base
581 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
582 Electrical and Electronics Engineers, Inc and The Open Group. In the
583 event of any discrepancy between this version and the original IEEE and
584 The Open Group Standard, the original IEEE and The Open Group Standard
585 is the referee document. The original Standard can be obtained online
586 at http://www.opengroup.org/unix/online.html .
587IEEE/The Open Group 2003 FIND(P)