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