1FIND(1) General Commands Manual FIND(1)
2
6 find - search for files in a directory hierarchy
7
9 find [-H] [-L] [-P] [path...] [expression]
10
12 This manual page documents the GNU version of find. GNU find searches
13 the directory tree rooted at each given file name by evaluating the
14 given expression from left to right, according to the rules of prece‐
15 dence (see section OPERATORS), until the outcome is known (the left
16 hand side is false for and operations, true for or), at which point
17 find moves on to the next file name.
18 If you are using find in an environment where security is important
20 (for example if you are using it to seach directories that are writable
21 by other users), you should read the "Security Considerations" chapter
22 of the findutils documentation, which is called Finding Files and comes
23 with findutils. That document also includes a lot more detail and
24 discussion than this manual page, so you may find it a more useful
25 source of information.
26
28 The `-H', `-L' and `-P' options control the treatment of symbolic
29 links. Command-line arguments following these are taken to be names of
30 files or directories to be examined, up to the first argument that
31 begins with `-', `(', `)', `,', or `!'. That argument and any follow‐
32 ing arguments are taken to be the expression describing what is to be
33 searched for. If no paths are given, the current directory is used.
34 If no expression is given, the expression `-print' is used (but you
35 should probably consider using `-print0' instead, anyway).
36 This manual page talks about `options' within the expression list.
38 These options control the behaviour of find but are specified immedi‐
39 ately after the last path name. The three `real' options `-H', `-L'
40 and `-P' must appear before the first path name, if at all.
41 -P Never follow symbolic links. This is the default behaviour.
43 When find examines or prints information a file, and the file is
44 a symbolic link, the information used shall be taken from the
45 properties of the symbolic link itself.
46 -L Follow symbolic links. When find examines or prints information
49 about files, the information used shall be taken from the prop‐
50 erties of the file to which the link points, not from the link
51 itself (unless it is a broken symbolic link or find is unable to
52 examine the file to which the link points). Use of this option
53 implies -noleaf. If you later use the -P option, -noleaf will
54 still be in effect. If -L is in effect and find discovers a
55 symbolic link to a subdirectory during its search, the subdirec‐
56 tory pointed to by the symbolic link will be searched.
57 When the -L option is in effect, the -type predicate will always
59 match against the type of the file that a symbolic link points
60 to rather than the link itself (unless the symbolic link is bro‐
61 ken). Using -L causes the -lname and -ilname predicates always
62 to return false.
63 -H Do not follow symbolic links, except while processing the com‐
66 mand line arguments. When find examines or prints information
67 about files, the information used shall be taken from the prop‐
68 erties of the symbolic link itself. The only exception to this
69 behaviour is when a file specified on the command line is a sym‐
70 bolic link, and the link can be resolved. For that situation,
71 the information used is taken from whatever the link points to
72 (that is, the link is followed). The information about the link
73 itself is used as a fallback if the file pointed to by the sym‐
74 bolic link cannot be examined. If -H is in effect and one of
75 the paths specified on the command line is a symbolic link to a
76 directory, the contents of that directory will be examined
77 (though of course -maxdepth 0 would prevent this).
78 If more than one of -H, -L and -P is specified, each overrides the oth‐
80 ers; the last one appearing on the command line takes effect. Since it
81 is the default, the -P option should be considered to be in effect
82 unless either -H or -L is specified.
83 GNU find frequently stats files during the processing of the command
85 line itself, before any searching has begun. These options also affect
86 how those arguments are processed. Specifically, there are a number of
87 tests that compare files listed on the command line against a file we
88 are currently considering. In each case, the file specified on the
89 command line will have been examined and some of its properties will
90 have been saved. If the named file is in fact a symbolic link, and the
91 -P option is in effect (or if neither -H nor -L were specified), the
92 information used for the comparison will be taken from the properties
93 of the symbolic link. Otherwise, it will be taken from the properties
94 of the file the link points to. If find cannot follow the link (for
95 example because it has insufficient privileges or the link points to a
96 nonexistent file) the properties of the link itself will be used.
97 When the -H or -L options are in effect, any symbolic links listed as
99 the argument of -newer will be dereferenced, and the timestamp will be
100 taken from the file to which the symbolic link points. The same con‐
101 sideration applies to -anewer and -cnewer.
102 The -follow option has a similar effect to -L, though it takes effect
104 at the point where it appears (that is, if -L is not used but -follow
105 is, any symbolic links appearing after -follow on the command line will
106 be dereferenced, and those before it will not).
107
110 The expression is made up of options (which affect overall operation
111 rather than the processing of a specific file, and always return true),
112 tests (which return a true or false value), and actions (which have
113 side effects and return a true or false value), all separated by opera‐
114 tors. -and is assumed where the operator is omitted.
115 If the expression contains no actions other than -prune, -print is per‐
117 formed on all files for which the expression is true.
118 OPTIONS
121 All options always return true. Except for -follow and -daystart, the
122 options affect all tests, including tests specified before the option.
123 This is because the options are processed when the command line is
124 parsed, while the tests don't do anything until files are examined.
125 The -follow and -daystart options are different in this respect, and
126 have an effect only on tests which appear later in the command line.
127 Therefore, for clarity, it is best to place them at the beginning of
128 the expression. A warning is issued if you don't do this.
129 -daystart
131 Measure times (for -amin, -atime, -cmin, -ctime, -mmin, and
132 -mtime) from the beginning of today rather than from 24 hours
133 ago. This option only affects tests which appear later on the
134 command line.
135 -depth Process each directory's contents before the directory itself.
137 -d A synonym for -depth, for compatibility with FreeBSD, NetBSD,
139 MacOS X and OpenBSD.
140 -follow
142 Deprecated; use the -L option instead. Dereference symbolic
143 links. Implies -noleaf. The -follow option affects only those
144 tests which appear after it on the command line. Unless the -H
145 or -L option has been specified, the position of the -follow
146 option changes the behaviour of the -newer predicate; any files
147 listed as the argument of -newer will be dereferenced if they
148 are symbolic links. The same consideration applies to -anewer
149 and -cnewer. Similarly, the -type predicate will always match
150 against the type of the file that a symbolic link points to
151 rather than the link itself. Using -follow causes the -lname
152 and -ilname predicates always to return false.
153 -help, --help
155 Print a summary of the command-line usage of find and exit.
156 -ignore_readdir_race
158 Normally, find will emit an error message when it fails to stat
159 a file. If you give this option and a file is deleted between
160 the time find reads the name of the file from the directory and
161 the time it tries to stat the file, no error message will be
162 issued. This also applies to files or directories whose names
163 are given on the command line. This option takes effect at the
164 time the command line is read, which means that you cannot
165 search one part of the filesystem with this option on and part
166 of it with this option off (if you need to do that, you will
167 need to issue two find commands instead, one with the option and
168 one without it).
169 -maxdepth levels
171 Descend at most levels (a non-negative integer) levels of direc‐
172 tories below the command line arguments. `-maxdepth 0' means
173 only apply the tests and actions to the command line arguments.
174 -mindepth levels
176 Do not apply any tests or actions at levels less than levels (a
177 non-negative integer). `-mindepth 1' means process all files
178 except the command line arguments.
179 -mount Don't descend directories on other filesystems. An alternate
181 name for -xdev, for compatibility with some other versions of
182 find.
183 -noignore_readdir_race
185 Turns off the effect of -ignore_readdir_race.
186 -noleaf
188 Do not optimize by assuming that directories contain 2 fewer
189 subdirectories than their hard link count. This option is
190 needed when searching filesystems that do not follow the Unix
191 directory-link convention, such as CD-ROM or MS-DOS filesystems
192 or AFS volume mount points. Each directory on a normal Unix
193 filesystem has at least 2 hard links: its name and its `.'
194 entry. Additionally, its subdirectories (if any) each have a
195 `..' entry linked to that directory. When find is examining a
196 directory, after it has statted 2 fewer subdirectories than the
197 directory's link count, it knows that the rest of the entries in
198 the directory are non-directories (`leaf' files in the directory
199 tree). If only the files' names need to be examined, there is
200 no need to stat them; this gives a significant increase in
201 search speed.
202 -regextype type
204 Changes the regular expression syntax understood by -regex and
205 -iregex tests which occur later on the command line. Currently-
206 implemented types are emacs (this is the default), posix-awk,
207 posix-basic, posix-egrep and posix-extended.
208 -version, --version
211 Print the find version number and exit.
212 -warn, -nowarn
214 Turn warning messages on or off. These warnings apply only to
215 the command line usage, not to any conditions that find might
216 encounter when it searches directories. The default behaviour
217 corresponds to -warn if standard input is a tty, and to -nowarn
218 otherwise.
219 -xdev Don't descend directories on other filesystems.
221 TESTS
224 Numeric arguments can be specified as
225 +n for greater than n,
227 -n for less than n,
229 n for exactly n.
231 -amin n
233 File was last accessed n minutes ago.
234 -anewer file
236 File was last accessed more recently than file was modified. If
237 file is a symbolic link and the -H option or the -L option is in
238 effect, the access time of the file it points to is always used.
239 -atime n
241 File was last accessed n*24 hours ago. When find figures out
242 how many 24-hour periods ago the file was last accessed, any
243 fractional part is ignored, so to match -atime +1, a file has to
244 have been accessed at least two days ago.
245 -cmin n
247 File's status was last changed n minutes ago.
248 -cnewer file
250 File's status was last changed more recently than file was modi‐
251 fied. If file is a symbolic link and the -H option or the -L
252 option is in effect, the status-change time of the file it
253 points to is always used.
254 -ctime n
257 File's status was last changed n*24 hours ago. See the comments
258 for -atime to understand how rounding affects the interpretation
259 of file status change times.
260 -empty File is empty and is either a regular file or a directory.
262 -false Always false.
264 -fstype type
266 File is on a filesystem of type type. The valid filesystem
267 types vary among different versions of Unix; an incomplete list
268 of filesystem types that are accepted on some version of Unix or
269 another is: ufs, 4.2, 4.3, nfs, tmp, mfs, S51K, S52K. You can
270 use -printf with the %F directive to see the types of your
271 filesystems.
272 -gid n File's numeric group ID is n.
274 -group gname
276 File belongs to group gname (numeric group ID allowed).
277 -ilname pattern
279 Like -lname, but the match is case insensitive. If the -L
280 option or the -follow option is in effect, this test returns
281 false unless the symbolic link is broken.
282 -iname pattern
284 Like -name, but the match is case insensitive. For example, the
285 patterns `fo*' and `F??' match the file names `Foo', `FOO',
286 `foo', `fOo', etc. In these patterns, unlike filename expan‐
287 sion by the shell, an initial '.' can be matched by '*'. That
288 is, find -name *bar will match the file `.foobar'. Please note
289 that you should quote patterns as a matter of course, otherwise
290 the shell will expand any wildcard characters in them.
291 -inum n
294 File has inode number n. It is normally easier to use the
295 -samefile test instead.
296 -ipath pattern
298 Behaves in the same way as -iwholename. This option is depre‐
299 cated, so please do not use it.
300 -iregex pattern
302 Like -regex, but the match is case insensitive.
303 -iwholename pattern
305 Like -wholename, but the match is case insensitive.
306 -links n
308 File has n links.
309 -lname pattern
311 File is a symbolic link whose contents match shell pattern pat‐
312 tern. The metacharacters do not treat `/' or `.' specially. If
313 the -L option or the -follow option is in effect, this test
314 returns false unless the symbolic link is broken.
315 -mmin n
317 File's data was last modified n minutes ago.
318 -mtime n
320 File's data was last modified n*24 hours ago. See the comments
321 for -atime to understand how rounding affects the interpretation
322 of file modification times.
323 -name pattern
325 Base of file name (the path with the leading directories
326 removed) matches shell pattern pattern. The metacharacters
327 (`*', `?', and `[]') match a `.' at the start of the base name
328 (this is a change in findutils-4.2.2; see section STANDARDS CON‐
329 FORMANCE below). To ignore a directory and the files under it,
330 use -prune; see an example in the description of -wholename.
331 Braces are not recognised as being special, despite the fact
332 that some shells including Bash imbue braces with a special
333 meaning in shell patterns. The filename matching is performed
334 with the use of the fnmatch(3) library function. Don't forget
335 to enclose the pattern in quotes in order to protect it from
336 expansion by the shell.
337 -newer file
340 File was modified more recently than file. If file is a sym‐
341 bolic link and the -H option or the -L option is in effect, the
342 modification time of the file it points to is always used.
343 -nouser
345 No user corresponds to file's numeric user ID.
346 -nogroup
348 No group corresponds to file's numeric group ID.
349 -path pattern
351 See -wholename. The predicate -path is also supported by HP-UX
352 find.
353 -perm mode
355 File's permission bits are exactly mode (octal or symbolic).
356 Since an exact match is required, if you want to use this form
357 for symbolic modes, you may have to specify a rather complex
358 mode string. For example '-perm g=w' will only match files
359 which have mode 0020 (that is, ones for which group write per‐
360 mission is the only permission set). It is more likely that you
361 will want to use the '/' or '-' forms, for example '-perm -g=w',
362 which matches any file with group write permission. See the
363 EXAMPLES section for some illustrative examples.
364 -perm -mode
366 All of the permission bits mode are set for the file. Symbolic
367 modes are accepted in this form, and this is usually the way in
368 which would want to use them. You must specify 'u', 'g' or 'o'
369 if you use a symbolic mode. See the EXAMPLES section for some
370 illustrative examples.
371 -perm /mode
373 Any of the permission bits mode are set for the file. Symbolic
374 modes are accepted in this form. You must specify 'u', 'g' or
375 'o' if you use a symbolic mode. See the EXAMPLES section for
376 some illustrative examples. If no permission bits in mode are
377 set, this test currently matches no files. However, it will
378 soon be changed to match any file (the idea is to be more con‐
379 sistent with the behaviour of perm -000).
380 -perm +mode
382 Deprecated, old way of searching for files with any of the per‐
383 mission bits in mode set. You should use -perm /mode instead.
384 Trying to use the '+' syntax with symbolic modes will yield sur‐
385 prising results. For example, '+u+x' is a valid symbolic mode
386 (equivalent to +u,+x, i.e. 0111) and will therefore not be eval‐
387 uated as -perm +mode but instead as the exact mode specifier
388 -perm mode and so it matches files with exact permissions 0111
389 instead of files with any execute bit set. If you found this
390 paragraph confusing, you're not alone - just use -perm /mode.
391 This form of the -perm test is deprecated because the POSIX
392 specification requires the interpretation of a leading '+' as
393 being part of a symbolic mode, and so we switched to using '/'
394 instead.
395 -regex pattern
398 File name matches regular expression pattern. This is a match
399 on the whole path, not a search. For example, to match a file
400 named `./fubar3', you can use the regular expression `.*bar.' or
401 `.*b.*3', but not `f.*r3'. The regular expressions understood
402 by find are by default Emacs Regular Expressions, but this can
403 be changed with the -regextype option.
404 -samefile name
406 File refers to the same inode as name. When -L is in effect,
407 this can include symbolic links.
408 -size n[cwbkMG]
410 File uses n units of space. The following suffixes can be used:
411 `b' for 512-byte blocks (this is the default if no suffix is
413 used)
414 `c' for bytes
416 `w' for two-byte words
418 `k' for Kilobytes (units of 1024 bytes)
420 `M' for Megabytes (units of 1048576 bytes)
422 `G' for Gigabytes (units of 1073741824 bytes)
424 The size does not count indirect blocks, but it does count
426 blocks in sparse files that are not actually allocated. Bear in
427 mind that the `%k' and `%b' format specifiers of -printf handle
428 sparse files differently. The `b' suffix always denotes
429 512-byte blocks and never 1 Kilobyte blocks, which is different
430 to the behaviour of -ls.
431 -true Always true.
434 -type c
436 File is of type c:
437 b block (buffered) special
439 c character (unbuffered) special
441 d directory
443 p named pipe (FIFO)
445 f regular file
447 l symbolic link; this is never true if the -L option or the
449 -follow option is in effect, unless the symbolic link is
450 broken. If you want to search for symbolic links when -L
451 is in effect, use -xtype.
452 s socket
454 D door (Solaris)
456 -uid n File's numeric user ID is n.
458 -used n
460 File was last accessed n days after its status was last changed.
461 -user uname
463 File is owned by user uname (numeric user ID allowed).
464 -wholename pattern
466 File name matches shell pattern pattern. The metacharacters do
467 not treat `/' or `.' specially; so, for example,
468 find . -wholename './sr*sc'
469 will print an entry for a directory called './src/misc' (if one
470 exists). To ignore a whole directory tree, use -prune rather
471 than checking every file in the tree. For example, to skip the
472 directory `src/emacs' and all files and directories under it,
473 and print the names of the other files found, do something like
474 this:
475 find . -wholename './src/emacs' -prune -o -print
476 -xtype c
478 The same as -type unless the file is a symbolic link. For sym‐
479 bolic links: if the -H or -P option was specified, true if the
480 file is a link to a file of type c; if the -L option has been
481 given, true if c is `l'. In other words, for symbolic links,
482 -xtype checks the type of the file that -type does not check.
483 -context pattern
485 (SELinux only) Security context of the file matches glob pat‐
486 tern.
487 ACTIONS
490 -delete
491 Delete files; true if removal succeeded. If the removal failed,
492 an error message is issued. Use of this action automatically
493 turns on the '-depth' option.
494 -exec command ;
497 Execute command; true if 0 status is returned. All following
498 arguments to find are taken to be arguments to the command until
499 an argument consisting of `;' is encountered. The string `{}'
500 is replaced by the current file name being processed everywhere
501 it occurs in the arguments to the command, not just in arguments
502 where it is alone, as in some versions of find. Both of these
503 constructions might need to be escaped (with a `\') or quoted to
504 protect them from expansion by the shell. See the EXAMPLES sec‐
505 tion for examples of the use of the `-exec' option. The speci‐
506 fied command is run once for each matched file. The command is
507 executed in the starting directory. There are unavoidable
508 security problems surrounding use of the -exec option; you
509 should use the -execdir option instead.
510 -exec command {} +
513 This variant of the -exec option runs the specified command on
514 the selected files, but the command line is built by appending
515 each selected file name at the end; the total number of invoca‐
516 tions of the command will be much less than the number of
517 matched files. The command line is built in much the same way
518 that xargs builds its command lines. Only one instance of '{}'
519 is allowed within the command. The command is executed in the
520 starting directory.
521 -execdir command ;
524 -execdir command {} +
526 Like -exec, but the specified command is run from the subdirec‐
527 tory containing the matched file, which is not normally the
528 directory in which you started find. This a much more secure
529 method for invoking commands, as it avoids race conditions dur‐
530 ing resolution of the paths to the matched files. As with the
531 -exec option, the '+' form of -execdir will build a command line
532 to process more than one matched file, but any given invocation
533 of command will only list files that exist in the same subdirec‐
534 tory. If you use this option, you must ensure that your $PATH
535 environment variable does not reference the current directory;
536 otherwise, an attacker can run any commands they like by leaving
537 an appropriately-named file in a directory in which you will run
538 -execdir.
539 -fls file
542 True; like -ls but write to file like -fprint. The output file
543 is always created, even if the predicate is never matched. See
544 the UNUSUAL FILENAMES section for information about how unusual
545 characters in filenames are handled.
546 -fprint file
549 True; print the full file name into file file. If file does not
550 exist when find is run, it is created; if it does exist, it is
551 truncated. The file names ``/dev/stdout'' and ``/dev/stderr''
552 are handled specially; they refer to the standard output and
553 standard error output, respectively. The output file is always
554 created, even if the predicate is never matched. See the
555 UNUSUAL FILENAMES section for information about how unusual
556 characters in filenames are handled.
557 -fprint0 file
559 True; like -print0 but write to file like -fprint. The output
560 file is always created, even if the predicate is never matched.
561 See the UNUSUAL FILENAMES section for information about how
562 unusual characters in filenames are handled.
563 -fprintf file format
565 True; like -printf but write to file like -fprint. The output
566 file is always created, even if the predicate is never matched.
567 See the UNUSUAL FILENAMES section for information about how
568 unusual characters in filenames are handled.
569 -ok command ;
571 Like -exec but ask the user first (on the standard input); if
572 the response does not start with `y' or `Y', do not run the com‐
573 mand, and return false. If the command is run, its standard
574 input is redirected from /dev/null.
575 -print True; print the full file name on the standard output, followed
578 by a newline. If you are piping the output of find into
579 another program and there is the faintest possibility that the
580 files which you are searching for might contain a newline, then
581 you should seriously consider using the `-print0' option instead
582 of `-print'. See the UNUSUAL FILENAMES section for information
583 about how unusual characters in filenames are handled.
584 -okdir command ;
586 Like -execdir but ask the user first (on the standard input); if
587 the response does not start with `y' or `Y', do not run the com‐
588 mand, and return false. If the command is run, its standard
589 input is redirected from /dev/null.
590 -print0
592 True; print the full file name on the standard output, followed
593 by a null character (instead of the newline character that
594 `-print' uses). This allows file names that contain newlines or
595 other types of white space to be correctly interpreted by pro‐
596 grams that process the find output. This option corresponds to
597 the `-0' option of xargs.
598 -printf format
600 True; print format on the standard output, interpreting `\'
601 escapes and `%' directives. Field widths and precisions can be
602 specified as with the `printf' C function. Please note that
603 many of the fields are printed as %s rather than %d, and this
604 may mean that flags don't work as you might expect. This also
605 means that the `-' flag does work (it forces fields to be left-
606 aligned). Unlike -print, -printf does not add a newline at the
607 end of the string. The escapes and directives are:
608 \a Alarm bell.
610 \b Backspace.
612 \c Stop printing from this format immediately and flush the
614 output.
615 \f Form feed.
617 \n Newline.
619 \r Carriage return.
621 \t Horizontal tab.
623 \v Vertical tab.
625 \ ASCII NUL.
627 \\ A literal backslash (`\').
629 \NNN The character whose ASCII code is NNN (octal).
631 A `\' character followed by any other character is treated as an
633 ordinary character, so they both are printed.
634 %% A literal percent sign.
636 %a File's last access time in the format returned by the C
638 `ctime' function.
639 %Ak File's last access time in the format specified by k,
641 which is either `@' or a directive for the C `strftime'
642 function. The possible values for k are listed below;
643 some of them might not be available on all systems, due
644 to differences in `strftime' between systems.
645 @ seconds since Jan. 1, 1970, 00:00 GMT.
647 Time fields:
649 H hour (00..23)
651 I hour (01..12)
653 k hour ( 0..23)
655 l hour ( 1..12)
657 M minute (00..59)
659 p locale's AM or PM
661 r time, 12-hour (hh:mm:ss [AP]M)
663 S second (00..61)
665 T time, 24-hour (hh:mm:ss)
667 + Date and time, separated by '+', for example
669 `2004-04-28+22:22:05'. The time is given in the
670 current timezone (which may be affected by setting
671 the TZ environment variable). This is a GNU
672 extension.
673 X locale's time representation (H:M:S)
675 Z time zone (e.g., EDT), or nothing if no time zone
677 is determinable
678 Date fields:
680 a locale's abbreviated weekday name (Sun..Sat)
682 A locale's full weekday name, variable length (Sun‐
684 day..Saturday)
685 b locale's abbreviated month name (Jan..Dec)
687 B locale's full month name, variable length (Janu‐
689 ary..December)
690 c locale's date and time (Sat Nov 04 12:02:33 EST
692 1989)
693 d day of month (01..31)
695 D date (mm/dd/yy)
697 h same as b
699 j day of year (001..366)
701 m month (01..12)
703 U week number of year with Sunday as first day of
705 week (00..53)
706 w day of week (0..6)
708 W week number of year with Monday as first day of
710 week (00..53)
711 x locale's date representation (mm/dd/yy)
713 y last two digits of year (00..99)
715 Y year (1970...)
717 %b The amount of disk space used for this file in 512-byte
719 blocks. Since disk space is allocated in multiples of the
720 filesystem block size this is usually greater than
721 %s/1024, but it can also be smaller if the file is a
722 sparse file.
723 %c File's last status change time in the format returned by
725 the C `ctime' function.
726 %Ck File's last status change time in the format specified by
728 k, which is the same as for %A.
729 %d File's depth in the directory tree; 0 means the file is a
731 command line argument.
732 %D The device number on which the file exists (the st_dev
734 field of struct stat), in decimal.
735 %f File's name with any leading directories removed (only
737 the last element).
738 %F Type of the filesystem the file is on; this value can be
740 used for -fstype.
741 %g File's group name, or numeric group ID if the group has
743 no name.
744 %G File's numeric group ID.
746 %h Leading directories of file's name (all but the last ele‐
748 ment). If the file name contains no slashes (since it is
749 in the current directory) the %h specifier expands to
750 ".".
751 %H Command line argument under which file was found.
753 %i File's inode number (in decimal).
755 %k The amount of disk space used for this file in 1K blocks.
757 Since disk space is allocated in multiples of the
758 filesystem block size this is usually greater than
759 %s/1024, but it can also be smaller if the file is a
760 sparse file.
761 %l Object of symbolic link (empty string if file is not a
763 symbolic link).
764 %m File's permission bits (in octal). This option uses the
766 'traditional' numbers which most Unix implementations
767 use, but if your particular implementation uses an
768 unusual ordering of octal permissions bits, you will see
769 a difference between the actual value of the file's mode
770 and the output of %m. Normally you will want to have a
771 leading zero on this number, and to do this, you should
772 use the # flag (as in, for example, '%#m').
773 %M File's permissions (in symbolic form, as for ls). This
775 directive is supported in findutils 4.2.5 and later.
776 %n Number of hard links to file.
778 %p File's name.
780 %P File's name with the name of the command line argument
782 under which it was found removed.
783 %s File's size in bytes.
785 %t File's last modification time in the format returned by
787 the C `ctime' function.
788 %Tk File's last modification time in the format specified by
790 k, which is the same as for %A.
791 %u File's user name, or numeric user ID if the user has no
793 name.
794 %U File's numeric user ID.
796 %y File's type (like in ls -l), U=unknown type (shouldn't
798 happen)
799 %Y File's type (like %y), plus follow symlinks: L=loop,
801 N=nonexistent
802 %Z (SELinux only) file's security context.
804 A `%' character followed by any other character is discarded,
806 but the other character is printed (don't rely on this, as fur‐
807 ther format characters may be introduced). A `%' at the end of
808 the format argument causes undefined behaviour since there is no
809 following character. In some locales, it may hide your door
810 keys, while in others it may remove the final page from the
811 novel you are reading.
812 The %m and %d directives support the # , 0 and + flags, but the
814 other directives do not, even if they print numbers. Numeric
815 directives that do not support these flags include G, U, b, D, k
816 and n. The `-' format flag is supported and changes the align‐
817 ment of a field from right-justified (which is the default) to
818 left-justified.
819 See the UNUSUAL FILENAMES section for information about how
821 unusual characters in filenames are handled.
822 -prune If -depth is not given, true; if the file is a directory, do not
826 descend into it.
827 If -depth is given, false; no effect.
828 -quit Exit immediately. No child processes will be left running, but
831 no more paths specified on the command line will be processed.
832 For example, find /tmp/foo /tmp/bar -print -quit will print only
833 /tmp/foo. Any command lines which have been built up with
834 -execdir ... {} + will be invoked before find exits. The exit
835 status may or may not be zero, depending on whether an error has
836 already occurred.
837 -ls True; list current file in `ls -dils' format on standard output.
840 The block counts are of 1K blocks, unless the environment vari‐
841 able POSIXLY_CORRECT is set, in which case 512-byte blocks are
842 used. See the UNUSUAL FILENAMES section for information about
843 how unusual characters in filenames are handled.
844 UNUSUAL FILENAMES
848 Many of the actions of find result in the printing of data which is
849 under the control of other users. This includes file names, sizes,
850 modification times and so forth. File names are a potential problem
851 since they can contain any character except '\0' and '/'. Unusual
852 characters in file names can do unexpected and often undesirable things
853 to your terminal (for example, changing the settings of your function
854 keys on some terminals). Unusual characters are handled differently by
855 various actions, as described below.
856 -print0, -fprint0
858 Always print the exact filename, unchanged, even if the output
859 is going to a terminal.
860 -ls, -fls
862 Unusual characters are always escaped. White space, backslash,
863 and double quote characters are printed using C-style escaping
864 (for example '\f', '\"'). Other unusual characters are printed
865 using an octal escape. Other printable characters (for -ls and
866 -fls these are the characters between octal 041 and 0176) are
867 printed as-is.
868 -printf, -fprintf
870 If the output is not going to a terminal, it is printed as-is.
871 Otherwise, the result depends on which directive is in use. The
872 directives %D, %F, %g, %G, %H, %Y, and %y expand to values which
873 are not under control of files' owners, and so are printed as-
874 is. The directives %a, %b, %c, %d, %i, %k, %m, %M, %n, %s, %t,
875 %u and %U have values which are under the control of files' own‐
876 ers but which cannot be used to send arbitrary data to the ter‐
877 minal, and so these are printed as-is. The directives %f, %h,
878 %l, %p and %P are quoted. This quoting is performed in the same
879 way as for GNU ls. This is not the same quoting mechanism as
880 the one used for -ls and -fls. If you are able to decide what
881 format to use for the output of find then it is normally better
882 to use '\0' as a terminator than to use newline, as file names
883 can contain white space and newline characters.
884 -print, -fprint
886 Quoting is handled in the same way as for -printf and -fprintf.
887 If you are using find in a script or in a situation where the
888 matched files might have arbitrary names, you should consider
889 using -print0 instead of -print.
890 The -ok and -okdir actions print the current filename as-is. This may
892 change in a future release.
893 OPERATORS
895 Listed in order of decreasing precedence:
896 ( expr )
898 Force precedence.
899 ! expr True if expr is false.
901 -not expr
903 Same as ! expr, but not POSIX compliant.
904 expr1 expr2
906 Two expressions in a row are taken to be joined with an implied
907 "and"; expr2 is not evaluated if expr1 is false.
908 expr1 -a expr2
910 Same as expr1 expr2.
911 expr1 -and expr2
913 Same as expr1 expr2, but not POSIX compliant.
914 expr1 -o expr2
916 Or; expr2 is not evaluated if expr1 is true.
917 expr1 -or expr2
919 Same as expr1 -o expr2, but not POSIX compliant.
920 expr1 , expr2
922 List; both expr1 and expr2 are always evaluated. The value of
923 expr1 is discarded; the value of the list is the value of
924 expr2. The comma operator can be useful for searching for
925 several different types of thing, but traversing the filesystem
926 hierarchy only once. The -fprintf action can be used to list
927 the various matched items into several different output files.
928
932 The following options are specified in the POSIX standard (IEEE Std
933 1003.1, 2003 Edition):
934 -H This option is supported.
936 -L This option is supported.
938 -name This option is supported, but POSIX conformance depends on the
940 POSIX conformance of the system's fnmatch(3) library function.
941 As of findutils-4.2.2, shell metacharacters ('*'. '?' or '[]'
942 for example) will match a leading '.', because IEEE PASC inter‐
943 pretation 126 requires this. This is a change from previous
944 versions of findutils.
945 -type Supported. POSIX specifies `b', `c', `d', `l', `p', `f' and
947 `s'. GNU find also supports `D', representing a Door, where the
948 OS provides these.
949 -ok Supported. Interpretation of the response is not locale-depen‐
952 dent (see ENVIRONMENT VARIABLES).
953 -newer Supported. If the file specified is a symbolic link, it is
956 always dereferenced. This is a change from previous behaviour,
957 which used to take the relevant time from the symbolic link; see
958 the HISTORY section below.
959 Other predicates
962 The predicates `-atime', `-ctime', `-depth', `-group', `-links',
963 `-mtime', `-nogroup', `-nouser', `-perm', `-print', `-prune',
964 `-size', `-user' and `-xdev', are all supported.
965 The POSIX standard specifies parentheses `(', `)', negation `!' and the
968 `and' and `or' operators (`-a', `-o').
969 All other options, predicates, expressions and so forth are extensions
971 beyond the POSIX standard. Many of these extensions are not unique to
972 GNU find, however.
973 The POSIX standard requires that
975 The find utility shall detect infinite loops; that is, entering
977 a previously visited directory that is an ancestor of the last
978 file encountered. When it detects an infinite loop, find shall
979 write a diagnostic message to standard error and shall either
980 recover its position in the hierarchy or terminate.
981 The link count of directories which contain entries which are hard
983 links to an ancestor will often be lower than they otherwise should be.
984 This can mean that GNU find will sometimes optimise away the visiting
985 of a subdirectory which is actually a link to an ancestor. Since find
986 does not actually enter such a subdirectory, it is allowed to avoid
987 emitting a diagnostic message. Although this behaviour may be somewhat
988 confusing, it is unlikely that anybody actually depends on this behav‐
989 iour. If the leaf optimisation has been turned off with -noleaf, the
990 directory entry will always be examined and the diagnostic message will
991 be issued where it is appropriate. Symbolic links cannot be used to
992 create filesystem cycles as such, but if the -L option or the -follow
993 option is in use, a diagnostic message is issued when find encounters a
994 loop of symbolic links. As with loops containing hard links, the leaf
995 optimisation will often mean that find knows that it doesn't need to
996 call stat() or chdir() on the symbolic link, so this diagnostic is fre‐
997 quently not necessary.
998 The -d option is supported for compatibility with various BSD systems,
1000 but you should use the POSIX-compliant option -depth instead.
1001 The POSIXLY_CORRECT environment variable does not affect the behaviour
1003 of the -regex or -iregex tests because those tests aren't specified in
1004 the POSIX standard.
1005
1007 LANG Provides a default value for the internationalization variables
1008 that are unset or null.
1009 LC_ALL If set to a non-empty string value, override the values of all
1011 the other internationalization variables.
1012 LC_COLLATE
1014 The POSIX standard specifies that this variable affects the pat‐
1015 tern matching to be used for the `-name' option. GNU find uses
1016 the fnmatch(3) library function, and so support for `LC_COLLATE'
1017 depends on the system library.
1018 POSIX also specifies that the `LC_COLLATE' environment variable
1020 affects the interpretation of the user's response to the query
1021 issued by `-ok', but this is not the case for GNU find.
1022 LC_CTYPE
1024 This variable affects the treatment of character classes used
1025 with the `-name' test, if the system's fnmatch(3) library func‐
1026 tion supports this. It has no effect on the behaviour of the
1027 `-ok' expression.
1028 LC_MESSAGES
1030 Determines the locale to be used for internationalised messages.
1031 NLSPATH
1033 Determines the location of the internationalisation message cat‐
1034 alogues.
1035 PATH Affects the directories which are searched to find the executa‐
1037 bles invoked by `-exec', `-execdir', `-ok' and `-okdir'.
1038 POSIXLY_CORRECT
1040 Determines the block size used by `-ls' and `-fls'. If
1041 `POSIXLY_CORRECT' is set, blocks are units of 512 bytes. Other‐
1042 wise they are units of 1024 bytes.
1043 TZ Affects the time zone used for some of the time-related format
1045 directives of -printf and -fprintf.
1046
1048 find /tmp -name core -type f -print | xargs /bin/rm -f
1049 Find files named core in or below the directory /tmp and delete them.
1051 Note that this will work incorrectly if there are any filenames con‐
1052 taining newlines, single or double quotes, or spaces.
1053 find /tmp -name core -type f -print0 | xargs -0 /bin/rm -f
1055 Find files named core in or below the directory /tmp and delete them,
1057 processing filenames in such a way that file or directory names con‐
1058 taining single or double quotes, spaces or newlines are correctly han‐
1059 dled. The -name test comes before the -type test in order to avoid
1060 having to call stat(2) on every file.
1061 find . -type f -exec file '{}' \;
1064 Runs `file' on every file in or below the current directory. Notice
1066 that the braces are enclosed in single quote marks to protect them from
1067 interpretation as shell script punctuation. The semicolon is simi‐
1068 larly protected by the use of a backslash, though ';' could have been
1069 used in that case also.
1070 find / \( -perm -4000 -fprintf /root/suid.txt '%#m %u %p\n' \) , \
1073 \( -size +100M -fprintf /root/big.txt '%-10s %p\n' \)
1074 Traverse the filesystem just once, listing setuid files and directories
1076 into /root/suid.txt and large files into /root/big.txt.
1077 find $HOME -mtime 0
1080 Search for files in your home directory which have been modified in the
1082 last twenty-four hours. This command works this way because the time
1083 since each file was last modified is divided by 24 hours and any
1084 remainder is discarded. That means that to match -mtime 0, a file will
1085 have to have a modification in the past which is less than 24 hours
1086 ago.
1087 find . -perm 664
1091 Search for files which have read and write permission for their owner,
1093 and group, but which other users can read but not write to. Files
1094 which meet these criteria but have other permissions bits set (for
1095 example if someone can execute the file) will not be matched.
1096 find . -perm -664
1099 Search for files which have read and write permission for their owner
1101 and group, and which other users can read, without regard to the pres‐
1102 ence of any extra permission bits (for example the executable bit).
1103 This will match a file which has mode 0777, for example.
1104 find . -perm /222
1107 Search for files which are writable by somebody (their owner, or their
1109 group, or anybody else).
1110 find . -perm /220
1113 find . -perm /u+w,g+w
1114 find . -perm /u=w,g=w
1115 All three of these commands do the same thing, but the first one uses
1117 the octal representation of the file mode, and the other two use the
1118 symbolic form. These commands all search for files which are writable
1119 by either their owner or their group. The files don't have to be
1120 writable by both the owner and group to be matched; either will do.
1121 find . -perm -220
1124 find . -perm -g+w,u+w
1125 Both these commands do the same thing; search for files which are
1127 writable by both their owner and their group.
1128 find . -perm -444 -perm /222 ! -perm /111
1131 find . -perm -a+r -perm /a+w ! -perm /a+x
1132 These two commands both search for files that are readable for every‐
1134 body (-perm -444 or -perm -a+r), have at least on write bit set (-perm
1135 /222 or -perm /a+w) but are not executable for anybody (! -perm /111
1136 and ! -perm /a+x respectively)
1137
1140 find exits with status 0 if all files are processed successfully,
1141 greater than 0 if errors occur. This is deliberately a very broad
1142 description, but if the return value is non-zero, you should not rely
1143 on the correctness of the results of find.
1144
1147 locate(1), locatedb(5), updatedb(1), xargs(1), chmod(1), fnmatch(3),
1148 regex(7), stat(2), lstat(2), ls(1), printf(3), strftime(3), ctime(3),
1149 Finding Files (on-line in Info, or printed).
1150
1152 As of findutils-4.2.2, shell metacharacters ('*'. '?' or '[]' for exam‐
1153 ple) used in filename patterns will match a leading '.', because IEEE
1154 POSIX interpretation 126 requires this.
1155
1157 $ find . -name *.c -print
1158 find: paths must precede expression
1159 Usage: find [-H] [-L] [-P] [path...] [expression]
1160 This happens because *.c has been expanded by the shell resulting in
1162 find actually receiving a command line like this:
1163 find . -name bigram.c code.c frcode.c locate.c -print
1165 That command is of course not going to work. Instead of doing things
1167 this way, you should enclose the pattern in quotes:
1168 $ find . -name ´*.c´ -print
1169
1172 The test -perm /000 currently matches no files, but for greater consis‐
1173 tency with -perm -000, this will be changed to match all files; this
1174 change will probably be made in early 2006. Meanwhile, a warning mes‐
1175 sage is given if you do this.
1176 There are security problems inherent in the behaviour that the POSIX
1178 standard specifies for find, which therefore cannot be fixed. For
1179 example, the -exec action is inherently insecure, and -execdir should
1180 be used instead. Please see Finding Files for more information.
1181 The best way to report a bug is to use the form at http://savan‐
1183 nah.gnu.org/bugs/?group=findutils. The reason for this is that you
1184 will then be able to track progress in fixing the problem. Other com‐
1185 ments about find(1) and about the findutils package in general can be
1186 sent to the bug-findutils mailing list. To join the list, send email
1187 to bug-findutils-request@gnu.org.
1188 FIND(1)