1FIND(1)                     General Commands Manual                    FIND(1)
2
3
4

NAME

6       find - search for files in a directory hierarchy
7

SYNOPSIS

9       find  [-H]  [-L] [-P] [-D debugopts] [-Olevel] [starting-point...] [ex‐
10       pression]
11

DESCRIPTION

13       This manual page documents the GNU version of find.  GNU find  searches
14       the  directory  tree  rooted at each given starting-point by evaluating
15       the given expression from left to right,  according  to  the  rules  of
16       precedence  (see  section  OPERATORS),  until the outcome is known (the
17       left hand side is false for and operations,  true  for  or),  at  which
18       point  find  moves  on  to the next file name.  If no starting-point is
19       specified, `.' is assumed.
20
21       If you are using find in an environment  where  security  is  important
22       (for  example  if  you  are  using  it  to  search directories that are
23       writable by other users), you should read the `Security Considerations'
24       chapter  of  the findutils documentation, which is called Finding Files
25       and comes with findutils.  That document also includes a lot  more  de‐
26       tail  and  discussion  than this manual page, so you may find it a more
27       useful source of information.
28

OPTIONS

30       The -H, -L and -P options control  the  treatment  of  symbolic  links.
31       Command-line  arguments  following these are taken to be names of files
32       or directories to be examined, up to the  first  argument  that  begins
33       with  `-', or the argument `(' or `!'.  That argument and any following
34       arguments are taken to be the  expression  describing  what  is  to  be
35       searched  for.   If  no paths are given, the current directory is used.
36       If no expression is given, the  expression  -print  is  used  (but  you
37       should probably consider using -print0 instead, anyway).
38
39       This  manual  page  talks  about  `options' within the expression list.
40       These options control the behaviour of find but are  specified  immedi‐
41       ately after the last path name.  The five `real' options -H, -L, -P, -D
42       and -O must appear before the first path name, if  at  all.   A  double
43       dash  -- could theoretically be used to signal that any remaining argu‐
44       ments are not options, but this does not really work  due  to  the  way
45       find  determines  the end of the following path arguments: it does that
46       by reading until an expression argument comes (which also starts with a
47       `-').   Now, if a path argument would start with a `-', then find would
48       treat it as expression argument instead.   Thus,  to  ensure  that  all
49       start points are taken as such, and especially to prevent that wildcard
50       patterns expanded by the calling shell are not  mistakenly  treated  as
51       expression  arguments, it is generally safer to prefix wildcards or du‐
52       bious path names with either `./' or to use absolute path names  start‐
53       ing  with '/'.  Alternatively, it is generally safe though non-portable
54       to use the GNU option -files0-from to pass arbitrary starting points to
55       find.
56
57
58       -P     Never  follow  symbolic  links.   This is the default behaviour.
59              When find examines or prints information about  files,  and  the
60              file  is  a  symbolic  link, the information used shall be taken
61              from the properties of the symbolic link itself.
62
63
64       -L     Follow symbolic links.  When find examines or prints information
65              about  files, the information used shall be taken from the prop‐
66              erties of the file to which the link points, not from  the  link
67              itself (unless it is a broken symbolic link or find is unable to
68              examine the file to which the link points).  Use of this  option
69              implies  -noleaf.   If you later use the -P option, -noleaf will
70              still be in effect.  If -L is in effect  and  find  discovers  a
71              symbolic link to a subdirectory during its search, the subdirec‐
72              tory pointed to by the symbolic link will be searched.
73
74              When the -L option is in effect, the -type predicate will always
75              match  against  the type of the file that a symbolic link points
76              to rather than the link itself (unless the symbolic link is bro‐
77              ken).   Actions  that  can cause symbolic links to become broken
78              while find is executing (for example -delete) can give  rise  to
79              confusing  behaviour.   Using  -L  causes the -lname and -ilname
80              predicates always to return false.
81
82
83       -H     Do not follow symbolic links, except while processing  the  com‐
84              mand  line  arguments.  When find examines or prints information
85              about files, the information used shall be taken from the  prop‐
86              erties  of the symbolic link itself.  The only exception to this
87              behaviour is when a file specified on the command line is a sym‐
88              bolic  link,  and the link can be resolved.  For that situation,
89              the information used is taken from whatever the link  points  to
90              (that is, the link is followed).  The information about the link
91              itself is used as a fallback if the file pointed to by the  sym‐
92              bolic  link  cannot  be examined.  If -H is in effect and one of
93              the paths specified on the command line is a symbolic link to  a
94              directory,  the  contents  of  that  directory  will be examined
95              (though of course -maxdepth 0 would prevent this).
96
97       If more than one of -H, -L and -P is specified, each overrides the oth‐
98       ers; the last one appearing on the command line takes effect.  Since it
99       is the default, the -P option should be considered to be in effect  un‐
100       less either -H or -L is specified.
101
102       GNU  find  frequently  stats files during the processing of the command
103       line itself, before any searching has begun.  These options also affect
104       how those arguments are processed.  Specifically, there are a number of
105       tests that compare files listed on the command line against a  file  we
106       are  currently  considering.   In  each case, the file specified on the
107       command line will have been examined and some of  its  properties  will
108       have been saved.  If the named file is in fact a symbolic link, and the
109       -P option is in effect (or if neither -H nor -L  were  specified),  the
110       information  used  for the comparison will be taken from the properties
111       of the symbolic link.  Otherwise, it will be taken from the  properties
112       of  the  file  the link points to.  If find cannot follow the link (for
113       example because it has insufficient privileges or the link points to  a
114       nonexistent file) the properties of the link itself will be used.
115
116       When  the  -H or -L options are in effect, any symbolic links listed as
117       the argument of -newer will be dereferenced, and the timestamp will  be
118       taken  from  the file to which the symbolic link points.  The same con‐
119       sideration applies to -newerXY, -anewer and -cnewer.
120
121       The -follow option has a similar effect to -L, though it  takes  effect
122       at  the  point where it appears (that is, if -L is not used but -follow
123       is, any symbolic links appearing after -follow on the command line will
124       be dereferenced, and those before it will not).
125
126
127       -D debugopts
128              Print  diagnostic  information;  this can be helpful to diagnose
129              problems with why find is not doing what you want.  The list  of
130              debug  options  should be comma separated.  Compatibility of the
131              debug options is not guaranteed between releases  of  findutils.
132              For  a  complete  list of valid debug options, see the output of
133              find -D help.  Valid debug options include
134
135              exec   Show diagnostic information relating to -exec,  -execdir,
136                     -ok and -okdir
137
138              opt    Prints  diagnostic  information relating to the optimisa‐
139                     tion of the expression tree; see the -O option.
140
141              rates  Prints a summary indicating how often each predicate suc‐
142                     ceeded or failed.
143
144              search Navigate the directory tree verbosely.
145
146              stat   Print  messages  as  files are examined with the stat and
147                     lstat system calls.  The find program tries  to  minimise
148                     such calls.
149
150              tree   Show  the  expression  tree in its original and optimised
151                     form.
152
153              all    Enable all of the other debug options (but help).
154
155              help   Explain the debugging options.
156
157       -Olevel
158              Enables query optimisation.  The find program reorders tests  to
159              speed up execution while preserving the overall effect; that is,
160              predicates with side effects are not reordered relative to  each
161              other.   The  optimisations performed at each optimisation level
162              are as follows.
163
164              0      Equivalent to optimisation level 1.
165
166              1      This is the default optimisation level and corresponds to
167                     the  traditional behaviour.  Expressions are reordered so
168                     that tests based only on the names of files (for  example
169                     -name and -regex) are performed first.
170
171              2      Any  -type  or -xtype tests are performed after any tests
172                     based only on the names of files, but  before  any  tests
173                     that  require information from the inode.  On many modern
174                     versions of Unix, file types are  returned  by  readdir()
175                     and so these predicates are faster to evaluate than pred‐
176                     icates which need to stat the file first.  If you use the
177                     -fstype FOO  predicate  and specify a filesystem type FOO
178                     which is not known (that is, present in  `/etc/mtab')  at
179                     the  time  find  starts,  that predicate is equivalent to
180                     -false.
181
182              3      At this optimisation level, the full cost-based query op‐
183                     timiser  is  enabled.   The order of tests is modified so
184                     that cheap (i.e. fast) tests are performed first and more
185                     expensive ones are performed later, if necessary.  Within
186                     each cost band, predicates are evaluated earlier or later
187                     according  to  whether they are likely to succeed or not.
188                     For -o, predicates which are likely to succeed are evalu‐
189                     ated  earlier, and for -a, predicates which are likely to
190                     fail are evaluated earlier.
191
192              The cost-based optimiser has a fixed  idea  of  how  likely  any
193              given  test  is to succeed.  In some cases the probability takes
194              account of the specific nature of the test (for example, -type f
195              is  assumed  to  be  more  likely to succeed than -type c).  The
196              cost-based optimiser is currently being evaluated.  If  it  does
197              not actually improve the performance of find, it will be removed
198              again.  Conversely, optimisations that prove to be reliable, ro‐
199              bust  and  effective may be enabled at lower optimisation levels
200              over time.  However, the default  behaviour  (i.e.  optimisation
201              level  1)  will not be changed in the 4.3.x release series.  The
202              findutils test suite runs all the tests on find at each  optimi‐
203              sation level and ensures that the result is the same.
204

EXPRESSION

206       The  part  of the command line after the list of starting points is the
207       expression.  This is a kind of query specification  describing  how  we
208       match  files  and  what we do with the files that were matched.  An ex‐
209       pression is composed of a sequence of things:
210
211
212       Tests  Tests return a true or false value, usually on the basis of some
213              property  of a file we are considering.  The -empty test for ex‐
214              ample is true only when the current file is empty.
215
216
217       Actions
218              Actions have side effects (such as  printing  something  on  the
219              standard  output) and return either true or false, usually based
220              on whether or not they are successful.  The  -print  action  for
221              example prints the name of the current file on the standard out‐
222              put.
223
224
225       Global options
226              Global options affect the operation of tests and actions  speci‐
227              fied on any part of the command line.  Global options always re‐
228              turn true.  The -depth option for example  makes  find  traverse
229              the file system in a depth-first order.
230
231
232       Positional options
233              Positional  options  affect  only  tests or actions which follow
234              them.  Positional options always return  true.   The  -regextype
235              option for example is positional, specifying the regular expres‐
236              sion dialect for regular expressions occurring later on the com‐
237              mand line.
238
239
240       Operators
241              Operators  join  together the other items within the expression.
242              They include for example -o (meaning logical OR) and -a (meaning
243              logical AND).  Where an operator is missing, -a is assumed.
244
245
246       The -print action is performed on all files for which the whole expres‐
247       sion is true, unless it contains an action other than -prune or  -quit.
248       Actions  which inhibit the default -print are -delete, -exec, -execdir,
249       -ok, -okdir, -fls, -fprint, -fprintf, -ls, -print and -printf.
250
251
252       The -delete action also acts like an option (since it implies -depth).
253
254
255   POSITIONAL OPTIONS
256       Positional options always return true.  They affect only  tests  occur‐
257       ring later on the command line.
258
259
260       -daystart
261              Measure  times  (for  -amin,  -atime,  -cmin, -ctime, -mmin, and
262              -mtime) from the beginning of today rather than  from  24  hours
263              ago.   This  option only affects tests which appear later on the
264              command line.
265
266
267       -follow
268              Deprecated; use the -L  option  instead.   Dereference  symbolic
269              links.   Implies -noleaf.  The -follow option affects only those
270              tests which appear after it on the command line.  Unless the  -H
271              or -L option has been specified, the position of the -follow op‐
272              tion changes the behaviour of the -newer  predicate;  any  files
273              listed  as  the  argument of -newer will be dereferenced if they
274              are symbolic links.  The same consideration applies to -newerXY,
275              -anewer and -cnewer.  Similarly, the -type predicate will always
276              match against the type of the file that a symbolic  link  points
277              to rather than the link itself.  Using -follow causes the -lname
278              and -ilname predicates always to return false.
279
280
281       -regextype type
282              Changes the regular expression syntax understood by  -regex  and
283              -iregex  tests  which  occur  later on the command line.  To see
284              which regular expression types are known,  use  -regextype help.
285              The Texinfo documentation (see SEE ALSO) explains the meaning of
286              and differences between the various types of regular expression.
287
288
289       -warn, -nowarn
290              Turn warning messages on or off.  These warnings apply  only  to
291              the  command  line  usage, not to any conditions that find might
292              encounter when it searches directories.  The  default  behaviour
293              corresponds  to -warn if standard input is a tty, and to -nowarn
294              otherwise.  If a warning message relating to command-line  usage
295              is  produced,  the  exit status of find is not affected.  If the
296              POSIXLY_CORRECT environment variable is set, and -warn  is  also
297              used,  it  is  not specified which, if any, warnings will be ac‐
298              tive.
299
300
301   GLOBAL OPTIONS
302       Global options always return true.  Global options take effect even for
303       tests  which  occur earlier on the command line.  To prevent confusion,
304       global options should specified on the command-line after the  list  of
305       start  points, just before the first test, positional option or action.
306       If you specify a global option in some other place, find will  issue  a
307       warning message explaining that this can be confusing.
308
309       The global options occur after the list of start points, and so are not
310       the same kind of option as -L, for example.
311
312
313       -d     A synonym for -depth, for compatibility  with  FreeBSD,  NetBSD,
314              MacOS X and OpenBSD.
315
316
317       -depth Process  each  directory's contents before the directory itself.
318              The -delete action also implies -depth.
319
320
321       -files0-from file
322              Read the starting points from file instead of  getting  them  on
323              the command line.  In contrast to the known limitations of pass‐
324              ing starting points via arguments on the  command  line,  namely
325              the limitation of the amount of file names, and the inherent am‐
326              biguity of file names clashing with option names, using this op‐
327              tion  allows  to  safely  pass  an  arbitrary number of starting
328              points to find.
329
330              Using this option and passing starting  points  on  the  command
331              line  is mutually exclusive, and is therefore not allowed at the
332              same time.
333
334              The file argument is mandatory.  One can use  -files0-from -  to
335              read the list of starting points from the standard input stream,
336              and e.g. from a pipe.  In this case, the actions -ok and  -okdir
337              are  not  allowed,  because  they would obviously interfere with
338              reading from standard input in order to get a user confirmation.
339
340              The starting points in file have to be separated  by  ASCII  NUL
341              characters.   Two  consecutive  NUL characters, i.e., a starting
342              point with a Zero-length file name is not allowed and will  lead
343              to an error diagnostic followed by a non-Zero exit code later.
344
345              In  the  case the given file is empty, find does not process any
346              starting point and therefore will exit immediately after parsing
347              the  program  arguments.  This is unlike the standard invocation
348              where find assumes the current directory as starting point if no
349              path argument is passed.
350
351              The  processing  of  the  starting points is otherwise as usual,
352              e.g.  find will recurse  into  subdirectories  unless  otherwise
353              prevented.   To  process only the starting points, one can addi‐
354              tionally pass -maxdepth 0.
355
356              Further notes: if a file is listed more than once in  the  input
357              file,  it  is  unspecified whether it is visited more than once.
358              If the file is mutated during the operation of find, the  result
359              is  unspecified  as well.  Finally, the seek position within the
360              named file at the time find exits, be it with -quit  or  in  any
361              other  way, is also unspecified.  By "unspecified" here is meant
362              that it may or may not work or do any specific thing,  and  that
363              the behavior may change from platform to platform, or from find‐
364              utils release to release.
365
366
367       -help, --help
368              Print a summary of the command-line usage of find and exit.
369
370
371       -ignore_readdir_race
372              Normally, find will emit an error message when it fails to  stat
373              a  file.   If you give this option and a file is deleted between
374              the time find reads the name of the file from the directory  and
375              the time it tries to stat the file, no error message will be is‐
376              sued.  This also applies to files or directories whose names are
377              given on the command line.  This option takes effect at the time
378              the command line is read, which means that you cannot search one
379              part  of  the filesystem with this option on and part of it with
380              this option off (if you need to do that, you will need to  issue
381              two  find  commands instead, one with the option and one without
382              it).
383
384              Furthermore, find with the -ignore_readdir_race option will  ig‐
385              nore  errors of the -delete action in the case the file has dis‐
386              appeared since the parent directory was read: it will not output
387              an  error  diagnostic, and the return code of the -delete action
388              will be true.
389
390
391       -maxdepth levels
392              Descend at most levels (a non-negative integer) levels of direc‐
393              tories  below the starting-points.  Using -maxdepth 0 means only
394              apply the tests and actions to the starting-points themselves.
395
396
397       -mindepth levels
398              Do not apply any tests or actions at levels less than levels  (a
399              non-negative  integer).   Using  -mindepth 1  means  process all
400              files except the starting-points.
401
402
403       -mount Don't descend directories on other  filesystems.   An  alternate
404              name  for  -xdev,  for compatibility with some other versions of
405              find.
406
407
408       -noignore_readdir_race
409              Turns off the effect of -ignore_readdir_race.
410
411
412       -noleaf
413              Do not optimize by assuming that  directories  contain  2  fewer
414              subdirectories  than  their  hard  link  count.   This option is
415              needed when searching filesystems that do not  follow  the  Unix
416              directory-link  convention, such as CD-ROM or MS-DOS filesystems
417              or AFS volume mount points.  Each directory  on  a  normal  Unix
418              filesystem  has  at least 2 hard links: its name and its `.' en‐
419              try.  Additionally, its subdirectories (if any) each have a `..'
420              entry linked to that directory.  When find is examining a direc‐
421              tory, after it has statted 2 fewer subdirectories than  the  di‐
422              rectory's  link  count, it knows that the rest of the entries in
423              the directory are non-directories (`leaf' files in the directory
424              tree).   If  only the files' names need to be examined, there is
425              no need to stat them;  this  gives  a  significant  increase  in
426              search speed.
427
428
429       -version, --version
430              Print the find version number and exit.
431
432
433       -xautofs
434              Don't descend directories on autofs filesystems.
435
436
437       -xdev  Don't descend directories on other filesystems.
438
439
440   TESTS
441       Some  tests,  for  example -newerXY and -samefile, allow comparison be‐
442       tween the file currently being examined and some reference file  speci‐
443       fied  on  the command line.  When these tests are used, the interpreta‐
444       tion of the reference file is determined by the options -H, -L  and  -P
445       and any previous -follow, but the reference file is only examined once,
446       at the time the command line is parsed.  If the reference  file  cannot
447       be examined (for example, the stat(2) system call fails for it), an er‐
448       ror message is issued, and find exits with a nonzero status.
449
450       A numeric argument n can be specified to  tests  (like  -amin,  -mtime,
451       -gid, -inum, -links, -size, -uid and -used) as
452
453       +n     for greater than n,
454
455       -n     for less than n,
456
457       n      for exactly n.
458
459       Supported tests:
460
461
462       -amin n
463              File was last accessed less than, more than or exactly n minutes
464              ago.
465
466
467       -anewer reference
468              Time of the last access of the current file is more recent  than
469              that  of  the  last data modification of the reference file.  If
470              reference is a symbolic link and the -H option or the -L  option
471              is in effect, then the time of the last data modification of the
472              file it points to is always used.
473
474
475       -atime n
476              File was last accessed less than,  more  than  or  exactly  n*24
477              hours  ago.   When find figures out how many 24-hour periods ago
478              the file was last accessed, any fractional part is  ignored,  so
479              to  match  -atime +1,  a file has to have been accessed at least
480              two days ago.
481
482
483       -cmin n
484              File's status was last changed less than, more than or exactly n
485              minutes ago.
486
487
488       -cnewer reference
489              Time  of  the last status change of the current file is more re‐
490              cent than that of the last data modification  of  the  reference
491              file.   If reference is a symbolic link and the -H option or the
492              -L option is in effect, then the time of the last data modifica‐
493              tion of the file it points to is always used.
494
495
496       -ctime n
497              File's  status  was last changed less than, more than or exactly
498              n*24 hours ago.  See the comments for -atime to  understand  how
499              rounding affects the interpretation of file status change times.
500
501
502       -empty File is empty and is either a regular file or a directory.
503
504
505       -executable
506              Matches  files  which  are  executable and directories which are
507              searchable (in a file name  resolution  sense)  by  the  current
508              user.   This  takes  into account access control lists and other
509              permissions artefacts which the -perm test ignores.   This  test
510              makes  use of the access(2) system call, and so can be fooled by
511              NFS servers which do UID mapping (or root-squashing), since many
512              systems implement access(2) in the client's kernel and so cannot
513              make use of the UID mapping information held on the server.  Be‐
514              cause  this  test  is  based only on the result of the access(2)
515              system call, there is no guarantee that a file  for  which  this
516              test succeeds can actually be executed.
517
518
519       -false Always false.
520
521
522       -fstype type
523              File  is  on  a  filesystem  of type type.  The valid filesystem
524              types vary among different versions of Unix; an incomplete  list
525              of filesystem types that are accepted on some version of Unix or
526              another is: ufs, 4.2, 4.3, nfs, tmp, mfs, S51K, S52K.   You  can
527              use  -printf  with  the  %F  directive  to see the types of your
528              filesystems.
529
530
531       -gid n File's numeric group ID is less than, more than or exactly n.
532
533
534       -group gname
535              File belongs to group gname (numeric group ID allowed).
536
537
538       -ilname pattern
539              Like -lname, but the match is case insensitive.  If the  -L  op‐
540              tion or the -follow option is in effect, this test returns false
541              unless the symbolic link is broken.
542
543
544
545       -iname pattern
546              Like -name, but the match is case insensitive.  For example, the
547              patterns  `fo*'  and  `F??'  match  the file names `Foo', `FOO',
548              `foo', `fOo', etc.  The pattern `*foo*` will also match  a  file
549              called '.foobar'.
550
551
552       -inum n
553              File  has  inode number smaller than, greater than or exactly n.
554              It is normally easier to use the -samefile test instead.
555
556
557       -ipath pattern
558              Like -path.  but the match is case insensitive.
559
560
561       -iregex pattern
562              Like -regex, but the match is case insensitive.
563
564
565       -iwholename pattern
566              See -ipath.  This alternative is less portable than -ipath.
567
568
569       -links n
570              File has less than, more than or exactly n hard links.
571
572
573       -lname pattern
574              File is a symbolic link whose contents match shell pattern  pat‐
575              tern.  The metacharacters do not treat `/' or `.' specially.  If
576              the -L option or the -follow option is in effect, this test  re‐
577              turns false unless the symbolic link is broken.
578
579
580       -mmin n
581              File's  data was last modified less than, more than or exactly n
582              minutes ago.
583
584
585       -mtime n
586              File's data was last modified less than, more  than  or  exactly
587              n*24  hours  ago.  See the comments for -atime to understand how
588              rounding affects the interpretation of file modification times.
589
590
591       -name pattern
592              Base of file name (the path with  the  leading  directories  re‐
593              moved)  matches  shell pattern pattern.  Because the leading di‐
594              rectories are removed, the file names  considered  for  a  match
595              with -name will never include a slash, so `-name a/b' will never
596              match anything (you probably need  to  use  -path  instead).   A
597              warning  is issued if you try to do this, unless the environment
598              variable POSIXLY_CORRECT is set.  The metacharacters (`*',  `?',
599              and  `[]')  match a `.' at the start of the base name (this is a
600              change in findutils-4.2.2; see section STANDARDS CONFORMANCE be‐
601              low).   To ignore a directory and the files under it, use -prune
602              rather than checking every file in the tree; see an  example  in
603              the  description  of  that action.  Braces are not recognised as
604              being special, despite the fact that some shells including  Bash
605              imbue  braces  with  a  special  meaning in shell patterns.  The
606              filename matching is performed with the use  of  the  fnmatch(3)
607              library function.  Don't forget to enclose the pattern in quotes
608              in order to protect it from expansion by the shell.
609
610
611       -newer reference
612              Time of the last data modification of the current file  is  more
613              recent  than that of the last data modification of the reference
614              file.  If reference is a symbolic link and the -H option or  the
615              -L option is in effect, then the time of the last data modifica‐
616              tion of the file it points to is always used.
617
618
619       -newerXY reference
620              Succeeds if timestamp X of the file being  considered  is  newer
621              than timestamp Y of the file reference.  The letters X and Y can
622              be any of the following letters:
623
624
625              a   The access time of the file reference
626              B   The birth time of the file reference
627              c   The inode status change time of reference
628              m   The modification time of the file reference
629              t   reference is interpreted directly as a time
630
631              Some combinations are invalid; for example, it is invalid for  X
632              to  be t.  Some combinations are not implemented on all systems;
633              for example B is not supported on all systems.  If an invalid or
634              unsupported  combination  of  XY is specified, a fatal error re‐
635              sults.  Time specifications are interpreted as for the  argument
636              to  the -d option of GNU date.  If you try to use the birth time
637              of a reference file, and the birth time cannot be determined,  a
638              fatal error message results.  If you specify a test which refers
639              to the birth time of files being examined, this test  will  fail
640              for any files where the birth time is unknown.
641
642
643       -nogroup
644              No group corresponds to file's numeric group ID.
645
646
647       -nouser
648              No user corresponds to file's numeric user ID.
649
650
651       -path pattern
652              File  name matches shell pattern pattern.  The metacharacters do
653              not treat `/' or `.' specially; so, for example,
654                  find . -path "./sr*sc"
655              will print an entry for a directory called  ./src/misc  (if  one
656              exists).   To  ignore  a whole directory tree, use -prune rather
657              than checking every file in the tree.   Note  that  the  pattern
658              match  test applies to the whole file name, starting from one of
659              the start points named on the command line.  It would only  make
660              sense  to  use  an absolute path name here if the relevant start
661              point is also an absolute path.  This means  that  this  command
662              will never match anything:
663                  find bar -path /foo/bar/myfile -print
664              Find compares the -path argument with the concatenation of a di‐
665              rectory name and the base  name  of  the  file  it's  examining.
666              Since the concatenation will never end with a slash, -path argu‐
667              ments ending in a slash will match  nothing  (except  perhaps  a
668              start point specified on the command line).  The predicate -path
669              is also supported by HP-UX find and is part of  the  POSIX  2008
670              standard.
671
672
673       -perm mode
674              File's  permission  bits  are  exactly mode (octal or symbolic).
675              Since an exact match is required, if you want to use  this  form
676              for  symbolic  modes,  you  may have to specify a rather complex
677              mode string.  For example `-perm  g=w'  will  only  match  files
678              which  have  mode 0020 (that is, ones for which group write per‐
679              mission is the only permission set).  It is more likely that you
680              will want to use the `/' or `-' forms, for example `-perm -g=w',
681              which matches any file with group write permission.  See the EX‐
682              AMPLES section for some illustrative examples.
683
684
685       -perm -mode
686              All  of the permission bits mode are set for the file.  Symbolic
687              modes are accepted in this form, and this is usually the way  in
688              which  you would want to use them.  You must specify `u', `g' or
689              `o' if you use a symbolic mode.  See the  EXAMPLES  section  for
690              some illustrative examples.
691
692
693       -perm /mode
694              Any  of the permission bits mode are set for the file.  Symbolic
695              modes are accepted in this form.  You must specify `u',  `g'  or
696              `o'  if  you  use a symbolic mode.  See the EXAMPLES section for
697              some illustrative examples.  If no permission bits in  mode  are
698              set,  this test matches any file (the idea here is to be consis‐
699              tent with the behaviour of -perm -000).
700
701
702       -perm +mode
703              This is no longer  supported  (and  has  been  deprecated  since
704              2005).  Use -perm /mode instead.
705
706
707       -readable
708              Matches  files  which  are  readable  by the current user.  This
709              takes into account access control lists  and  other  permissions
710              artefacts  which the -perm test ignores.  This test makes use of
711              the access(2) system call, and so can be fooled by  NFS  servers
712              which do UID mapping (or root-squashing), since many systems im‐
713              plement access(2) in the client's kernel and so cannot make  use
714              of the UID mapping information held on the server.
715
716
717       -regex pattern
718              File  name  matches regular expression pattern.  This is a match
719              on the whole path, not a search.  For example, to match  a  file
720              named  ./fubar3,  you can use the regular expression `.*bar.' or
721              `.*b.*3', but not `f.*r3'.  The regular  expressions  understood
722              by  find  are  by default Emacs Regular Expressions (except that
723              `.' matches newline), but this can be changed with  the  -regex‐
724              type option.
725
726
727       -samefile name
728              File  refers  to  the same inode as name.  When -L is in effect,
729              this can include symbolic links.
730
731
732       -size n[cwbkMG]
733              File uses less than, more than or  exactly  n  units  of  space,
734              rounding up.  The following suffixes can be used:
735
736              `b'    for  512-byte blocks (this is the default if no suffix is
737                     used)
738
739              `c'    for bytes
740
741              `w'    for two-byte words
742
743              `k'    for kibibytes (KiB, units of 1024 bytes)
744
745              `M'    for mebibytes (MiB, units of 1024 * 1024 = 1048576 bytes)
746
747              `G'    for gibibytes (GiB,  units  of  1024  *  1024  *  1024  =
748                     1073741824 bytes)
749
750              The  size  is simply the st_size member of the struct stat popu‐
751              lated by the lstat (or stat) system call, rounded  up  as  shown
752              above.   In other words, it's consistent with the result you get
753              for ls -l.  Bear in mind that the `%k' and  `%b'  format  speci‐
754              fiers  of -printf handle sparse files differently.  The `b' suf‐
755              fix always denotes 512-byte blocks and never  1024-byte  blocks,
756              which is different to the behaviour of -ls.
757
758              The  +  and  -  prefixes  signify greater than and less than, as
759              usual; i.e., an exact size of n units does not match.   Bear  in
760              mind  that  the  size is rounded up to the next unit.  Therefore
761              -size -1M is not equivalent to -size -1048576c.  The former only
762              matches  empty  files,  the  latter  matches  files  from  0  to
763              1,048,575 bytes.
764
765       -true  Always true.
766
767
768       -type c
769              File is of type c:
770
771              b      block (buffered) special
772
773              c      character (unbuffered) special
774
775              d      directory
776
777              p      named pipe (FIFO)
778
779              f      regular file
780
781              l      symbolic link; this is never true if the -L option or the
782                     -follow  option is in effect, unless the symbolic link is
783                     broken.  If you want to search for symbolic links when -L
784                     is in effect, use -xtype.
785
786              s      socket
787
788              D      door (Solaris)
789
790              To  search  for  more  than one type at once, you can supply the
791              combined list of type letters separated by a comma `,' (GNU  ex‐
792              tension).
793
794       -uid n File's numeric user ID is less than, more than or exactly n.
795
796
797       -used n
798              File  was  last  accessed less than, more than or exactly n days
799              after its status was last changed.
800
801
802       -user uname
803              File is owned by user uname (numeric user ID allowed).
804
805
806       -wholename pattern
807              See -path.  This alternative is less portable than -path.
808
809
810       -writable
811              Matches files which are writable  by  the  current  user.   This
812              takes  into  account  access control lists and other permissions
813              artefacts which the -perm test ignores.  This test makes use  of
814              the  access(2)  system call, and so can be fooled by NFS servers
815              which do UID mapping (or root-squashing), since many systems im‐
816              plement  access(2) in the client's kernel and so cannot make use
817              of the UID mapping information held on the server.
818
819
820       -xtype c
821              The same as -type unless the file is a symbolic link.  For  sym‐
822              bolic  links:  if the -H or -P option was specified, true if the
823              file is a link to a file of type c; if the -L  option  has  been
824              given,  true  if  c is `l'.  In other words, for symbolic links,
825              -xtype checks the type of the file that -type does not check.
826
827       -context pattern
828              (SELinux only) Security context of the file  matches  glob  pat‐
829              tern.
830
831
832   ACTIONS
833       -delete
834              Delete  files or directories; true if removal succeeded.  If the
835              removal failed, an error message is issued and find's exit  sta‐
836              tus will be nonzero (when it eventually exits).
837
838              Warning: Don't forget that find evaluates the command line as an
839              expression, so putting -delete  first  will  make  find  try  to
840              delete everything below the starting points you specified.
841
842              The  use of the -delete action on the command line automatically
843              turns on the -depth option.  As in turn -depth makes -prune  in‐
844              effective,  the  -delete action cannot usefully be combined with
845              -prune.
846
847              Often, the user might want to test  a  find  command  line  with
848              -print  prior  to adding -delete for the actual removal run.  To
849              avoid surprising results, it is usually best to remember to  use
850              -depth explicitly during those earlier test runs.
851
852              The  -delete action will fail to remove a directory unless it is
853              empty.
854
855              Together with the -ignore_readdir_race option, find will  ignore
856              errors  of  the  -delete  action in the case the file has disap‐
857              peared since the parent directory was read: it will  not  output
858              an  error  diagnostic,  not change the exit code to nonzero, and
859              the return code of the -delete action will be true.
860
861
862
863       -exec command ;
864              Execute command; true if 0 status is  returned.   All  following
865              arguments to find are taken to be arguments to the command until
866              an argument consisting of `;' is encountered.  The  string  `{}'
867              is  replaced by the current file name being processed everywhere
868              it occurs in the arguments to the command, not just in arguments
869              where  it  is alone, as in some versions of find.  Both of these
870              constructions might need to be escaped (with a `\') or quoted to
871              protect them from expansion by the shell.  See the EXAMPLES sec‐
872              tion for examples of the use of the -exec option.  The specified
873              command  is run once for each matched file.  The command is exe‐
874              cuted in the starting directory.  There are unavoidable security
875              problems surrounding use of the -exec action; you should use the
876              -execdir option instead.
877
878
879       -exec command {} +
880              This variant of the -exec action runs the specified  command  on
881              the  selected  files, but the command line is built by appending
882              each selected file name at the end; the total number of  invoca‐
883              tions  of  the  command  will  be  much  less than the number of
884              matched files.  The command line is built in much the  same  way
885              that  xargs builds its command lines.  Only one instance of `{}'
886              is allowed within the command, and it must appear  at  the  end,
887              immediately  before the `+'; it needs to be escaped (with a `\')
888              or quoted to protect it from interpretation by the  shell.   The
889              command  is  executed in the starting directory.  If any invoca‐
890              tion with the `+' form returns a non-zero value as exit  status,
891              then find returns a non-zero exit status.  If find encounters an
892              error, this can sometimes cause an immediate exit, so some pend‐
893              ing  commands  may not be run at all.  For this reason -exec my-
894              command ... {} + -quit may not result in my-command actually be‐
895              ing run.  This variant of -exec always returns true.
896
897
898       -execdir command ;
899
900       -execdir command {} +
901              Like  -exec, but the specified command is run from the subdirec‐
902              tory containing the matched file, which is not normally the  di‐
903              rectory in which you started find.  As with -exec, the {} should
904              be quoted if find is being invoked from a shell.   This  a  much
905              more secure method for invoking commands, as it avoids race con‐
906              ditions during resolution of the paths to the matched files.  As
907              with  the  -exec  action,  the `+' form of -execdir will build a
908              command line to process more than  one  matched  file,  but  any
909              given  invocation  of command will only list files that exist in
910              the same subdirectory.  If you use this option, you must  ensure
911              that your PATH environment variable does not reference `.'; oth‐
912              erwise, an attacker can run any commands they like by leaving an
913              appropriately-named  file  in  a directory in which you will run
914              -execdir.  The same applies to having entries in PATH which  are
915              empty or which are not absolute directory names.  If any invoca‐
916              tion with the `+' form returns a non-zero value as exit  status,
917              then find returns a non-zero exit status.  If find encounters an
918              error, this can sometimes cause an immediate exit, so some pend‐
919              ing  commands  may  not be run at all.  The result of the action
920              depends on whether the + or the ; variant is  being  used;  -ex‐
921              ecdir command {} +  always  returns  true,  while  -execdir com‐
922              mand {} ; returns true only if command returns 0.
923
924
925
926       -fls file
927              True; like -ls but write to file like -fprint.  The output  file
928              is  always created, even if the predicate is never matched.  See
929              the UNUSUAL FILENAMES section for information about how  unusual
930              characters in filenames are handled.
931
932
933       -fprint file
934              True; print the full file name into file file.  If file does not
935              exist when find is run, it is created; if it does exist,  it  is
936              truncated.   The file names /dev/stdout and /dev/stderr are han‐
937              dled specially; they refer to the standard output  and  standard
938              error  output, respectively.  The output file is always created,
939              even if the predicate is never matched.  See the  UNUSUAL  FILE‐
940              NAMES  section  for  information about how unusual characters in
941              filenames are handled.
942
943
944       -fprint0 file
945              True; like -print0 but write to file like -fprint.   The  output
946              file  is always created, even if the predicate is never matched.
947              See the UNUSUAL FILENAMES section for information about how  un‐
948              usual characters in filenames are handled.
949
950
951       -fprintf file format
952              True;  like  -printf but write to file like -fprint.  The output
953              file is always created, even if the predicate is never  matched.
954              See  the UNUSUAL FILENAMES section for information about how un‐
955              usual characters in filenames are handled.
956
957
958       -ls    True; list current file in ls -dils format on  standard  output.
959              The  block  counts  are  of  1 KB blocks, unless the environment
960              variable POSIXLY_CORRECT is set, in which case  512-byte  blocks
961              are  used.   See  the  UNUSUAL FILENAMES section for information
962              about how unusual characters in filenames are handled.
963
964
965       -ok command ;
966              Like -exec but ask the user first.  If the user agrees, run  the
967              command.   Otherwise  just return false.  If the command is run,
968              its standard input is redirected from  /dev/null.   This  action
969              may not be specified together with the -files0-from option.
970
971
972              The  response to the prompt is matched against a pair of regular
973              expressions to determine if it is an affirmative or negative re‐
974              sponse.   This regular expression is obtained from the system if
975              the POSIXLY_CORRECT environment variable is  set,  or  otherwise
976              from find's message translations.  If the system has no suitable
977              definition, find's own definition will be used.  In either case,
978              the  interpretation of the regular expression itself will be af‐
979              fected by the environment variables LC_CTYPE (character classes)
980              and LC_COLLATE (character ranges and equivalence classes).
981
982
983
984
985       -okdir command ;
986              Like -execdir but ask the user first in the same way as for -ok.
987              If the user does not agree, just return false.  If  the  command
988              is  run,  its standard input is redirected from /dev/null.  This
989              action may not be specified together with the  -files0-from  op‐
990              tion.
991
992
993
994       -print True;  print the full file name on the standard output, followed
995              by a newline.  If you are piping the output of find into another
996              program  and  there  is  the faintest possibility that the files
997              which you are searching for might contain a  newline,  then  you
998              should  seriously  consider  using the -print0 option instead of
999              -print.  See the UNUSUAL FILENAMES section for information about
1000              how unusual characters in filenames are handled.
1001
1002
1003       -print0
1004              True;  print the full file name on the standard output, followed
1005              by a null character  (instead  of  the  newline  character  that
1006              -print  uses).   This allows file names that contain newlines or
1007              other types of white space to be correctly interpreted  by  pro‐
1008              grams  that process the find output.  This option corresponds to
1009              the -0 option of xargs.
1010
1011
1012       -printf format
1013              True; print format on the standard output, interpreting `\'  es‐
1014              capes  and  `%'  directives.  Field widths and precisions can be
1015              specified as with the printf(3) C function.   Please  note  that
1016              many  of  the  fields are printed as %s rather than %d, and this
1017              may mean that flags don't work as you might expect.   This  also
1018              means  that the `-' flag does work (it forces fields to be left-
1019              aligned).  Unlike -print, -printf does not add a newline at  the
1020              end of the string.  The escapes and directives are:
1021
1022              \a     Alarm bell.
1023
1024              \b     Backspace.
1025
1026              \c     Stop  printing from this format immediately and flush the
1027                     output.
1028
1029              \f     Form feed.
1030
1031              \n     Newline.
1032
1033              \r     Carriage return.
1034
1035              \t     Horizontal tab.
1036
1037              \v     Vertical tab.
1038
1039              \0     ASCII NUL.
1040
1041              \\     A literal backslash (`\').
1042
1043              \NNN   The character whose ASCII code is NNN (octal).
1044
1045              A `\' character followed by any other character is treated as an
1046              ordinary character, so they both are printed.
1047
1048              %%     A literal percent sign.
1049
1050              %a     File's  last  access time in the format returned by the C
1051                     ctime(3) function.
1052
1053              %Ak    File's last access time in the  format  specified  by  k,
1054                     which  is either `@' or a directive for the C strftime(3)
1055                     function.  The following shows an incomplete list of pos‐
1056                     sible values for k.  Please refer to the documentation of
1057                     strftime(3) for the full list.  Some  of  the  conversion
1058                     specification  characters  might  not be available on all
1059                     systems, due to differences in the implementation of  the
1060                     strftime(3) library function.
1061
1062                     @      seconds  since Jan. 1, 1970, 00:00 GMT, with frac‐
1063                            tional part.
1064
1065                     Time fields:
1066
1067                     H      hour (00..23)
1068
1069                     I      hour (01..12)
1070
1071                     k      hour ( 0..23)
1072
1073                     l      hour ( 1..12)
1074
1075                     M      minute (00..59)
1076
1077                     p      locale's AM or PM
1078
1079                     r      time, 12-hour (hh:mm:ss [AP]M)
1080
1081                     S      Second (00.00 .. 61.00).  There  is  a  fractional
1082                            part.
1083
1084                     T      time, 24-hour (hh:mm:ss.xxxxxxxxxx)
1085
1086                     +      Date  and  time,  separated  by  `+',  for example
1087                            `2004-04-28+22:22:05.0'.  This is a GNU extension.
1088                            The  time  is given in the current timezone (which
1089                            may be affected  by  setting  the  TZ  environment
1090                            variable).   The  seconds  field  includes a frac‐
1091                            tional part.
1092
1093                     X      locale's time representation (H:M:S).  The seconds
1094                            field includes a fractional part.
1095
1096                     Z      time  zone (e.g., EDT), or nothing if no time zone
1097                            is determinable
1098
1099                     Date fields:
1100
1101                     a      locale's abbreviated weekday name (Sun..Sat)
1102
1103                     A      locale's full weekday name, variable length  (Sun‐
1104                            day..Saturday)
1105
1106                     b      locale's abbreviated month name (Jan..Dec)
1107
1108                     B      locale's  full  month name, variable length (Janu‐
1109                            ary..December)
1110
1111                     c      locale's date and time (Sat Nov  04  12:02:33  EST
1112                            1989).  The format is the same as for ctime(3) and
1113                            so to preserve  compatibility  with  that  format,
1114                            there is no fractional part in the seconds field.
1115
1116                     d      day of month (01..31)
1117
1118                     D      date (mm/dd/yy)
1119
1120                     F      date (yyyy-mm-dd)
1121
1122                     h      same as b
1123
1124                     j      day of year (001..366)
1125
1126                     m      month (01..12)
1127
1128                     U      week  number  of  year with Sunday as first day of
1129                            week (00..53)
1130
1131                     w      day of week (0..6)
1132
1133                     W      week number of year with Monday as  first  day  of
1134                            week (00..53)
1135
1136                     x      locale's date representation (mm/dd/yy)
1137
1138                     y      last two digits of year (00..99)
1139
1140                     Y      year (1970...)
1141
1142              %b     The  amount  of disk space used for this file in 512-byte
1143                     blocks.  Since disk space is allocated  in  multiples  of
1144                     the  filesystem  block  size this is usually greater than
1145                     %s/512, but it can also be  smaller  if  the  file  is  a
1146                     sparse file.
1147
1148
1149              %Bk    File's birth time, i.e., its creation time, in the format
1150                     specified by k, which is the same as for %A.  This direc‐
1151                     tive produces an empty string if the underlying operating
1152                     system or filesystem does not support birth times.
1153
1154
1155              %c     File's last status change time in the format returned  by
1156                     the C ctime(3) function.
1157
1158              %Ck    File's last status change time in the format specified by
1159                     k, which is the same as for %A.
1160
1161              %d     File's depth in the directory tree; 0 means the file is a
1162                     starting-point.
1163
1164              %D     The  device  number  on which the file exists (the st_dev
1165                     field of struct stat), in decimal.
1166
1167              %f     Print the basename; the file's name with any leading  di‐
1168                     rectories  removed  (only  the last element).  For /, the
1169                     result is `/'.  See the EXAMPLES section for an example.
1170
1171
1172              %F     Type of the filesystem the file is on; this value can  be
1173                     used for -fstype.
1174
1175              %g     File's  group  name, or numeric group ID if the group has
1176                     no name.
1177
1178              %G     File's numeric group ID.
1179
1180              %h     Dirname; the Leading directories of the file's name  (all
1181                     but  the  last  element).   If  the file name contains no
1182                     slashes (since it is in the  current  directory)  the  %h
1183                     specifier expands to `.'.  For files which are themselves
1184                     directories and contain a slash (including /), %h expands
1185                     to the empty string.  See the EXAMPLES section for an ex‐
1186                     ample.
1187
1188              %H     Starting-point under which file was found.
1189
1190              %i     File's inode number (in decimal).
1191
1192              %k     The amount of disk space  used  for  this  file  in  1 KB
1193                     blocks.   Since  disk  space is allocated in multiples of
1194                     the filesystem block size this is  usually  greater  than
1195                     %s/1024,  but  it  can  also  be smaller if the file is a
1196                     sparse file.
1197
1198              %l     Object of symbolic link (empty string if file  is  not  a
1199                     symbolic link).
1200
1201              %m     File's  permission bits (in octal).  This option uses the
1202                     `traditional' numbers  which  most  Unix  implementations
1203                     use,  but  if  your particular implementation uses an un‐
1204                     usual ordering of octal permissions bits, you will see  a
1205                     difference  between  the  actual value of the file's mode
1206                     and the output of %m.  Normally you will want to  have  a
1207                     leading  zero  on this number, and to do this, you should
1208                     use the # flag (as in, for example, `%#m').
1209
1210              %M     File's permissions (in symbolic form, as for  ls).   This
1211                     directive is supported in findutils 4.2.5 and later.
1212
1213              %n     Number of hard links to file.
1214
1215              %p     File's name.
1216
1217              %P     File's  name  with  the  name of the starting-point under
1218                     which it was found removed.
1219
1220              %s     File's size in bytes.
1221
1222              %S     File's  sparseness.   This  is  calculated   as   (BLOCK‐
1223                     SIZE*st_blocks  / st_size).  The exact value you will get
1224                     for an ordinary file of a certain length is system-depen‐
1225                     dent.   However,  normally  sparse files will have values
1226                     less than 1.0, and files which use  indirect  blocks  may
1227                     have  a  value which is greater than 1.0.  In general the
1228                     number of blocks used by a file is file system dependent.
1229                     The  value used for BLOCKSIZE is system-dependent, but is
1230                     usually 512 bytes.  If the file size is zero,  the  value
1231                     printed  is undefined.  On systems which lack support for
1232                     st_blocks, a file's sparseness is assumed to be 1.0.
1233
1234              %t     File's last modification time in the format  returned  by
1235                     the C ctime(3) function.
1236
1237              %Tk    File's  last modification time in the format specified by
1238                     k, which is the same as for %A.
1239
1240              %u     File's user name, or numeric user ID if the user  has  no
1241                     name.
1242
1243              %U     File's numeric user ID.
1244
1245              %y     File's  type  (like  in ls -l), U=unknown type (shouldn't
1246                     happen)
1247
1248              %Y     File's  type  (like  %y),  plus  follow  symbolic  links:
1249                     `L'=loop,  `N'=nonexistent,  `?' for any other error when
1250                     determining the type of the target of a symbolic link.
1251
1252              %Z     (SELinux only) file's security context.
1253
1254              %{ %[ %(
1255                     Reserved for future use.
1256
1257              A `%' character followed by any other  character  is  discarded,
1258              but  the other character is printed (don't rely on this, as fur‐
1259              ther format characters may be introduced).  A `%' at the end  of
1260              the format argument causes undefined behaviour since there is no
1261              following character.  In some locales, it  may  hide  your  door
1262              keys,  while  in  others  it  may remove the final page from the
1263              novel you are reading.
1264
1265              The %m and %d directives support the #, 0 and + flags,  but  the
1266              other  directives  do  not, even if they print numbers.  Numeric
1267              directives that do not support these flags include G, U, b, D, k
1268              and  n.  The `-' format flag is supported and changes the align‐
1269              ment of a field from right-justified (which is the  default)  to
1270              left-justified.
1271
1272              See  the UNUSUAL FILENAMES section for information about how un‐
1273              usual characters in filenames are handled.
1274
1275
1276
1277       -prune True; if the file is a directory, do not descend  into  it.   If
1278              -depth is given, then -prune has no effect.  Because -delete im‐
1279              plies -depth, you cannot usefully use  -prune  and  -delete  to‐
1280              gether.   For  example,  to skip the directory src/emacs and all
1281              files and directories under it, and print the names of the other
1282              files found, do something like this:
1283                  find . -path ./src/emacs -prune -o -print
1284
1285
1286
1287       -quit  Exit  immediately  (with return value zero if no errors have oc‐
1288              curred).  This is different to -prune because  -prune  only  ap‐
1289              plies  to the contents of pruned directories, while -quit simply
1290              makes find stop immediately.  No child processes  will  be  left
1291              running.  Any command lines which have been built by -exec ... +
1292              or -execdir ... + are invoked before the program is exited.  Af‐
1293              ter  -quit  is  executed, no more files specified on the command
1294              line      will      be      processed.        For       example,
1295              `find /tmp/foo /tmp/bar -print -quit`     will     print    only
1296              `/tmp/foo`.
1297              One common use of -quit is to stop  searching  the  file  system
1298              once  we  have  found  what we want.  For example, if we want to
1299              find just a single file we can do this:
1300                  find / -name needle -print -quit
1301
1302
1303   OPERATORS
1304       Listed in order of decreasing precedence:
1305
1306
1307       ( expr )
1308              Force precedence.  Since parentheses are special to  the  shell,
1309              you  will  normally need to quote them.  Many of the examples in
1310              this manual page use backslashes for this purpose: `\(...\)' in‐
1311              stead of `(...)'.
1312
1313
1314       ! expr True  if  expr  is false.  This character will also usually need
1315              protection from interpretation by the shell.
1316
1317
1318       -not expr
1319              Same as ! expr, but not POSIX compliant.
1320
1321
1322       expr1 expr2
1323              Two expressions in a row are taken to be joined with an  implied
1324              -a; expr2 is not evaluated if expr1 is false.
1325
1326
1327       expr1 -a expr2
1328              Same as expr1 expr2.
1329
1330
1331       expr1 -and expr2
1332              Same as expr1 expr2, but not POSIX compliant.
1333
1334
1335       expr1 -o expr2
1336              Or; expr2 is not evaluated if expr1 is true.
1337
1338
1339       expr1 -or expr2
1340              Same as expr1 -o expr2, but not POSIX compliant.
1341
1342
1343       expr1 , expr2
1344              List;  both  expr1 and expr2 are always evaluated.  The value of
1345              expr1 is discarded; the value of the list is the value of expr2.
1346              The  comma operator can be useful for searching for several dif‐
1347              ferent types of thing, but traversing the  filesystem  hierarchy
1348              only  once.  The -fprintf action can be used to list the various
1349              matched items into several different output files.
1350
1351       Please note that -a when specified implicitly (for example by two tests
1352       appearing  without an explicit operator between them) or explicitly has
1353       higher precedence than -o.  This means that find . -name afile -o -name
1354       bfile -print will never print afile.
1355

UNUSUAL FILENAMES

1357       Many of the actions of find result in the printing of data which is un‐
1358       der the control of other users.  This includes file names, sizes, modi‐
1359       fication  times and so forth.  File names are a potential problem since
1360       they can contain any character except `\0' and `/'.  Unusual characters
1361       in  file  names  can do unexpected and often undesirable things to your
1362       terminal (for example, changing the settings of your function  keys  on
1363       some terminals).  Unusual characters are handled differently by various
1364       actions, as described below.
1365
1366
1367       -print0, -fprint0
1368              Always print the exact filename, unchanged, even if  the  output
1369              is going to a terminal.
1370
1371
1372       -ls, -fls
1373              Unusual  characters are always escaped.  White space, backslash,
1374              and double quote characters are printed using  C-style  escaping
1375              (for  example `\f', `\"').  Other unusual characters are printed
1376              using an octal escape.  Other printable characters (for -ls  and
1377              -fls  these  are  the characters between octal 041 and 0176) are
1378              printed as-is.
1379
1380
1381       -printf, -fprintf
1382              If the output is not going to a terminal, it is  printed  as-is.
1383              Otherwise, the result depends on which directive is in use.  The
1384              directives %D, %F, %g, %G, %H, %Y, and %y expand to values which
1385              are  not  under control of files' owners, and so are printed as-
1386              is.  The directives %a, %b, %c, %d, %i, %k, %m, %M, %n, %s,  %t,
1387              %u and %U have values which are under the control of files' own‐
1388              ers but which cannot be used to send arbitrary data to the  ter‐
1389              minal,  and  so these are printed as-is.  The directives %f, %h,
1390              %l, %p and %P are quoted.  This quoting is performed in the same
1391              way  as  for  GNU ls.  This is not the same quoting mechanism as
1392              the one used for -ls and -fls.  If you are able to  decide  what
1393              format  to use for the output of find then it is normally better
1394              to use `\0' as a terminator than to use newline, as  file  names
1395              can  contain white space and newline characters.  The setting of
1396              the LC_CTYPE environment variable is  used  to  determine  which
1397              characters need to be quoted.
1398
1399
1400       -print, -fprint
1401              Quoting  is handled in the same way as for -printf and -fprintf.
1402              If you are using find in a script or in a  situation  where  the
1403              matched  files  might  have arbitrary names, you should consider
1404              using -print0 instead of -print.
1405
1406       The -ok and -okdir actions print the current filename as-is.  This  may
1407       change in a future release.
1408

STANDARDS CONFORMANCE

1410       For  closest  compliance  to  the  POSIX  standard,  you should set the
1411       POSIXLY_CORRECT environment variable.  The following options are speci‐
1412       fied in the POSIX standard (IEEE Std 1003.1-2008, 2016 Edition):
1413
1414
1415       -H     This option is supported.
1416
1417
1418       -L     This option is supported.
1419
1420
1421       -name  This  option  is supported, but POSIX conformance depends on the
1422              POSIX conformance of the system's fnmatch(3)  library  function.
1423              As  of  findutils-4.2.2,  shell metacharacters (`*', `?' or `[]'
1424              for example) match a leading `.', because IEEE PASC  interpreta‐
1425              tion 126 requires this.  This is a change from previous versions
1426              of findutils.
1427
1428
1429       -type  Supported.  POSIX specifies `b', `c', `d',  `l',  `p',  `f'  and
1430              `s'.  GNU find also supports `D', representing a Door, where the
1431              OS provides these.  Furthermore, GNU find allows multiple  types
1432              to be specified at once in a comma-separated list.
1433
1434
1435       -ok    Supported.   Interpretation  of the response is according to the
1436              `yes' and `no' patterns selected by setting the LC_MESSAGES  en‐
1437              vironment  variable.  When the POSIXLY_CORRECT environment vari‐
1438              able is set, these patterns are taken system's definition  of  a
1439              positive (yes) or negative (no) response.  See the system's doc‐
1440              umentation for nl_langinfo(3), in particular YESEXPR and NOEXPR.
1441              When  POSIXLY_CORRECT is not set, the patterns are instead taken
1442              from find's own message catalogue.
1443
1444
1445       -newer Supported.  If the file specified is a symbolic link, it is  al‐
1446              ways  dereferenced.   This  is a change from previous behaviour,
1447              which used to take the relevant time from the symbolic link; see
1448              the HISTORY section below.
1449
1450
1451       -perm  Supported.   If  the POSIXLY_CORRECT environment variable is not
1452              set, some mode arguments (for example +a+x) which are not  valid
1453              in POSIX are supported for backward-compatibility.
1454
1455
1456       Other primaries
1457              The  primaries  -atime,  -ctime,  -depth, -exec, -group, -links,
1458              -mtime, -nogroup, -nouser, -ok, -path,  -print,  -prune,  -size,
1459              -user and -xdev are all supported.
1460
1461
1462       The POSIX standard specifies parentheses `(', `)', negation `!' and the
1463       logical AND/OR operators -a and -o.
1464
1465       All other options, predicates, expressions and so forth are  extensions
1466       beyond  the POSIX standard.  Many of these extensions are not unique to
1467       GNU find, however.
1468
1469       The POSIX standard requires that find detects loops:
1470
1471              The find utility shall detect infinite loops; that is,  entering
1472              a  previously  visited directory that is an ancestor of the last
1473              file encountered.  When it detects an infinite loop, find  shall
1474              write  a  diagnostic  message to standard error and shall either
1475              recover its position in the hierarchy or terminate.
1476
1477       GNU find complies with these requirements.  The link count of  directo‐
1478       ries which contain entries which are hard links to an ancestor will of‐
1479       ten be lower than they otherwise should be.  This  can  mean  that  GNU
1480       find  will sometimes optimise away the visiting of a subdirectory which
1481       is actually a link to an ancestor.  Since find does not actually  enter
1482       such  a subdirectory, it is allowed to avoid emitting a diagnostic mes‐
1483       sage.  Although this behaviour may be somewhat  confusing,  it  is  un‐
1484       likely  that  anybody  actually depends on this behaviour.  If the leaf
1485       optimisation has been turned off with -noleaf, the directory entry will
1486       always  be  examined and the diagnostic message will be issued where it
1487       is appropriate.  Symbolic links cannot be used to create filesystem cy‐
1488       cles  as  such, but if the -L option or the -follow option is in use, a
1489       diagnostic message is issued when find encounters a  loop  of  symbolic
1490       links.  As with loops containing hard links, the leaf optimisation will
1491       often mean that find knows that it  doesn't  need  to  call  stat()  or
1492       chdir() on the symbolic link, so this diagnostic is frequently not nec‐
1493       essary.
1494
1495       The -d option is supported for compatibility with various BSD  systems,
1496       but you should use the POSIX-compliant option -depth instead.
1497
1498       The  POSIXLY_CORRECT environment variable does not affect the behaviour
1499       of the -regex or -iregex tests because those tests aren't specified  in
1500       the POSIX standard.
1501

ENVIRONMENT VARIABLES

1503       LANG   Provides  a default value for the internationalization variables
1504              that are unset or null.
1505
1506
1507       LC_ALL If set to a non-empty string value, override the values  of  all
1508              the other internationalization variables.
1509
1510
1511       LC_COLLATE
1512              The POSIX standard specifies that this variable affects the pat‐
1513              tern matching to be used for the -name option.   GNU  find  uses
1514              the  fnmatch(3)  library function, and so support for LC_COLLATE
1515              depends on the system library.  This variable also  affects  the
1516              interpretation  of  the  response  to -ok; while the LC_MESSAGES
1517              variable selects the actual pattern used to  interpret  the  re‐
1518              sponse  to -ok, the interpretation of any bracket expressions in
1519              the pattern will be affected by LC_COLLATE.
1520
1521
1522       LC_CTYPE
1523              This variable affects the treatment of character classes used in
1524              regular  expressions  and  also with the -name test, if the sys‐
1525              tem's fnmatch(3) library function supports this.  This  variable
1526              also  affects the interpretation of any character classes in the
1527              regular expressions used to interpret the response to the prompt
1528              issued  by -ok.  The LC_CTYPE environment variable will also af‐
1529              fect which characters are  considered  to  be  unprintable  when
1530              filenames are printed; see the section UNUSUAL FILENAMES.
1531
1532
1533       LC_MESSAGES
1534              Determines the locale to be used for internationalised messages.
1535              If the POSIXLY_CORRECT environment variable is  set,  this  also
1536              determines the interpretation of the response to the prompt made
1537              by the -ok action.
1538
1539
1540       NLSPATH
1541              Determines the location of the internationalisation message cat‐
1542              alogues.
1543
1544
1545       PATH   Affects  the directories which are searched to find the executa‐
1546              bles invoked by -exec, -execdir, -ok and -okdir.
1547
1548
1549       POSIXLY_CORRECT
1550              Determines the block size used by -ls and -fls.  If POSIXLY_COR‐
1551              RECT  is set, blocks are units of 512 bytes.  Otherwise they are
1552              units of 1024 bytes.
1553
1554              Setting this variable also turns off warning messages (that  is,
1555              implies  -nowarn)  by default, because POSIX requires that apart
1556              from the output for -ok, all messages printed on stderr are  di‐
1557              agnostics and must result in a non-zero exit status.
1558
1559              When POSIXLY_CORRECT is not set, -perm +zzz is treated just like
1560              -perm  /zzz  if  +zzz  is  not  a  valid  symbolic  mode.   When
1561              POSIXLY_CORRECT is set, such constructs are treated as an error.
1562
1563              When  POSIXLY_CORRECT is set, the response to the prompt made by
1564              the -ok action is interpreted according to the system's  message
1565              catalogue,  as opposed to according to find's own message trans‐
1566              lations.
1567
1568
1569       TZ     Affects the time zone used for some of the  time-related  format
1570              directives of -printf and -fprintf.
1571

EXAMPLES

1573   Simple `find|xargs` approach
1574       •      Find  files named core in or below the directory /tmp and delete
1575              them.
1576
1577                  $ find /tmp -name core -type f -print | xargs /bin/rm -f
1578
1579              Note that this will work incorrectly if there are any  filenames
1580              containing newlines, single or double quotes, or spaces.
1581
1582   Safer `find -print0 | xargs -0` approach
1583       •      Find  files named core in or below the directory /tmp and delete
1584              them, processing filenames in such a way that file or  directory
1585              names containing single or double quotes, spaces or newlines are
1586              correctly handled.
1587
1588                  $ find /tmp -name core -type f -print0 | xargs -0 /bin/rm -f
1589
1590              The -name test comes before the -type test  in  order  to  avoid
1591              having to call stat(2) on every file.
1592
1593       Note that there is still a race between the time find traverses the hi‐
1594       erarchy printing the matching filenames, and the time the process  exe‐
1595       cuted by xargs works with that file.
1596
1597   Processing arbitrary starting points
1598       •      Given that another program proggy pre-filters and creates a huge
1599              NUL-separated list of files, process those as  starting  points,
1600              and find all regular, empty files among them:
1601
1602                  $ proggy | find -files0-from - -maxdepth 0 -type f -empty
1603
1604              The  use  of  `-files0-from -`  means  to  read the names of the
1605              starting points from standard input, i.e., from  the  pipe;  and
1606              -maxdepth 0 ensures that only explicitly those entries are exam‐
1607              ined without recursing into directories (in the case one of  the
1608              starting points is one).
1609
1610   Executing a command for each file
1611       •      Run file on every file in or below the current directory.
1612
1613                  $ find . -type f -exec file '{}' \;
1614
1615              Notice  that  the  braces  are enclosed in single quote marks to
1616              protect them from interpretation as  shell  script  punctuation.
1617              The  semicolon is similarly protected by the use of a backslash,
1618              though single quotes could have been used in that case also.
1619
1620       In many cases, one might prefer the `-exec ... +` or better  the  `-ex‐
1621       ecdir ... +` syntax for performance and security reasons.
1622
1623   Traversing the filesystem just once - for 2 different actions
1624       •      Traverse the filesystem just once, listing set-user-ID files and
1625              directories   into   /root/suid.txt   and   large   files   into
1626              /root/big.txt.
1627
1628                  $ find / \
1629                      \( -perm -4000 -fprintf /root/suid.txt '%#m %u %p\n' \) , \
1630                      \( -size +100M -fprintf /root/big.txt '%-10s %p\n' \)
1631
1632              This  example  uses  the  line-continuation character '\' on the
1633              first two lines to instruct the shell to  continue  reading  the
1634              command on the next line.
1635
1636   Searching files by age
1637       •      Search for files in your home directory which have been modified
1638              in the last twenty-four hours.
1639
1640                  $ find $HOME -mtime 0
1641
1642              This command works this way because the time since each file was
1643              last  modified  is divided by 24 hours and any remainder is dis‐
1644              carded.  That means that to match -mtime 0, a file will have  to
1645              have a modification in the past which is less than 24 hours ago.
1646
1647   Searching files by permissions
1648       •      Search for files which are executable but not readable.
1649
1650                  $ find /sbin /usr/sbin -executable \! -readable -print
1651
1652
1653       •      Search  for files which have read and write permission for their
1654              owner, and group, but which other users can read but  not  write
1655              to.
1656
1657                  $ find . -perm 664
1658
1659              Files  which meet these criteria but have other permissions bits
1660              set (for example if someone can execute the file)  will  not  be
1661              matched.
1662
1663       •      Search  for files which have read and write permission for their
1664              owner and group, and which other users can read, without  regard
1665              to  the  presence  of any extra permission bits (for example the
1666              executable bit).
1667
1668                  $ find . -perm -664
1669
1670              This will match a file which has mode 0777, for example.
1671
1672       •      Search for files which are writable by somebody (their owner, or
1673              their group, or anybody else).
1674
1675                  $ find . -perm /222
1676
1677
1678       •      Search  for  files  which  are writable by either their owner or
1679              their group.
1680
1681                  $ find . -perm /220
1682                  $ find . -perm /u+w,g+w
1683                  $ find . -perm /u=w,g=w
1684
1685              All three of these commands do the same thing, but the first one
1686              uses  the  octal  representation of the file mode, and the other
1687              two use the symbolic form.  The files don't have to be  writable
1688              by both the owner and group to be matched; either will do.
1689
1690       •      Search  for  files  which  are  writable by both their owner and
1691              their group.
1692
1693                  $ find . -perm -220
1694                  $ find . -perm -g+w,u+w
1695
1696              Both these commands do the same thing.
1697
1698       •      A more elaborate search on permissions.
1699
1700                  $ find . -perm -444 -perm /222 \! -perm /111
1701                  $ find . -perm -a+r -perm /a+w \! -perm /a+x
1702
1703              These two commands both search for files that are  readable  for
1704              everybody  (-perm  -444  or -perm -a+r), have at least one write
1705              bit set (-perm /222 or -perm /a+w) but are  not  executable  for
1706              anybody (! -perm /111 or ! -perm /a+x respectively).
1707
1708   Pruning - omitting files and subdirectories
1709       •      Copy  the  contents  of /source-dir to /dest-dir, but omit files
1710              and directories named .snapshot (and anything in them).  It also
1711              omits files or directories whose name ends in `~', but not their
1712              contents.
1713
1714                  $ cd /source-dir
1715                  $ find . -name .snapshot -prune -o \( \! -name '*~' -print0 \) \
1716                      | cpio -pmd0 /dest-dir
1717
1718              The construct -prune -o \( ... -print0 \) is quite common.   The
1719              idea  here  is  that the expression before -prune matches things
1720              which are to be pruned.  However, the -prune action  itself  re‐
1721              turns true, so the following -o ensures that the right hand side
1722              is evaluated only for those directories which didn't get  pruned
1723              (the contents of the pruned directories are not even visited, so
1724              their contents are irrelevant).  The  expression  on  the  right
1725              hand  side of the -o is in parentheses only for clarity.  It em‐
1726              phasises that the -print0 action takes  place  only  for  things
1727              that  didn't  have  -prune applied to them.  Because the default
1728              `and' condition between tests binds more tightly than  -o,  this
1729              is  the default anyway, but the parentheses help to show what is
1730              going on.
1731
1732       •      Given the following directory of projects and  their  associated
1733              SCM  administrative directories, perform an efficient search for
1734              the projects' roots:
1735
1736                  $ find repo/ \
1737                      \( -exec test -d '{}/.svn' \; \
1738                      -or -exec test -d '{}/.git' \; \
1739                      -or -exec test -d '{}/CVS' \; \
1740                      \) -print -prune
1741
1742              Sample output:
1743
1744                  repo/project1/CVS
1745                  repo/gnu/project2/.svn
1746                  repo/gnu/project3/.svn
1747                  repo/gnu/project3/src/.svn
1748                  repo/project4/.git
1749
1750              In this example, -prune prevents unnecessary descent into direc‐
1751              tories  that have already been discovered (for example we do not
1752              search project3/src because we already found project3/.svn), but
1753              ensures sibling directories (project2 and project3) are found.
1754
1755   Other useful examples
1756       •      Search for several file types.
1757
1758                  $ find /tmp -type f,d,l
1759
1760              Search  for files, directories, and symbolic links in the direc‐
1761              tory /tmp passing these types as a comma-separated list (GNU ex‐
1762              tension),  which is otherwise equivalent to the longer, yet more
1763              portable:
1764
1765                  $ find /tmp \( -type f -o -type d -o -type l \)
1766
1767
1768       •      Search for files with the particular name needle and stop  imme‐
1769              diately when we find the first one.
1770
1771                  $ find / -name needle -print -quit
1772
1773
1774       •      Demonstrate  the  interpretation  of the %f and %h format direc‐
1775              tives of the -printf action for some corner-cases.  Here  is  an
1776              example including some output.
1777
1778                  $ find . .. / /tmp /tmp/TRACE compile compile/64/tests/find -maxdepth 0 -printf '[%h][%f]\n'
1779                  [.][.]
1780                  [.][..]
1781                  [][/]
1782                  [][tmp]
1783                  [/tmp][TRACE]
1784                  [.][compile]
1785                  [compile/64/tests][find]
1786
1787

EXIT STATUS

1789       find  exits  with  status  0  if  all files are processed successfully,
1790       greater than 0 if errors occur.  This is deliberately a very broad  de‐
1791       scription,  but if the return value is non-zero, you should not rely on
1792       the correctness of the results of find.
1793
1794       When some error occurs, find may stop immediately,  without  completing
1795       all  the  actions specified.  For example, some starting points may not
1796       have  been  examined  or   some   pending   program   invocations   for
1797       -exec ... {} + or -execdir ... {} + may not have been performed.
1798

HISTORY

1800       As of findutils-4.2.2, shell metacharacters (`*', `?' or `[]' for exam‐
1801       ple) used in filename patterns match a leading `.', because IEEE  POSIX
1802       interpretation 126 requires this.
1803
1804       As  of  findutils-4.3.3,  -perm /000  now  matches all files instead of
1805       none.
1806
1807       Nanosecond-resolution timestamps were implemented in findutils-4.3.3.
1808
1809       As of findutils-4.3.11, the -delete action sets find's exit status to a
1810       nonzero  value when it fails.  However, find will not exit immediately.
1811       Previously, find's  exit  status  was  unaffected  by  the  failure  of
1812       -delete.
1813
1814       Feature                Added in   Also occurs in
1815       -files0-from           4.9.0
1816       -newerXY               4.3.3      BSD
1817       -D                     4.3.1
1818       -O                     4.3.1
1819       -readable              4.3.0
1820       -writable              4.3.0
1821       -executable            4.3.0
1822       -regextype             4.2.24
1823       -exec ... +            4.2.12     POSIX
1824       -execdir               4.2.12     BSD
1825       -okdir                 4.2.12
1826       -samefile              4.2.11
1827       -H                     4.2.5      POSIX
1828       -L                     4.2.5      POSIX
1829       -P                     4.2.5      BSD
1830       -delete                4.2.3
1831       -quit                  4.2.3
1832       -d                     4.2.3      BSD
1833       -wholename             4.2.0
1834       -iwholename            4.2.0
1835       -ignore_readdir_race   4.2.0
1836       -fls                   4.0
1837       -ilname                3.8
1838       -iname                 3.8
1839       -ipath                 3.8
1840       -iregex                3.8
1841
1842       The  syntax  -perm  +MODE was removed in findutils-4.5.12, in favour of
1843       -perm /MODE.   The  +MODE  syntax  had  been  deprecated  since  findu‐
1844       tils-4.2.21 which was released in 2005.
1845

NON-BUGS

1847   Operator precedence surprises
1848       The  command  find . -name afile -o -name bfile -print will never print
1849       afile because this is actually equivalent to find . -name afile  -o  \(
1850       -name bfile -a -print \).  Remember that the precedence of -a is higher
1851       than that of -o and when there is no operator specified between  tests,
1852       -a is assumed.
1853
1854   “paths must precede expression” error message
1855       $ find . -name *.c -print
1856       find: paths must precede expression
1857       find: possible unquoted pattern after predicate `-name'?
1858
1859       This  happens  when the shell could expand the pattern *.c to more than
1860       one file name existing in the current directory, and  passing  the  re‐
1861       sulting file names in the command line to find like this:
1862       find . -name frcode.c locate.c word_io.c -print
1863       That  command  is of course not going to work, because the -name predi‐
1864       cate allows exactly only one pattern as  argument.   Instead  of  doing
1865       things this way, you should enclose the pattern in quotes or escape the
1866       wildcard, thus allowing find to use the pattern with the wildcard  dur‐
1867       ing the search for file name matching instead of file names expanded by
1868       the parent shell:
1869       $ find . -name '*.c' -print
1870       $ find . -name \*.c -print
1871

BUGS

1873       There are security problems inherent in the behaviour  that  the  POSIX
1874       standard  specifies for find, which therefore cannot be fixed.  For ex‐
1875       ample, the -exec action is inherently insecure, and -execdir should  be
1876       used instead.
1877
1878       The environment variable LC_COLLATE has no effect on the -ok action.
1879

REPORTING BUGS

1881       GNU   findutils   online   help:   <https://www.gnu.org/software/findu
1882       tils/#get-help>
1883       Report any translation bugs to <https://translationproject.org/team/>
1884
1885       Report any other issue via the form at the GNU Savannah bug tracker:
1886              <https://savannah.gnu.org/bugs/?group=findutils>
1887       General topics about the GNU findutils package  are  discussed  at  the
1888       bug-findutils mailing list:
1889              <https://lists.gnu.org/mailman/listinfo/bug-findutils>
1890
1892       Copyright  ©  1990-2022 Free Software Foundation, Inc.  License GPLv3+:
1893       GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
1894       This is free software: you are free  to  change  and  redistribute  it.
1895       There is NO WARRANTY, to the extent permitted by law.
1896

SEE ALSO

1898       chmod(1),  locate(1),  ls(1), updatedb(1), xargs(1), lstat(2), stat(2),
1899       ctime(3) fnmatch(3), printf(3), strftime(3), locatedb(5), regex(7)
1900
1901       Full documentation <https://www.gnu.org/software/findutils/find>
1902       or available locally via: info find
1903
1904
1905
1906                                                                       FIND(1)
Impressum