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

EXPRESSION

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

UNUSUAL FILENAMES

1208       Many  of  the  actions  of find result in the printing of data which is
1209       under the control of other users.  This  includes  file  names,  sizes,
1210       modification  times  and  so forth.  File names are a potential problem
1211       since they can contain any character  except  `\0'  and  `/'.   Unusual
1212       characters in file names can do unexpected and often undesirable things
1213       to your terminal (for example, changing the settings of  your  function
1214       keys on some terminals).  Unusual characters are handled differently by
1215       various actions, as described below.
1216
1217
1218       -print0, -fprint0
1219              Always print the exact filename, unchanged, even if  the  output
1220              is going to a terminal.
1221
1222
1223       -ls, -fls
1224              Unusual  characters are always escaped.  White space, backslash,
1225              and double quote characters are printed using  C-style  escaping
1226              (for  example `\f', `\"').  Other unusual characters are printed
1227              using an octal escape.  Other printable characters (for -ls  and
1228              -fls  these  are  the characters between octal 041 and 0176) are
1229              printed as-is.
1230
1231
1232       -printf, -fprintf
1233              If the output is not going to a terminal, it is  printed  as-is.
1234              Otherwise, the result depends on which directive is in use.  The
1235              directives %D, %F, %g, %G, %H, %Y, and %y expand to values which
1236              are  not  under control of files' owners, and so are printed as-
1237              is.  The directives %a, %b, %c, %d, %i, %k, %m, %M, %n, %s,  %t,
1238              %u and %U have values which are under the control of files' own‐
1239              ers but which cannot be used to send arbitrary data to the  ter‐
1240              minal,  and  so these are printed as-is.  The directives %f, %h,
1241              %l, %p and %P are quoted.  This quoting is performed in the same
1242              way  as  for  GNU ls.  This is not the same quoting mechanism as
1243              the one used for -ls and -fls.  If you are able to  decide  what
1244              format  to use for the output of find then it is normally better
1245              to use `\0' as a terminator than to use newline, as  file  names
1246              can  contain white space and newline characters.  The setting of
1247              the `LC_CTYPE' environment variable is used to  determine  which
1248              characters need to be quoted.
1249
1250
1251       -print, -fprint
1252              Quoting  is handled in the same way as for -printf and -fprintf.
1253              If you are using find in a script or in a  situation  where  the
1254              matched  files  might  have arbitrary names, you should consider
1255              using -print0 instead of -print.
1256
1257       The -ok and -okdir actions print the current filename as-is.  This  may
1258       change in a future release.
1259
1260

STANDARDS CONFORMANCE

1262       For  closest  compliance  to  the  POSIX  standard,  you should set the
1263       POSIXLY_CORRECT environment variable.  The following options are speci‐
1264       fied in the POSIX standard (IEEE Std 1003.1, 2003 Edition):
1265
1266
1267       -H     This option is supported.
1268
1269
1270       -L     This option is supported.
1271
1272
1273       -name  This  option  is supported, but POSIX conformance depends on the
1274              POSIX conformance of the system's fnmatch(3)  library  function.
1275              As  of  findutils-4.2.2,  shell metacharacters (`*', `?' or `[]'
1276              for example) will match a leading `.', because IEEE PASC  inter‐
1277              pretation  126  requires  this.   This is a change from previous
1278              versions of findutils.
1279
1280
1281       -type  Supported.   POSIX specifies `b', `c', `d', `l',  `p',  `f'  and
1282              `s'.  GNU find also supports `D', representing a Door, where the
1283              OS provides these.
1284
1285
1286       -ok    Supported.  Interpretation of the response is according  to  the
1287              "yes"  and  "no"  patterns selected by setting the `LC_MESSAGES'
1288              environment variable.  When  the  `POSIXLY_CORRECT'  environment
1289              variable is set, these patterns are taken system's definition of
1290              a positive (yes) or negative (no) response.   See  the  system's
1291              documentation  for  nl_langinfo(3),  in  particular  YESEXPR and
1292              NOEXPR.    When `POSIXLY_CORRECT' is not set, the  patterns  are
1293              instead taken from find's own message catalogue.
1294
1295
1296       -newer Supported.   If  the  file  specified  is a symbolic link, it is
1297              always dereferenced.  This is a change from previous  behaviour,
1298              which used to take the relevant time from the symbolic link; see
1299              the HISTORY section below.
1300
1301
1302       -perm  Supported.  If the POSIXLY_CORRECT environment variable  is  not
1303              set,  some mode arguments (for example +a+x) which are not valid
1304              in POSIX are supported for backward-compatibility.
1305
1306
1307       Other predicates
1308              The predicates -atime, -ctime, -depth, -group,  -links,  -mtime,
1309              -nogroup,  -nouser,  -print,  -prune,  -size,  -user  and  -xdev
1310              `-atime',  `-ctime',  `-depth',  `-group',  `-links',  `-mtime',
1311              `-nogroup',  `-nouser',  `-perm',  `-print',  `-prune', `-size',
1312              `-user' and `-xdev', are all supported.
1313
1314
1315       The POSIX standard specifies parentheses `(', `)', negation `!' and the
1316       `and' and `or' operators ( -a, -o).
1317
1318       All  other options, predicates, expressions and so forth are extensions
1319       beyond the POSIX standard.  Many of these extensions are not unique  to
1320       GNU find, however.
1321
1322       The POSIX standard requires that find detects loops:
1323
1324              The  find utility shall detect infinite loops; that is, entering
1325              a previously visited directory that is an ancestor of  the  last
1326              file  encountered.  When it detects an infinite loop, find shall
1327              write a diagnostic message to standard error  and  shall  either
1328              recover its position in the hierarchy or terminate.
1329
1330       GNU  find complies with these requirements.  The link count of directo‐
1331       ries which contain entries which are hard links  to  an  ancestor  will
1332       often  be  lower than they otherwise should be.  This can mean that GNU
1333       find will sometimes optimise away the visiting of a subdirectory  which
1334       is  actually a link to an ancestor.  Since find does not actually enter
1335       such a subdirectory, it is allowed to avoid emitting a diagnostic  mes‐
1336       sage.   Although  this  behaviour  may  be  somewhat  confusing,  it is
1337       unlikely that anybody actually depends on this behaviour.  If the  leaf
1338       optimisation has been turned off with -noleaf, the directory entry will
1339       always be examined and the diagnostic message will be issued  where  it
1340       is  appropriate.   Symbolic  links  cannot be used to create filesystem
1341       cycles as such, but if the -L option or the -follow option is in use, a
1342       diagnostic  message  is  issued when find encounters a loop of symbolic
1343       links.  As with loops containing hard links, the leaf optimisation will
1344       often  mean  that  find  knows  that  it doesn't need to call stat() or
1345       chdir() on the symbolic link, so this diagnostic is frequently not nec‐
1346       essary.
1347
1348       The  -d option is supported for compatibility with various BSD systems,
1349       but you should use the POSIX-compliant option -depth instead.
1350
1351       The POSIXLY_CORRECT environment variable does not affect the  behaviour
1352       of  the -regex or -iregex tests because those tests aren't specified in
1353       the POSIX standard.
1354

ENVIRONMENT VARIABLES

1356       LANG   Provides a default value for the internationalization  variables
1357              that are unset or null.
1358
1359
1360       LC_ALL If  set  to a non-empty string value, override the values of all
1361              the other internationalization variables.
1362
1363
1364       LC_COLLATE
1365              The POSIX standard specifies that this variable affects the pat‐
1366              tern  matching  to be used for the -name option.   GNU find uses
1367              the fnmatch(3) library function, and so support for `LC_COLLATE'
1368              depends on the system library.    This variable also affects the
1369              interpretation of the response to -ok; while  the  `LC_MESSAGES'
1370              variable  selects  the  actual  pattern  used  to  interpret the
1371              response to -ok, the interpretation of any  bracket  expressions
1372              in the pattern will be affected by `LC_COLLATE'.
1373
1374
1375       LC_CTYPE
1376              This variable affects the treatment of character classes used in
1377              regular expressions and also with the -name test,  if  the  sys‐
1378              tem's  fnmatch(3) library function supports this.  This variable
1379              also affects the interpretation of any character classes in  the
1380              regular expressions used to interpret the response to the prompt
1381              issued by -ok.  The `LC_CTYPE' environment  variable  will  also
1382              affect  which  characters  are considered to be unprintable when
1383              filenames are printed; see the section UNUSUAL FILENAMES.
1384
1385
1386       LC_MESSAGES
1387              Determines the locale to be used for internationalised messages.
1388              If  the `POSIXLY_CORRECT' environment variable is set, this also
1389              determines the interpretation of the response to the prompt made
1390              by the -ok action.
1391
1392
1393       NLSPATH
1394              Determines the location of the internationalisation message cat‐
1395              alogues.
1396
1397
1398       PATH   Affects the directories which are searched to find the  executa‐
1399              bles invoked by -exec, -execdir, -ok and -okdir.
1400
1401
1402       POSIXLY_CORRECT
1403              Determines the block size used by -ls and -fls.  If POSIXLY_COR‐
1404              RECT is set, blocks are units of 512 bytes.  Otherwise they  are
1405              units of 1024 bytes.
1406
1407              Setting  this variable also turns off warning messages (that is,
1408              implies -nowarn) by default, because POSIX requires  that  apart
1409              from  the  output  for  -ok,  all messages printed on stderr are
1410              diagnostics and must result in a non-zero exit status.
1411
1412              When POSIXLY_CORRECT is not set, -perm +zzz is treated just like
1413              -perm  /zzz  if  +zzz  is  not  a  valid  symbolic  mode.   When
1414              POSIXLY_CORRECT is set, such constructs are treated as an error.
1415
1416              When POSIXLY_CORRECT is set, the response to the prompt made  by
1417              the  -ok action is interpreted according to the system's message
1418              catalogue, as opposed to according to find's own message  trans‐
1419              lations.
1420
1421
1422       TZ     Affects  the  time zone used for some of the time-related format
1423              directives of -printf and -fprintf.
1424

EXAMPLES

1426       find /tmp -name core -type f -print | xargs /bin/rm -f
1427
1428       Find files named core in or below the directory /tmp and  delete  them.
1429       Note  that  this  will work incorrectly if there are any filenames con‐
1430       taining newlines, single or double quotes, or spaces.
1431
1432       find /tmp -name core -type f -print0 | xargs -0 /bin/rm -f
1433
1434       Find files named core in or below the directory /tmp and  delete  them,
1435       processing  filenames  in  such a way that file or directory names con‐
1436       taining single or double quotes, spaces or newlines are correctly  han‐
1437       dled.   The  -name  test  comes before the -type test in order to avoid
1438       having to call stat(2) on every file.
1439
1440
1441       find . -type f -exec file '{}' \;
1442
1443       Runs `file' on every file in or below the  current  directory.   Notice
1444       that the braces are enclosed in single quote marks to protect them from
1445       interpretation as shell script punctuation.  The semicolon is similarly
1446       protected  by  the  use of a backslash, though single quotes could have
1447       been used in that case also.
1448
1449
1450       find / \( -perm -4000 -fprintf /root/suid.txt '%#m %u %p\n' \) , \
1451       \( -size +100M -fprintf /root/big.txt '%-10s %p\n' \)
1452
1453       Traverse the filesystem just once, listing setuid files and directories
1454       into /root/suid.txt and large files into /root/big.txt.
1455
1456
1457       find $HOME -mtime 0
1458
1459       Search for files in your home directory which have been modified in the
1460       last twenty-four hours.  This command works this way because  the  time
1461       since  each  file  was  last  modified  is  divided by 24 hours and any
1462       remainder is discarded.  That means that to match -mtime 0, a file will
1463       have  to  have  a  modification in the past which is less than 24 hours
1464       ago.
1465
1466
1467       find /sbin /usr/sbin -executable \! -readable -print
1468
1469       Search for files which are executable but not readable.
1470
1471
1472       find . -perm 664
1473
1474       Search for files which have read and write permission for their  owner,
1475       and  group,  but  which  other  users can read but not write to.  Files
1476       which meet these criteria but have  other  permissions  bits  set  (for
1477       example if someone can execute the file) will not be matched.
1478
1479
1480       find . -perm -664
1481
1482       Search  for  files which have read and write permission for their owner
1483       and group, and which other users can read, without regard to the  pres‐
1484       ence  of  any  extra  permission bits (for example the executable bit).
1485       This will match a file which has mode 0777, for example.
1486
1487
1488       find . -perm /222
1489
1490       Search for files which are writable by somebody (their owner, or  their
1491       group, or anybody else).
1492
1493
1494       find . -perm /220
1495       find . -perm /u+w,g+w
1496       find . -perm /u=w,g=w
1497
1498       All  three  of these commands do the same thing, but the first one uses
1499       the octal representation of the file mode, and the other  two  use  the
1500       symbolic  form.  These commands all search for files which are writable
1501       by either their owner or their group.   The  files  don't  have  to  be
1502       writable by both the owner and group to be matched; either will do.
1503
1504
1505       find . -perm -220
1506       find . -perm -g+w,u+w
1507
1508       Both  these  commands  do  the  same  thing; search for files which are
1509       writable by both their owner and their group.
1510
1511
1512       find . -perm -444 -perm /222 ! -perm /111
1513       find . -perm -a+r -perm /a+w ! -perm /a+x
1514
1515       These two commands both search for files that are readable  for  every‐
1516       body  (  -perm  -444  or -perm -a+r), have at least one write bit set (
1517       -perm /222 or -perm /a+w) but are not executable for anybody ( !  -perm
1518       /111 and ! -perm /a+x respectively).
1519
1520
1521       cd /source-dir
1522       find . -name .snapshot -prune -o \( \! -name *~ -print0 \)|
1523       cpio -pmd0 /dest-dir
1524
1525       This command copies the contents of /source-dir to /dest-dir, but omits
1526       files and directories named .snapshot (and anything in them).  It  also
1527       omits  files  or  directories  whose name ends in ~, but not their con‐
1528       tents.  The construct -prune -o \( ... -print0 \) is quite common.  The
1529       idea here is that the expression before -prune matches things which are
1530       to be pruned.  However, the -prune action itself returns true,  so  the
1531       following  -o  ensures  that  the right hand side is evaluated only for
1532       those directories which didn't get pruned (the contents of  the  pruned
1533       directories  are  not  even visited, so their contents are irrelevant).
1534       The expression on the right hand side of the -o is in parentheses  only
1535       for  clarity.   It  emphasises that the -print0 action takes place only
1536       for things that didn't  have  -prune  applied  to  them.   Because  the
1537       default  `and' condition between tests binds more tightly than -o, this
1538       is the default anyway, but the parentheses help to show what  is  going
1539       on.
1540
1541
1542       find repo/ -exec test -d {}/.svn \; -or \
1543       -exec test -d {}/.git \; -or -exec test -d {}/CVS \; \
1544       -print -prune
1545
1546       Given  the  following  directory  of  projects and their associated SCM
1547       administrative  directories,  perform  an  efficient  search  for   the
1548       projects' roots:
1549
1550       repo/project1/CVS
1551       repo/gnu/project2/.svn
1552       repo/gnu/project3/.svn
1553       repo/gnu/project3/src/.svn
1554       repo/project4/.git
1555
1556       In  this  example, -prune prevents unnecessary descent into directories
1557       that have already  been  discovered  (for  example  we  do  not  search
1558       project3/src  because we already found project3/.svn), but ensures sib‐
1559       ling directories (project2 and project3) are found.
1560
1561

EXIT STATUS

1563       find exits with status 0  if  all  files  are  processed  successfully,
1564       greater  than  0  if  errors occur.   This is deliberately a very broad
1565       description, but if the return value is non-zero, you should  not  rely
1566       on the correctness of the results of find.
1567
1568       When  some  error occurs, find may stop immediately, without completing
1569       all the actions specified.  For example, some starting points  may  not
1570       have been examined or some pending program invocations for -exec ... {}
1571       + or -execdir ... {} + may not have been performed.
1572
1573
1574

SEE ALSO

1576       locate(1), locatedb(5), updatedb(1),  xargs(1),  chmod(1),  fnmatch(3),
1577       regex(7), stat(2), lstat(2), ls(1), printf(3), strftime(3), ctime(3)
1578
1579       The  full documentation for find is maintained as a Texinfo manual.  If
1580       the info and find programs are properly installed  at  your  site,  the
1581       command info find should give you access to the complete manual.
1582
1583

HISTORY

1585       As of findutils-4.2.2, shell metacharacters (`*', `?' or `[]' for exam‐
1586       ple) used in filename patterns will match a leading `.',  because  IEEE
1587       POSIX interpretation 126 requires this.
1588
1589       As  of  findutils-4.3.3,  -perm  /000  now matches all files instead of
1590       none.
1591
1592       Nanosecond-resolution timestamps were implemented in findutils-4.3.3.
1593
1594       As of findutils-4.3.11, the -delete action sets find's exit status to a
1595       nonzero  value when it fails.  However, find will not exit immediately.
1596       Previously, find's  exit  status  was  unaffected  by  the  failure  of
1597       -delete.
1598
1599       Feature                Added in   Also occurs in
1600       -newerXY               4.3.3      BSD
1601       -D                     4.3.1
1602       -O                     4.3.1
1603       -readable              4.3.0
1604       -writable              4.3.0
1605       -executable            4.3.0
1606       -regextype             4.2.24
1607       -exec ... +            4.2.12     POSIX
1608       -execdir               4.2.12     BSD
1609       -okdir                 4.2.12
1610       -samefile              4.2.11
1611       -H                     4.2.5      POSIX
1612       -L                     4.2.5      POSIX
1613       -P                     4.2.5      BSD
1614       -delete                4.2.3
1615       -quit                  4.2.3
1616       -d                     4.2.3      BSD
1617       -wholename             4.2.0
1618       -iwholename            4.2.0
1619       -ignore_readdir_race   4.2.0
1620       -fls                   4.0
1621       -ilname                3.8
1622       -iname                 3.8
1623       -ipath                 3.8
1624       -iregex                3.8
1625
1626       The  syntax  -perm  +MODE was removed in findutils-4.5.12, in favour of
1627       -perm /MODE.   The  +MODE  syntax  had  been  deprecated  since  findu‐
1628       tils-4.2.21 which was released in 2005.
1629

NON-BUGS

1631       $ find . -name *.c -print
1632       find: paths must precede expression
1633       Usage: find [-H] [-L] [-P] [-Olevel] [-D help|tree|search|stat|rates|opt|exec] [path...] [expression]
1634
1635       This  happens  because  *.c has been expanded by the shell resulting in
1636       find actually receiving a command line like this:
1637
1638       find . -name bigram.c code.c frcode.c locate.c -print
1639
1640       That command is of course not going to work.  Instead of  doing  things
1641       this  way, you should enclose the pattern in quotes or escape the wild‐
1642       card:
1643       $ find . -name '*.c' -print
1644       $ find . -name \*.c -print
1645
1646

BUGS

1648       There are security problems inherent in the behaviour  that  the  POSIX
1649       standard  specifies  for  find,  which  therefore cannot be fixed.  For
1650       example, the -exec action is inherently insecure, and  -execdir  should
1651       be used instead.  Please see Finding Files for more information.
1652
1653       The environment variable LC_COLLATE has no effect on the -ok action.
1654
1655       The  best  way  to  report  a  bug  is to use the form at http://savan
1656       nah.gnu.org/bugs/?group=findutils.  The reason for  this  is  that  you
1657       will then be able to track progress in fixing the problem.   Other com‐
1658       ments about find(1) and about the findutils package in general  can  be
1659       sent  to  the bug-findutils mailing list.  To join the list, send email
1660       to bug-findutils-request@gnu.org.
1661
1662
1663
1664                                                                       FIND(1)
Impressum