1 \input texinfo @c -*-texinfo-*-
4 @settitle Finding Files
5 @c For double-sided printing, uncomment:
6 @c @setchapternewpage odd
17 * Finding files: (find). Operating on files matching certain criteria.
20 @dircategory Individual utilities
22 * find: (find)Invoking find. Finding and acting on files.
23 * locate: (find)Invoking locate. Finding files in a database.
24 * updatedb: (find)Invoking updatedb. Building the locate database.
25 * xargs: (find)Invoking xargs. Operating on many files.
30 This file documents the GNU utilities for finding files that match
31 certain criteria and performing various operations on them.
33 Copyright (C) 1994, 1996, 1998, 2000, 2001, 2003, 2004, 2005 Free
34 Software Foundation, Inc.
36 Permission is granted to make and distribute verbatim copies of
37 this manual provided the copyright notice and this permission notice
38 are preserved on all copies.
41 Permission is granted to process this file through TeX and print the
42 results, provided the printed document carries copying permission
43 notice identical to this one except for the removal of this paragraph
44 (this paragraph not being relevant to the printed manual).
47 Permission is granted to copy and distribute modified versions of this
48 manual under the conditions for verbatim copying, provided that the
49 entire resulting derived work is distributed under the terms of a
50 permission notice identical to this one.
52 Permission is granted to copy and distribute translations of this
53 manual into another language, under the above conditions for modified
54 versions, except that this permission notice may be stated in a
55 translation approved by the Foundation.
60 @subtitle Edition @value{EDITION}, for GNU @code{find} version @value{VERSION}
61 @subtitle @value{UPDATED}
62 @author by David MacKenzie and James Youngman
65 @vskip 0pt plus 1filll
72 @node Top, Introduction, , (dir)
73 @comment node-name, next, previous, up
75 This file documents the GNU utilities for finding files that match
76 certain criteria and performing various actions on them.
78 This is edition @value{EDITION}, for @code{find} version @value{VERSION}.
81 @c The master menu, created with texinfo-master-menu, goes here.
84 * Introduction:: Summary of the tasks this manual describes.
85 * Finding Files:: Finding files that match certain criteria.
86 * Actions:: Doing things to files you have found.
87 * Databases:: Maintaining file name databases.
88 * File Permissions:: How to control access to files.
89 * Reference:: Summary of how to invoke the programs.
90 * Common Tasks:: Solutions to common real-world problems.
91 * Worked Examples:: Examples demonstrating more complex points.
92 * Security Considerations:: Security issues relating to findutils.
93 * Error Messages:: Explanations of some messages you might see.
94 * Primary Index:: The components of @code{find} expressions.
97 @node Introduction, Finding Files, Top, Top
100 This manual shows how to find files that meet criteria you specify,
101 and how to perform various actions on the files that you find. The
102 principal programs that you use to perform these tasks are
103 @code{find}, @code{locate}, and @code{xargs}. Some of the examples in
104 this manual use capabilities specific to the GNU versions of those
107 GNU @code{find} was originally written by Eric Decker, with
108 enhancements by David MacKenzie, Jay Plett, and Tim Wood. GNU
109 @code{xargs} was originally written by Mike Rendell, with enhancements
110 by David MacKenzie. GNU @code{locate} and its associated utilities
111 were originally written by James Woods, with enhancements by David
112 MacKenzie. The idea for @samp{find -print0} and @samp{xargs -0} came
113 from Dan Bernstein. The current maintainer of GNU findutils (and this
114 manual) is James Youngman. Many other people have contributed bug
115 fixes, small improvements, and helpful suggestions. Thanks!
117 To report a bug in GNU findutils, please use the form on the Savannah
119 @code{http://savannah.gnu.org/bugs/?group=findutils}. Reporting bugs
120 this way means that you will then be able to track progress in fixing
123 If you don't have web access, you can also just send mail to the
124 mailing list. The mailing list @email{bug-findutils@@gnu.org} carries
125 discussion of bugs in findutils, questions and answers about the
126 software and discussion of the development of the programs. To join
127 the list, send email to @email{bug-findutils-request@@gnu.org}.
129 Please read any relevant sections of this manual before asking for
130 help on the mailing list. You may also find it helpful to read the
131 NON-BUGS section of the @code{find} manual page.
133 If you ask for help on the mailing list, people will be able to help
134 you much more effectively if you include the following things:
137 @item The version of the software you are running. You can find this
138 out by running @samp{locate --version}.
139 @item What you were trying to do
140 @item The @emph{exact} command line you used
141 @item The @emph{exact} output you got (if this is very long, try to
142 find a smaller example which exhibits the same problem)
143 @item The output you expected to get
155 For brevity, the word @dfn{file} in this manual means a regular file,
156 a directory, a symbolic link, or any other kind of node that has a
157 directory entry. A directory entry is also called a @dfn{file name}.
158 A file name may contain some, all, or none of the directories in a
159 path that leads to the file. These are all examples of what this
160 manual calls ``file names'':
167 /usr/local/include/termcap.h
170 A @dfn{directory tree} is a directory and the files it contains, all
171 of its subdirectories and the files they contain, etc. It can also be
172 a single non-directory file.
174 These programs enable you to find the files in one or more directory
179 have names that contain certain text or match a certain pattern;
181 are links to certain files;
183 were last used during a certain period of time;
185 are within a certain size range;
187 are of a certain type (regular file, directory, symbolic link, etc.);
189 are owned by a certain user or group;
191 have certain access permissions or special mode bits;
193 contain text that matches a certain pattern;
195 are within a certain depth in the directory tree;
197 or some combination of the above.
200 Once you have found the files you're looking for (or files that are
201 potentially the ones you're looking for), you can do more to them than
202 simply list their names. You can get any combination of the files'
203 attributes, or process the files in many ways, either individually or
204 in groups of various sizes. Actions that you might want to perform on
205 the files you have found include, but are not limited to:
215 change access permissions
220 This manual describes how to perform each of those tasks, and more.
225 The principal programs used for making lists of files that match given
226 criteria and running commands on them are @code{find}, @code{locate},
227 and @code{xargs}. An additional command, @code{updatedb}, is used by
228 system administrators to create databases for @code{locate} to use.
230 @code{find} searches for files in a directory hierarchy and prints
231 information about the files it found. It is run like this:
234 find @r{[}@var{file}@dots{}@r{]} @r{[}@var{expression}@r{]}
238 Here is a typical use of @code{find}. This example prints the names
239 of all files in the directory tree rooted in @file{/usr/src} whose
240 name ends with @samp{.c} and that are larger than 100 Kilobytes.
242 find /usr/src -name '*.c' -size +100k -print
245 Notice that the wildcard must be enclosed in quotes in order to
246 protect it from expansion by the shell.
248 @code{locate} searches special file name databases for file names that
249 match patterns. The system administrator runs the @code{updatedb}
250 program to create the databases. @code{locate} is run like this:
253 locate @r{[}@var{option}@dots{}@r{]} @var{pattern}@dots{}
257 This example prints the names of all files in the default file name
258 database whose name ends with @samp{Makefile} or @samp{makefile}.
259 Which file names are stored in the database depends on how the system
260 administrator ran @code{updatedb}.
262 locate '*[Mm]akefile'
265 The name @code{xargs}, pronounced EX-args, means ``combine
266 arguments.'' @code{xargs} builds and executes command lines by
267 gathering together arguments it reads on the standard input. Most
268 often, these arguments are lists of file names generated by
269 @code{find}. @code{xargs} is run like this:
272 xargs @r{[}@var{option}@dots{}@r{]} @r{[}@var{command} @r{[}@var{initial-arguments}@r{]}@r{]}
276 The following command searches the files listed in the file
277 @file{file-list} and prints all of the lines in them that contain the
280 xargs grep typedef < file-list
283 @node find Expressions
284 @section @code{find} Expressions
286 The expression that @code{find} uses to select files consists of one
287 or more @dfn{primaries}, each of which is a separate command line
288 argument to @code{find}. @code{find} evaluates the expression each
289 time it processes a file. An expression can contain any of the
290 following types of primaries:
294 affect overall operation rather than the processing of a specific
297 return a true or false value, depending on the file's attributes;
299 have side effects and return a true or false value; and
301 connect the other arguments and affect when and whether they are
305 You can omit the operator between two primaries; it defaults to
306 @samp{-and}. @xref{Combining Primaries With Operators}, for ways to
307 connect primaries into more complex expressions. If the expression
308 contains no actions other than @samp{-prune}, @samp{-print} is
309 performed on all files for which the entire expression is true
310 (@pxref{Print File Name}).
312 Options take effect immediately, rather than being evaluated for each
313 file when their place in the expression is reached. Therefore, for
314 clarity, it is best to place them at the beginning of the expression.
315 There are two exceptions to this; @samp{-daystart} and @samp{-follow}
316 have different effects depending on where in the command line they
317 appear. This can be confusing, so it's best to keep them at the
320 Many of the primaries take arguments, which immediately follow them in
321 the next command line argument to @code{find}. Some arguments are
322 file names, patterns, or other strings; others are numbers. Numeric
323 arguments can be specified as
327 for greater than @var{n},
329 for less than @var{n},
334 @node Finding Files, Actions, Introduction, Top
335 @chapter Finding Files
337 By default, @code{find} prints to the standard output the names of the
338 files that match the given criteria. @xref{Actions}, for how to get
339 more information about the matching files.
353 * Combining Primaries With Operators::
359 Here are ways to search for files whose name matches a certain
360 pattern. @xref{Shell Pattern Matching}, for a description of the
361 @var{pattern} arguments to these tests.
363 Each of these tests has a case-sensitive version and a
364 case-insensitive version, whose name begins with @samp{i}. In a
365 case-insensitive comparison, the patterns @samp{fo*} and @samp{F??}
366 match the file names @file{Foo}, @samp{FOO}, @samp{foo}, @samp{fOo},
370 * Base Name Patterns::
371 * Full Name Patterns::
372 * Fast Full Name Search::
373 * Shell Pattern Matching:: Wildcards used by these programs.
376 @node Base Name Patterns
377 @subsection Base Name Patterns
379 @deffn Test -name pattern
380 @deffnx Test -iname pattern
381 True if the base of the file name (the path with the leading
382 directories removed) matches shell pattern @var{pattern}. For
383 @samp{-iname}, the match is case-insensitive.@footnote{Because we
384 need to perform case-insensitive matching, the GNU fnmatch
385 implementation is always used; if the C library includes the GNU
386 implementation, we use that and otherwise we use the one from gnulib}
387 To ignore a whole directory tree, use @samp{-prune}
388 (@pxref{Directories}). As an example, to find Texinfo source files in
389 @file{/usr/local/doc}:
392 find /usr/local/doc -name '*.texi'
395 Notice that the wildcard must be enclosed in quotes in order to
396 protect it from expansion by the shell.
398 As of findutils version 4.2.2, patterns for @samp{-name} and
399 @samp{-iname} will match a file name with a leading @samp{.}. For
400 example the command @samp{find /tmp -name \*bar} will match the file
401 @file{/tmp/.foobar}. Braces within the pattern (@samp{@{@}}) are not
402 considered to be special (that is, @code{find . -name 'foo@{1,2@}'}
403 matches a file named @file{foo@{1,2@}}, not the files @file{foo1} and
408 @node Full Name Patterns
409 @subsection Full Name Patterns
411 @deffn Test -wholename pattern
412 @deffnx Test -iwholename pattern
413 True if the entire file name, starting with the command line argument
414 under which the file was found, matches shell pattern @var{pattern}.
415 For @samp{-iwholename}, the match is case-insensitive. To ignore a
416 whole directory tree, use @samp{-prune} rather than checking every
417 file in the tree (@pxref{Directories}). The ``entire file name'' as
418 used by @code{find} starts with the starting-point specified on the
419 command line, and is not converted to an absolute pathname, so for
420 example @code{cd /; find tmp -wholename /tmp} will never match
424 @deffn Test -path pattern
425 @deffnx Test -ipath pattern
426 These tests are deprecated, but work as for @samp{-wholename} and
427 @samp{-iwholename}, respectively. The @samp{-ipath} test is a GNU
428 extension, but @samp{-path} is also provided by HP-UX @code{find}.
431 @deffn Test -regex expr
432 @deffnx Test -iregex expr
433 True if the entire file name matches regular expression @var{expr}.
434 This is a match on the whole path, not a search. For example, to
435 match a file named @file{./fubar3}, you can use the regular expression
436 @samp{.*bar.} or @samp{.*b.*3}, but not @samp{f.*r3}. @xref{Regexps,
437 , Syntax of Regular Expressions, emacs, The GNU Emacs Manual}, for a
438 description of the syntax of regular expressions. For @samp{-iregex},
439 the match is case-insensitive. There are several varieties of regular
440 expressions; by default this test uses POSIX basic regular
441 expressions, but this can be changed with the option
445 @deffn Option -regextype name
446 This option controls the variety of regular expression syntax
447 understood by the @samp{-regex} and @samp{-iregex} tests. This option
448 is positional; that is, it only affects regular expressions which
449 occur later in the command line. If this option is not given, GNU
450 Emacs regular expressions are assumed. Currently-implemented types
456 Regular expressions compatible with GNU Emacs; this is also the
457 default behaviour if this option is not used.
459 Regular expressions compatible with the POSIX awk command (not GNU awk)
461 POSIX Basic Regular Expressions.
463 Regular expressions compatible with the POSIX egrep command
465 POSIX Extended Regular Expressions
468 @ref{Regular Expressions} for more information on the regular
469 expression dialects understood by GNU findutils.
474 @node Fast Full Name Search
475 @subsection Fast Full Name Search
477 To search for files by name without having to actually scan the
478 directories on the disk (which can be slow), you can use the
479 @code{locate} program. For each shell pattern you give it,
480 @code{locate} searches one or more databases of file names and
481 displays the file names that contain the pattern. @xref{Shell Pattern
482 Matching}, for details about shell patterns.
484 If a pattern is a plain string---it contains no
485 metacharacters---@code{locate} displays all file names in the database
486 that contain that string. If a pattern contains
487 metacharacters, @code{locate} only displays file names that match the
488 pattern exactly. As a result, patterns that contain metacharacters
489 should usually begin with a @samp{*}, and will most often end with one
490 as well. The exceptions are patterns that are intended to explicitly
491 match the beginning or end of a file name.
493 If you only want @code{locate} to match against the last component of
494 the file names (the ``base name'' of the files) you can use the
495 @samp{--basename} option. The opposite behaviour is the default, but
496 can be selected explicitly by using the option @samp{--wholename}.
503 is almost equivalent to
505 find @var{directories} -name @var{pattern}
508 where @var{directories} are the directories for which the file name
509 databases contain information. The differences are that the
510 @code{locate} information might be out of date, and that @code{locate}
511 handles wildcards in the pattern slightly differently than @code{find}
512 (@pxref{Shell Pattern Matching}).
514 The file name databases contain lists of files that were on the system
515 when the databases were last updated. The system administrator can
516 choose the file name of the default database, the frequency with which
517 the databases are updated, and the directories for which they contain
520 Here is how to select which file name databases @code{locate}
521 searches. The default is system-dependent.
524 @item --database=@var{path}
526 Instead of searching the default file name database, search the file
527 name databases in @var{path}, which is a colon-separated list of
528 database file names. You can also use the environment variable
529 @code{LOCATE_PATH} to set the list of database files to search. The
530 option overrides the environment variable if both are used.
533 @node Shell Pattern Matching
534 @subsection Shell Pattern Matching
536 @code{find} and @code{locate} can compare file names, or parts of file
537 names, to shell patterns. A @dfn{shell pattern} is a string that may
538 contain the following special characters, which are known as
539 @dfn{wildcards} or @dfn{metacharacters}.
541 You must quote patterns that contain metacharacters to prevent the
542 shell from expanding them itself. Double and single quotes both work;
543 so does escaping with a backslash.
547 Matches any zero or more characters.
550 Matches any one character.
553 Matches exactly one character that is a member of the string
554 @var{string}. This is called a @dfn{character class}. As a
555 shorthand, @var{string} may contain ranges, which consist of two
556 characters with a dash between them. For example, the class
557 @samp{[a-z0-9_]} matches a lowercase letter, a number, or an
558 underscore. You can negate a class by placing a @samp{!} or @samp{^}
559 immediately after the opening bracket. Thus, @samp{[^A-Z@@]} matches
560 any character except an uppercase letter or an at sign.
563 Removes the special meaning of the character that follows it. This
564 works even in character classes.
567 In the @code{find} tests that do shell pattern matching (@samp{-name},
568 @samp{-wholename}, etc.), wildcards in the pattern will match a
569 @samp{.} at the beginning of a file name. This is also the case for
570 @code{locate}. Thus, @samp{find -name '*macs'} will match a file
571 named @file{.emacs}, as will @samp{locate '*macs'}.
573 Slash characters have no special significance in the shell pattern
574 matching that @code{find} and @code{locate} do, unlike in the shell,
575 in which wildcards do not match them. Therefore, a pattern
576 @samp{foo*bar} can match a file name @samp{foo3/bar}, and a pattern
577 @samp{./sr*sc} can match a file name @samp{./src/misc}.
579 If you want to locate some files with the @samp{locate} command but
580 don't need to see the full list you can use the @samp{--limit} option
581 to see just a small number of results, or the @samp{--count} option to
582 display only the total number of matches.
587 There are two ways that files can be linked together. @dfn{Symbolic
588 links} are a special type of file whose contents are a portion of the
589 name of another file. @dfn{Hard links} are multiple directory entries
590 for one file; the file names all have the same index node
591 (@dfn{inode}) number on the disk.
599 @subsection Symbolic Links
601 Symbolic links are names that reference other files. GNU @code{find}
602 will handle symbolic links in one of two ways; firstly, it can
603 dereference the links for you - this means that if it comes across a
604 symbolic link, it examines the file that the link points to, in order
605 to see if it matches the criteria you have specified. Secondly, it
606 can check the link itself in case you might be looking for the actual
607 link. If the file that the symbolic link points to is also within the
608 directory hierarchy you are searching with the @code{find} command,
609 you may not see a great deal of difference between these two
612 By default, @code{find} examines symbolic links themselves when it
613 finds them (and, if it later comes across the linked-to file, it will
614 examine that, too). If you would prefer @code{find} to dereference
615 the links and examine the file that each link points to, specify the
616 @samp{-L} option to @code{find}. You can explicitly specify the
617 default behaviour by using the @samp{-P} option. The @samp{-H}
618 option is a half-way-between option which ensures that any symbolic
619 links listed on the command line are dereferenced, but other symbolic
622 Symbolic links are different to ``hard links'' in the sense that you
623 need permission to search the directories
624 in the linked-to file name to
625 dereference the link. This can mean that even if you specify the
626 @samp{-L} option, @code{find} may not be able to determine the
627 properties of the file that the link points to (because you don't have
628 sufficient permission). In this situation, @code{find} uses the
629 properties of the link itself. This also occurs if a symbolic link
630 exists but points to a file that is missing.
632 The options controlling the behaviour of @code{find} with respect to
633 links are as follows :-
637 @code{find} does not dereference symbolic links at all. This is the
638 default behaviour. This option must be specified before any of the
639 file names on the command line.
641 @code{find} does not dereference symbolic links (except in the case of
642 file names on the command line, which are dereferenced). If a
643 symbolic link cannot be dereferenced, the information for the symbolic
644 link itself is used. This option must be specified before any of the
645 file names on the command line.
647 @code{find} dereferences symbolic links where possible, and where this
648 is not possible it uses the properties of the symbolic link itself.
649 This option must be specified before any of the file names on the
650 command line. Use of this option also implies the same behaviour as
651 the @samp{-noleaf} option. If you later use the @samp{-H} or
652 @samp{-P} options, this does not turn off @samp{-noleaf}.
655 This option forms part of the ``expression'' and must be specified
656 after the file names, but it is otherwise equivalent to @samp{-L}.
657 The @samp{-follow} option affects only those tests which appear after
658 it on the command line. This option is deprecated. Where possible,
659 you should use @samp{-L} instead.
662 The following differences in behavior occur when the @samp{-L} option
667 @code{find} follows symbolic links to directories when searching
670 @samp{-lname} and @samp{-ilname} always return false (unless they
671 happen to match broken symbolic links).
673 @samp{-type} reports the types of the files that symbolic links point
674 to. This means that in combination with @samp{-L}, @samp{-type l}
675 will be true only for broken symbolic links. To check for symbolic
676 links when @samp{-L} has been specified, use @samp{-xtype l}.
678 Implies @samp{-noleaf} (@pxref{Directories}).
681 If the @samp{-L} option or the @samp{-H} option is used,
682 the file names used as arguments to @samp{-newer}, @samp{-anewer}, and
683 @samp{-cnewer} are dereferenced and the timestamp from the pointed-to
684 file is used instead (if possible -- otherwise the timestamp from the
685 symbolic link is used).
687 @deffn Test -lname pattern
688 @deffnx Test -ilname pattern
689 True if the file is a symbolic link whose contents match shell pattern
690 @var{pattern}. For @samp{-ilname}, the match is case-insensitive.
691 @xref{Shell Pattern Matching}, for details about the @var{pattern}
692 argument. If the @samp{-L} option is in effect, this test will always
693 return false for symbolic links unless they are broken. So, to list
694 any symbolic links to @file{sysdep.c} in the current directory and its
695 subdirectories, you can do:
698 find . -lname '*sysdep.c'
703 @subsection Hard Links
705 Hard links allow more than one name to refer to the same file. To
706 find all the names which refer to the same file as NAME, use
707 @samp{-samefile NAME}. If you are not using the @samp{-L} option, you
708 can confine your search to one filesystem using the @samp{-xdev}
709 option. This is useful because hard links cannot point outside a
710 single filesystem, so this can cut down on needless searching.
712 If the @samp{-L} option is in effect, and NAME is in fact a symbolic
713 link, the symbolic link will be dereferenced. Hence you are searching
714 for other links (hard or symbolic) to the file pointed to by NAME. If
715 @samp{-L} is in effect but NAME is not itself a symbolic link, other
716 symbolic links to the file NAME will be matched.
718 You can also search for files by inode number. This can occasionally
719 be useful in diagnosing problems with filesystems for example, because
720 @code{fsck} tends to print inode numbers. Inode numbers also
721 occasionally turn up in log messages for some types of software, and
722 are used to support the @code{ftok()} library function.
724 You can learn a file's inode number and the number of links to it by
725 running @samp{ls -li} or @samp{find -ls}.
727 You can search for hard links to inode number NUM by using @samp{-inum
728 NUM}. If there are any filesystem mount points below the directory
729 where you are starting the search, use the @samp{-xdev} option unless
730 you are also using the @samp{-L} option. Using @samp{-xdev} this
731 saves needless searching, since hard links to a file must be on the
732 same filesystem. @xref{Filesystems}.
734 @deffn Test -samefile NAME
735 File is a hard link to the same inode as NAME. If the @samp{-L}
736 option is in effect, symbolic links to the same file as NAME points to
741 File has inode number @var{n}. The @samp{+} and @samp{-} qualifiers
742 also work, though these are rarely useful. Much of the time it is
743 easier to use @samp{-samefile} rather than this option.
746 You can also search for files that have a certain number of links,
747 with @samp{-links}. Directories normally have at least two hard
748 links; their @file{.} entry is the second one. If they have
749 subdirectories, each of those also has a hard link called @file{..} to
750 its parent directory. The @file{.} and @file{..} directory entries
751 are not normally searched unless they are mentioned on the @code{find}
755 File has @var{n} hard links.
758 @deffn Test -links +n
759 File has more than @var{n} hard links.
762 @deffn Test -links -n
763 File has fewer than @var{n} hard links.
769 Each file has three time stamps, which record the last time that
770 certain operations were performed on the file:
774 access (read the file's contents)
776 change the status (modify the file or its attributes)
778 modify (change the file's contents)
781 There is no timestamp that indicates when a file was @emph{created}.
783 You can search for files whose time stamps are within a certain age
784 range, or compare them to other time stamps.
788 * Comparing Timestamps::
792 @subsection Age Ranges
794 These tests are mainly useful with ranges (@samp{+@var{n}} and
798 @deffnx Test -ctime n
799 @deffnx Test -mtime n
800 True if the file was last accessed (or its status changed, or it was
801 modified) @var{n}*24 hours ago. The number of 24-hour periods since
802 the file's timestamp is always rounded down; therefore 0 means ``less
803 than 24 hours ago'', 1 means ``between 24 and 48 hours ago'', and so
804 forth. Fractional values are supported but this only really makes
805 sense for the case where ranges (@samp{+@var{n}} and @samp{-@var{n}})
812 True if the file was last accessed (or its status changed, or it was
813 modified) @var{n} minutes ago. These tests provide finer granularity
814 of measurement than @samp{-atime} et al., but rounding is done in a
815 similar way (again, fractions are supported). For example, to list
816 files in @file{/u/bill} that were last read from 2 to 6 minutes ago:
819 find /u/bill -amin +2 -amin -6
823 @deffn Option -daystart
824 Measure times from the beginning of today rather than from 24 hours
825 ago. So, to list the regular files in your home directory that were
826 modified yesterday, do
829 find ~ -daystart -type f -mtime 1
832 The @samp{-daystart} option is unlike most other options in that it
833 has an effect on the way that other tests are performed. The affected
834 tests are @samp{-amin}, @samp{-cmin}, @samp{-mmin}, @samp{-atime},
835 @samp{-ctime} and @samp{-mtime}. The @samp{-daystart} option only
836 affects the behaviour of any tests which appear after it on the
840 @node Comparing Timestamps
841 @subsection Comparing Timestamps
843 As an alternative to comparing timestamps to the current time, you can
844 compare them to another file's timestamp. That file's timestamp could
845 be updated by another program when some event occurs. Or you could
846 set it to a particular fixed date using the @code{touch} command. For
847 example, to list files in @file{/usr} modified after February 1 of the
850 @c Idea from Rick Sladkey.
852 touch -t 02010000 /tmp/stamp$$
853 find /usr -newer /tmp/stamp$$
857 @deffn Test -anewer file
858 @deffnx Test -cnewer file
859 @deffnx Test -newer file
860 True if the file was last accessed (or its status changed, or it was
861 modified) more recently than @var{file} was modified. These tests are
862 affected by @samp{-follow} only if @samp{-follow} comes before them on
863 the command line. @xref{Symbolic Links}, for more information on
864 @samp{-follow}. As an example, to list any files modified since
865 @file{/bin/sh} was last modified:
868 find . -newer /bin/sh
873 True if the file was last accessed @var{n} days after its status was
874 last changed. Useful for finding files that are not being used, and
875 could perhaps be archived or removed to save disk space.
881 @deffn Test -size n@r{[}bckwMG@r{]}
882 True if the file uses @var{n} units of space, rounding up. The units
883 are 512-byte blocks by default, but they can be changed by adding a
884 one-character suffix to @var{n}:
888 512-byte blocks (never 1024)
892 kilobytes (1024 bytes)
896 Megabytes (units of 1048576 bytes)
898 Gigabytes (units of 1073741824 bytes)
901 The `b' suffix always considers blocks to be 512 bytes. This is not
902 affected by the setting (or non-setting) of the POSIXLY_CORRECT
903 environment variable. This behaviour is different to the behaviour of
904 the @samp{-ls} action). If you want to use 1024-byte units, use the
907 The number can be prefixed with a `+' or a `-'. A plus sign indicates
908 that the test should succeed if the file uses at least @var{n} units
909 of storage (a common use of this test) and a minus sign
910 indicates that the test should succeed if the file uses less than
911 @var{n} units of storage. There is no `=' prefix, because that's the
914 The size does not count indirect blocks, but it does count blocks in
915 sparse files that are not actually allocated. In other words, it's
916 consistent with the result you get for @samp{ls -l} or @samp{wc -c}.
917 This handling of sparse files differs from the output of the @samp{%k}
918 and @samp{%b} format specifiers for the @samp{-printf} predicate.
923 True if the file is empty and is either a regular file or a directory.
924 This might help determine good candidates for deletion. This test is
925 useful with @samp{-depth} (@pxref{Directories}) and @samp{-delete}
926 (@pxref{Single File}).
933 True if the file is of type @var{c}:
937 block (buffered) special
939 character (unbuffered) special
947 symbolic link; if @samp{-L} is in effect, this is true only for broken
948 symbolic links. If you want to search for symbolic links when
949 @samp{-L} is in effect, use @samp{-xtype} instead of @samp{-type}.
958 This test behaves the same as @samp{-type} unless the file is a
959 symbolic link. If the file is a symbolic link, the result is as
960 follows (in the table below, @samp{X} should be understood to
961 represent any letter except @samp{l}):
964 @item @samp{-P -xtype l}
965 True if the symbolic link is broken
966 @item @samp{-P -xtype X}
967 True if the (ultimate) target file is of type @samp{X}.
968 @item @samp{-L -xtype l}
970 @item @samp{-L -xtype X}
971 False unless the symbolic link is broken
974 In other words, for symbolic links, @samp{-xtype} checks the type of
975 the file that @samp{-type} does not check.
977 The @samp{-H} option also affects the behaviour of @samp{-xtype}.
978 When @samp{-H} is in effect, @samp{-xtype} behaves as if @samp{-L} had
979 been specified when examining files listed on the command line, and as
980 if @samp{-P} had been specified otherwise. If neither @samp{-H} nor
981 @samp{-L} was specified, @samp{-xtype} behaves as if @samp{-P} had
984 @xref{Symbolic Links}, for more information on @samp{-follow} and
991 @deffn Test -user uname
992 @deffnx Test -group gname
993 True if the file is owned by user @var{uname} (belongs to group
994 @var{gname}). A numeric ID is allowed.
999 True if the file's numeric user ID (group ID) is @var{n}. These tests
1000 support ranges (@samp{+@var{n}} and @samp{-@var{n}}), unlike
1001 @samp{-user} and @samp{-group}.
1005 @deffnx Test -nogroup
1006 True if no user corresponds to the file's numeric user ID (no group
1007 corresponds to the numeric group ID). These cases usually mean that
1008 the files belonged to users who have since been removed from the
1009 system. You probably should change the ownership of such files to an
1010 existing user or group, using the @code{chown} or @code{chgrp}
1015 @section File Mode Bits
1017 @xref{File Permissions}, for information on how file mode bits are
1018 structured and how to specify them.
1020 Four tests determine what users can do with files. These are
1021 @samp{-readable}, @samp{-writable}, @samp{-executable} and
1022 @samp{-perm}. The first three tests ask the operating system if the
1023 current user can perform the relevant operation on a file, while
1024 @samp{-perm} just examines the file's mode. The file mode may give
1025 a misleading impression of what the user can actually do, because the
1026 file may have an access control list, or exist on a read-only
1027 filesystem, for example. Of these four tests though, only
1028 @samp{-perm} is specified by the POSIX standard.
1030 The @samp{-readable}, @samp{-writable} and @samp{-executable} tests
1031 are implemented via the @code{access} system call. This is
1032 implemented within the operating system itself. If the file being
1033 considered is on an NFS filesystem, the remote system may allow or
1034 forbid read or write operations for reasons of which the NFS client
1035 cannot take account. This includes user-ID mapping, either in the
1036 general sense or the more restricted sense in which remote superusers
1037 are treated by the NFS server as if they are the local user
1038 @samp{nobody} on the NFS server.
1040 None of the tests in this section should be used to verify that a user
1041 is authorised to perform any operation (on the file being tested or
1042 any other file) because of the possibility of a race condition. That
1043 is, the situation may change between the test and an action being
1044 taken on the basis of the result of that test.
1047 @deffn Test -readable
1048 True if the file can be read by the invoking user.
1051 @deffn Test -writable
1052 True if the file can be written by the invoking user. This is an
1053 in-principle check, and other things may prevent a successful write
1054 operation; for example, the filesystem might be full.
1057 @deffn Test -executable
1058 True if the file can be executed/searched by the invoking user.
1061 @deffn Test -perm pmode
1063 True if the file's mode bits match @var{pmode}, which can be
1064 either a symbolic or numeric @var{mode} (@pxref{File Permissions})
1065 optionally prefixed by @samp{-} or @samp{/}.
1067 A @var{pmode} that starts with neither @samp{-} nor @samp{/} matches
1068 if @var{mode} exactly matches the file mode bits.
1070 A @var{pmode} that starts with @samp{-} matches if
1071 @emph{all} the file mode bits set in @var{mode} are set for the file;
1072 bits not set in @var{mode} are ignored.
1074 A @var{pmode} that starts with @samp{/} matches if
1075 @emph{any} of the file mode bits set in @var{mode} are set for the file;
1076 bits not set in @var{mode} are ignored.
1077 This is a GNU extension.
1079 If you don't use the @samp{/} or @samp{-} form with a symbolic mode
1080 string, you may have to specify a rather complex mode string. For
1081 example @samp{-perm g=w} will only match files that have mode 0020
1082 (that is, ones for which group write permission is the only file mode bit
1083 set). It is more likely that you will want to use the @samp{/} or
1084 @samp{-} forms, for example @samp{-perm -g=w}, which matches any file
1085 with group write permission.
1090 Match files that have read and write permission for their owner,
1091 and group, but that the rest of the world can read but not write to.
1092 Do not match files that meet these criteria but have other file mode
1093 bits set (for example if someone can execute/search the file).
1096 Match files that have read and write permission for their owner,
1097 and group, but that the rest of the world can read but not write to,
1098 without regard to the presence of any extra file mode bits (for
1099 example the executable bit). This matches a file with mode
1103 Match files that are writable by somebody (their owner, or
1104 their group, or anybody else).
1107 Match files that are writable by either their owner or their
1108 group. The files don't have to be writable by both the owner and
1109 group to be matched; either will do.
1111 @item -perm /g+w,o+w
1114 @item -perm /g=w,o=w
1118 Match files that are writable by both their owner and their
1121 @item -perm -444 -perm /222 ! -perm /111
1122 Match files that are readable for everybody, have at least one
1123 write bit set (i.e., somebody can write to them), but that cannot be
1124 executed/searched by anybody. Note that in some shells the @samp{!} must be
1127 @item -perm -a+r -perm /a+w ! -perm /a+x
1131 @item -perm -g+w,o+w
1136 If you specify @samp{-perm /000} or @samp{-perm /mode} where the
1137 symbolic mode @samp{mode} has no bits set, the test currently matches
1138 no files. This differs from the behaviour of @samp{-perm -000}, which
1139 matches all files. The behaviour of @samp{-perm /000} will be changed
1140 to be consistent with the behaviour of @samp{-perm -000}. The change
1141 will probably be made in early 2006.
1149 To search for files based on their contents, you can use the
1150 @code{grep} program. For example, to find out which C source files in
1151 the current directory contain the string @samp{thing}, you can do:
1154 grep -l thing *.[ch]
1157 If you also want to search for the string in files in subdirectories,
1158 you can combine @code{grep} with @code{find} and @code{xargs}, like
1162 find . -name '*.[ch]' | xargs grep -l thing
1165 The @samp{-l} option causes @code{grep} to print only the names of
1166 files that contain the string, rather than the lines that contain it.
1167 The string argument (@samp{thing}) is actually a regular expression,
1168 so it can contain metacharacters. This method can be refined a little
1169 by using the @samp{-r} option to make @code{xargs} not run @code{grep}
1170 if @code{find} produces no output, and using the @code{find} action
1171 @samp{-print0} and the @code{xargs} option @samp{-0} to avoid
1172 misinterpreting files whose names contain spaces:
1175 find . -name '*.[ch]' -print0 | xargs -r -0 grep -l thing
1178 For a fuller treatment of finding files whose contents match a
1179 pattern, see the manual page for @code{grep}.
1182 @section Directories
1184 Here is how to control which directories @code{find} searches, and how
1185 it searches them. These two options allow you to process a horizontal
1186 slice of a directory tree.
1188 @deffn Option -maxdepth levels
1189 Descend at most @var{levels} (a non-negative integer) levels of
1190 directories below the command line arguments. @samp{-maxdepth 0}
1191 means only apply the tests and actions to the command line arguments.
1194 @deffn Option -mindepth levels
1195 Do not apply any tests or actions at levels less than @var{levels} (a
1196 non-negative integer). @samp{-mindepth 1} means process all files
1197 except the command line arguments.
1200 @deffn Option -depth
1201 Process each directory's contents before the directory itself. Doing
1202 this is a good idea when producing lists of files to archive with
1203 @code{cpio} or @code{tar}. If a directory does not have write
1204 permission for its owner, its contents can still be restored from the
1205 archive since the directory's permissions are restored after its
1210 This is a deprecated synonym for @samp{-depth}, for compatibility with
1211 Mac OS X, FreeBSD and OpenBSD. The @samp{-depth} option is a POSIX
1212 feature, so it is better to use that.
1215 @deffn Action -prune
1216 If the file is a directory, do not descend into it. The result is
1217 true. For example, to skip the directory @file{src/emacs} and all
1218 files and directories under it, and print the names of the other files
1222 find . -wholename './src/emacs' -prune -o -print
1225 The above command will not print @file{./src/emacs} among its list of
1226 results. This however is not due to the effect of the @samp{-prune}
1227 action (which only prevents further descent, it doesn't make sure we
1228 ignore that item). Instead, this effect is due to the use of
1229 @samp{-o}. Since the left hand side of the ``or'' condition has
1230 succeeded for @file{./src/emacs}, it is not necessary to evaluate the
1231 right-hand-side (@samp{-print}) at all for this particular file. If
1232 you wanted to print that directory name you could use either an extra
1233 @samp{-print} action:
1236 find . -wholename './src/emacs' -prune -print -o -print
1239 or use the comma operator:
1242 find . -wholename './src/emacs' -prune , -print
1245 If the @samp{-depth} option is in effect, the subdirectories will have
1246 already been visited in any case. Hence @samp{-prune} has no effect
1252 Exit immediately (with return value zero if no errors have occurred).
1253 No child processes will be left running, but no more files specified
1254 on the command line will be processed. For example, @code{find
1255 /tmp/foo /tmp/bar -print -quit} will print only @samp{/tmp/foo}. Any
1256 command lines which have been built by @samp{-exec ... \+} or
1257 @samp{-execdir ... \+} are invoked before the program is executed.
1260 @deffn Option -noleaf
1261 Do not optimize by assuming that directories contain 2 fewer
1262 subdirectories than their hard link count. This option is needed when
1263 searching filesystems that do not follow the Unix directory-link
1264 convention, such as CD-ROM or MS-DOS filesystems or AFS volume mount
1265 points. Each directory on a normal Unix filesystem has at least 2
1266 hard links: its name and its @file{.} entry. Additionally, its
1267 subdirectories (if any) each have a @file{..} entry linked to that
1268 directory. When @code{find} is examining a directory, after it has
1269 statted 2 fewer subdirectories than the directory's link count, it
1270 knows that the rest of the entries in the directory are
1271 non-directories (@dfn{leaf} files in the directory tree). If only the
1272 files' names need to be examined, there is no need to stat them; this
1273 gives a significant increase in search speed.
1276 @deffn Option -ignore_readdir_race
1277 If a file disappears after its name has been read from a directory but
1278 before @code{find} gets around to examining the file with @code{stat},
1279 don't issue an error message. If you don't specify this option, an
1280 error message will be issued. This option can be useful in system
1281 scripts (cron scripts, for example) that examine areas of the
1282 filesystem that change frequently (mail queues, temporary directories,
1283 and so forth), because this scenario is common for those sorts of
1284 directories. Completely silencing error messages from @code{find} is
1285 undesirable, so this option neatly solves the problem. There is no
1286 way to search one part of the filesystem with this option on and part
1287 of it with this option off, though. When this option is turned on and
1288 find discovers that one of the start-point files specified on the
1289 command line does not exist, no error message will be issued.
1293 @deffn Option -noignore_readdir_race
1294 This option reverses the effect of the @samp{-ignore_readdir_race}
1300 @section Filesystems
1302 A @dfn{filesystem} is a section of a disk, either on the local host or
1303 mounted from a remote host over a network. Searching network
1304 filesystems can be slow, so it is common to make @code{find} avoid
1307 There are two ways to avoid searching certain filesystems. One way is
1308 to tell @code{find} to only search one filesystem:
1311 @deffnx Option -mount
1312 Don't descend directories on other filesystems. These options are
1316 The other way is to check the type of filesystem each file is on, and
1317 not descend directories that are on undesirable filesystem types:
1319 @deffn Test -fstype type
1320 True if the file is on a filesystem of type @var{type}. The valid
1321 filesystem types vary among different versions of Unix; an incomplete
1322 list of filesystem types that are accepted on some version of Unix or
1325 ext2 ext3 proc sysfs ufs 4.2 4.3 nfs tmp mfs S51K S52K
1327 You can use @samp{-printf} with the @samp{%F} directive to see the
1328 types of your filesystems. The @samp{%D} directive shows the device
1329 number. @xref{Print File Information}. @samp{-fstype} is usually
1330 used with @samp{-prune} to avoid searching remote filesystems
1331 (@pxref{Directories}).
1334 @node Combining Primaries With Operators
1335 @section Combining Primaries With Operators
1337 Operators build a complex expression from tests and actions.
1338 The operators are, in order of decreasing precedence:
1341 @item @asis{( @var{expr} )}
1343 Force precedence. True if @var{expr} is true.
1345 @item @asis{! @var{expr}}
1346 @itemx @asis{-not @var{expr}}
1349 True if @var{expr} is false. In some shells, it is necessary to
1350 protect the @samp{!} from shell interpretation by quoting it.
1352 @item @asis{@var{expr1 expr2}}
1353 @itemx @asis{@var{expr1} -a @var{expr2}}
1354 @itemx @asis{@var{expr1} -and @var{expr2}}
1357 And; @var{expr2} is not evaluated if @var{expr1} is false.
1359 @item @asis{@var{expr1} -o @var{expr2}}
1360 @itemx @asis{@var{expr1} -or @var{expr2}}
1363 Or; @var{expr2} is not evaluated if @var{expr1} is true.
1365 @item @asis{@var{expr1} , @var{expr2}}
1367 List; both @var{expr1} and @var{expr2} are always evaluated. True if
1368 @var{expr2} is true. The value of @var{expr1} is discarded. This
1369 operator lets you do multiple independent operations on one traversal,
1370 without depending on whether other operations succeeded. The two
1371 operations @var{expr1} and @var{expr2} are not always fully
1372 independent, since @var{expr1} might have side effects like touching
1373 or deleting files, or it might use @samp{-prune} which would also
1377 @code{find} searches the directory tree rooted at each file name by
1378 evaluating the expression from left to right, according to the rules
1379 of precedence, until the outcome is known (the left hand side is false
1380 for @samp{-and}, true for @samp{-or}), at which point @code{find}
1381 moves on to the next file name.
1383 There are two other tests that can be useful in complex expressions:
1393 @node Actions, Databases, Finding Files, Top
1396 There are several ways you can print information about the files that
1397 match the criteria you gave in the @code{find} expression. You can
1398 print the information either to the standard output or to a file that
1399 you name. You can also execute commands that have the file names as
1400 arguments. You can use those commands as further filters to select
1405 * Print File Information::
1411 @node Print File Name
1412 @section Print File Name
1414 @deffn Action -print
1415 True; print the entire file name on the standard output, followed by a
1416 newline. If there is the faintest possibility that one of the files
1417 for which you are searching might contain a newline, you should use
1418 @samp{-print0} instead.
1421 @deffn Action -fprint file
1422 True; print the entire file name into file @var{file}, followed by a
1423 newline. If @var{file} does not exist when @code{find} is run, it is
1424 created; if it does exist, it is truncated to 0 bytes. The named
1425 output file is always created, even if no output is sent to it. The
1426 file names @file{/dev/stdout} and @file{/dev/stderr} are handled
1427 specially; they refer to the standard output and standard error
1428 output, respectively.
1430 If there is the faintest possibility that one of the files for which
1431 you are searching might contain a newline, you should use
1432 @samp{-fprint0} instead.
1436 @c @deffn Option -show-control-chars how
1437 @c This option affects how some of @code{find}'s actions treat
1438 @c unprintable characters in file names. If @samp{how} is
1439 @c @samp{literal}, any subsequent actions (i.e., actions further on in the
1440 @c command line) print file names as-is.
1442 @c If this option is not specified, it currently defaults to @samp{safe}.
1443 @c If @samp{how} is @samp{safe}, C-like backslash escapes are used to
1444 @c indicate the non-printable characters for @samp{-ls} and @samp{-fls}.
1445 @c On the other hand, @samp{-print}, @samp{-fprint}, @samp{-fprintf} and
1446 @c @code{-printf} all quote unprintable characters if the data is going
1447 @c to a tty, and otherwise the data is emitted literally.
1451 @c Escaped if @samp{how} is @samp{safe}
1453 @c Escaped if @samp{how} is @samp{safe}
1455 @c Always quoted if stdout is a tty,
1456 @c @samp{-show-control-chars} is ignored
1458 @c Always literal, never escaped
1460 @c Always quoted if the destination is a tty;
1461 @c @samp{-show-control-chars} is ignored
1463 @c Always literal, never escaped
1465 @c If the destination is a tty, the @samp{%f},
1466 @c @samp{%F}, @samp{%h}, @samp{%l}, @samp{%p},
1467 @c and @samp{%P} directives produce quoted
1468 @c strings if stdout is a tty and are treated
1469 @c literally otherwise.
1471 @c As for @code{-fprintf}.
1476 @node Print File Information
1477 @section Print File Information
1480 True; list the current file in @samp{ls -dils} format on the standard
1481 output. The output looks like this:
1484 204744 17 -rw-r--r-- 1 djm staff 17337 Nov 2 1992 ./lwall-quotes
1491 The inode number of the file. @xref{Hard Links}, for how to find
1492 files based on their inode number.
1495 the number of blocks in the file. The block counts are of 1K blocks,
1496 unless the environment variable @code{POSIXLY_CORRECT} is set, in
1497 which case 512-byte blocks are used. @xref{Size}, for how to find
1498 files based on their size.
1501 The file's type and file mode bits. The type is shown as a dash for a
1502 regular file; for other file types, a letter like for @samp{-type} is
1503 used (@pxref{Type}). The file mode bits are read, write, and execute/search for
1504 the file's owner, its group, and other users, respectively; a dash
1505 means the permission is not granted. @xref{File Permissions}, for
1506 more details about file permissions. @xref{Mode Bits}, for how to
1507 find files based on their file mode bits.
1510 The number of hard links to the file.
1513 The user who owns the file.
1519 The file's size in bytes.
1522 The date the file was last modified.
1525 The file's name. @samp{-ls} quotes non-printable characters in the
1526 file names using C-like backslash escapes. This may change soon, as
1527 the treatment of unprintable characters is harmonised for @samp{-ls},
1528 @samp{-fls}, @samp{-print}, @samp{-fprint}, @samp{-printf} and
1533 @deffn Action -fls file
1534 True; like @samp{-ls} but write to @var{file} like @samp{-fprint}
1535 (@pxref{Print File Name}). The named output file is always created,
1536 even if no output is sent to it.
1539 @deffn Action -printf format
1540 True; print @var{format} on the standard output, interpreting @samp{\}
1541 escapes and @samp{%} directives. Field widths and precisions can be
1542 specified as with the @code{printf} C function. Format flags (like
1543 @samp{#} for example) may not work as you expect because many of the
1544 fields, even numeric ones, are printed with %s. Numeric flags which
1545 are affected in this way include G, U, b, D, k and n. This difference
1546 in behaviour means though that the format flag @samp{-} will work; it
1547 forces left-alignment of the field. Unlike @samp{-print},
1548 @samp{-printf} does not add a newline at the end of the string. If
1549 you want a newline at the end of the string, add a @samp{\n}.
1552 @deffn Action -fprintf file format
1553 True; like @samp{-printf} but write to @var{file} like @samp{-fprint}
1554 (@pxref{Print File Name}). The output file is always created, even if
1555 no output is ever sent to it.
1560 * Format Directives::
1567 The escapes that @samp{-printf} and @samp{-fprintf} recognise are:
1575 Stop printing from this format immediately and flush the output.
1587 A literal backslash (@samp{\}).
1591 The character whose ASCII code is NNN (octal).
1594 A @samp{\} character followed by any other character is treated as an
1595 ordinary character, so they both are printed, and a warning message is
1596 printed to the standard error output (because it was probably a typo).
1598 @node Format Directives
1599 @subsection Format Directives
1601 @samp{-printf} and @samp{-fprintf} support the following format
1602 directives to print information about the file being processed. The C
1603 @code{printf} function, field width and precision specifiers are
1604 supported, as applied to string (%s) types. That is, you can specify
1605 "minimum field width"."maximum field width" for each directive.
1606 Format flags (like @samp{#} for example) may not work as you expect
1607 because many of the fields, even numeric ones, are printed with %s.
1608 The format flag @samp{-} does work; it forces left-alignment of the
1611 @samp{%%} is a literal percent sign. A @samp{%} character followed by
1612 an unrecognised character (i.e., not a known directive or @code{printf}
1613 field width and precision specifier), is discarded (but the
1614 unrecognised character is printed), and a warning message is printed
1615 to the standard error output (because it was probably a typo). Don't
1616 rely on this behaviour, because other directives may be added in the
1619 A @samp{%} at the end of the format argument causes undefined
1620 behaviour since there is no following character. In some locales, it
1621 may hide your door keys, while in others it may remove the final page
1622 from the novel you are reading.
1626 * Ownership Directives::
1628 * Location Directives::
1630 * Formatting Flags::
1633 @node Name Directives
1634 @subsubsection Name Directives
1639 File's name (not the absolute path name, but the name of the file as
1640 it was encountered by @code{find} - that is, as a relative path from
1641 one of the starting points).
1643 File's name with any leading directories removed (only the last
1647 Leading directories of file's name (all but the last element and the
1648 slash before it). If the file's name contains no slashes (for example
1649 because it was named on the command line and is in the current working
1650 directory), then ``%h'' expands to ``.''. This prevents ``%h/%f''
1651 expanding to ``/foo'', which would be surprising and probably not
1655 File's name with the name of the command line argument under which
1656 it was found removed from the beginning.
1659 Command line argument under which file was found.
1663 @node Ownership Directives
1664 @subsubsection Ownership Directives
1669 File's group name, or numeric group ID if the group has no name.
1672 @c TODO: Needs to support # flag and 0 flag
1673 File's numeric group ID.
1676 File's user name, or numeric user ID if the user has no name.
1679 @c TODO: Needs to support # flag
1680 File's numeric user ID.
1682 @c full support, including # and 0.
1683 File's mode bits (in octal). If you always want to have a leading
1684 zero on the number, use the '#' format flag, for example '%#m'.
1686 The file mode bit numbers used are the traditional Unix
1687 numbers, which will be as expected on most systems, but if your
1688 system's file mode bit layout differs from the traditional Unix
1689 semantics, you will see a difference between the mode as printed by
1690 @samp{%m} and the mode as it appears in @code{struct stat}.
1693 File's type and mode bits (in symbolic form, as for @code{ls}). This
1694 directive is supported in findutils 4.2.5 and later.
1697 @node Size Directives
1698 @subsubsection Size Directives
1702 The amount of disk space used for this file in 1K blocks. Since disk
1703 space is allocated in multiples of the filesystem block size this is
1704 usually greater than %s/1024, but it can also be smaller if the file
1705 is a sparse file (that is, it has ``holes'').
1707 The amount of disk space used for this file in 512-byte blocks. Since
1708 disk space is allocated in multiples of the filesystem block size this
1709 is usually greater than %s/1024, but it can also be smaller if the
1710 file is a sparse file (that is, it has ``holes'').
1712 File's size in bytes.
1715 @node Location Directives
1716 @subsubsection Location Directives
1720 File's depth in the directory tree (depth below a file named on the
1721 command line, not depth below the root directory). Files named on the
1722 command line have a depth of 0. Subdirectories immediately below them
1723 have a depth of 1, and so on.
1725 The device number on which the file exists (the @code{st_dev} field of
1726 @code{struct stat}), in decimal.
1728 Type of the filesystem the file is on; this value can be used for
1729 @samp{-fstype} (@pxref{Directories}).
1731 Object of symbolic link (empty string if file is not a symbolic link).
1733 File's inode number (in decimal).
1735 Number of hard links to file.
1737 Type of the file as used with @samp{-type}. If the file is a symbolic
1738 link, @samp{l} will be printed.
1740 Type of the file as used with @samp{-type}. If the file is a symbolic
1741 link, it is dereferenced. If the file is a broken symbolic link,
1742 @samp{N} is printed.
1746 @node Time Directives
1747 @subsubsection Time Directives
1749 Some of these directives use the C @code{ctime} function. Its output
1750 depends on the current locale, but it typically looks like
1753 Wed Nov 2 00:42:36 1994
1758 File's last access time in the format returned by the C @code{ctime}
1761 File's last access time in the format specified by @var{k}
1762 (@pxref{Time Formats}).
1764 File's last status change time in the format returned by the C
1765 @code{ctime} function.
1767 File's last status change time in the format specified by @var{k}
1768 (@pxref{Time Formats}).
1770 File's last modification time in the format returned by the C
1771 @code{ctime} function.
1773 File's last modification time in the format specified by @var{k}
1774 (@pxref{Time Formats}).
1778 @subsection Time Formats
1780 Below are the formats for the directives @samp{%A}, @samp{%C}, and
1781 @samp{%T}, which print the file's timestamps. Some of these formats
1782 might not be available on all systems, due to differences in the C
1783 @code{strftime} function between systems.
1788 * Combined Time Formats::
1791 @node Time Components
1792 @subsubsection Time Components
1794 The following format directives print single components of the time.
1808 time zone (e.g., EDT), or nothing if no time zone is determinable
1814 seconds since Jan. 1, 1970, 00:00 GMT.
1817 @node Date Components
1818 @subsubsection Date Components
1820 The following format directives print single components of the date.
1824 locale's abbreviated weekday name (Sun..Sat)
1826 locale's full weekday name, variable length (Sunday..Saturday)
1829 locale's abbreviated month name (Jan..Dec)
1831 locale's full month name, variable length (January..December)
1835 day of month (01..31)
1839 day of year (001..366)
1841 week number of year with Sunday as first day of week (00..53)
1843 week number of year with Monday as first day of week (00..53)
1847 last two digits of year (00..99)
1850 @node Combined Time Formats
1851 @subsubsection Combined Time Formats
1853 The following format directives print combinations of time and date
1858 time, 12-hour (hh:mm:ss [AP]M)
1860 time, 24-hour (hh:mm:ss)
1862 locale's time representation (H:M:S)
1864 locale's date and time (Sat Nov 04 12:02:33 EST 1989)
1868 locale's date representation (mm/dd/yy)
1870 Date and time, separated by '+', for example `2004-04-28+22:22:05'.
1871 The time is given in the current timezone (which may be affected by
1872 setting the TZ environment variable). This is a GNU extension.
1875 @node Formatting Flags
1876 @subsubsection Formatting Flags
1878 The @samp{%m} and @samp{%d} directives support the @samp{#}, @samp{0}
1879 and @samp{+} flags, but the other directives do not, even if they
1880 print numbers. Numeric directives that do not support these flags
1890 All fields support the format flag @samp{-}, which makes fields
1891 left-aligned. That is, if the field width is greater than the actual
1892 contents of the field, the requisite number of spaces are printed
1893 after the field content instead of before it.
1896 @section Run Commands
1898 You can use the list of file names created by @code{find} or
1899 @code{locate} as arguments to other commands. In this way you can
1900 perform arbitrary actions on the files.
1909 @subsection Single File
1911 Here is how to run a command on one file at a time.
1913 @deffn Action -execdir command ;
1914 Execute @var{command}; true if zero status is returned. @code{find}
1915 takes all arguments after @samp{-exec} to be part of the command until
1916 an argument consisting of @samp{;} is reached. It replaces the string
1917 @samp{@{@}} by the current file name being processed everywhere it
1918 occurs in the command. Both of these constructions need to be escaped
1919 (with a @samp{\}) or quoted to protect them from expansion by the
1920 shell. The command is executed in the directory in which @code{find}
1923 For example, to compare each C header file in or below the current
1924 directory with the file @file{/tmp/master}:
1927 find . -name '*.h' -execdir diff -u '@{@}' /tmp/master ';'
1931 If you use`@samp{-execdir}, you must ensure that the current directory
1932 is not on @var{$PATH}, because otherwise an attacker could make
1933 @samp{find} run commands of their choice simply by leaving a
1934 suitably-named file in the right directory. GNU find will refuse to
1935 run if you use @samp{-execdir} and the current directory is in
1938 Another similar option, @samp{-exec} is supported, but is less secure.
1939 @xref{Security Considerations}, for a discussion of the security
1940 problems surrounding @samp{-exec}.
1943 @deffn Action -exec command ;
1944 This insecure variant of the @samp{-execdir} action is specified by
1945 POSIX. The main difference is that the command is executed in the
1946 directory from which @code{find} was invoked, meaning that @samp{@{@}}
1947 is expanded to a relative path starting with the name of one of the
1948 starting directories, rather than just the basename of the matched
1951 While some implementations of @code{find} replace the @samp{@{@}} only
1952 where it appears on its own in an argument, GNU @code{find} replaces
1953 @samp{@{@}} wherever it appears.
1957 @node Multiple Files
1958 @subsection Multiple Files
1960 Sometimes you need to process files one at a time. But usually this
1961 is not necessary, and, it is faster to run a command on as many files
1962 as possible at a time, rather than once per file. Doing this saves on
1963 the time it takes to start up the command each time.
1965 The @samp{-execdir} and @samp{-exec} actions have variants that build
1966 command lines containing as many matched files as possible.
1968 @deffn Action -execdir command @{@} +
1969 This works as for @samp{-execdir command ;}, except that the
1970 @samp{@{@}} at the end of the command is expanded to a list of names
1971 of matching files. This expansion is done in such a way as to avoid
1972 exceeding the maximum command line length available on the system.
1973 Only one @samp{@{@}} is allowed within the command, and it must appear
1974 at the end, immediately before the @samp{+}. A @samp{+} appearing in
1975 any position other than immediately after @samp{@{@}} is not
1976 considered to be special (that is, it does not terminate the command).
1980 @deffn Action -exec command @{@} +
1981 This insecure variant of the @samp{-execdir} action is specified by
1982 POSIX. The main difference is that the command is executed in the
1983 directory from which @code{find} was invoked, meaning that @samp{@{@}}
1984 is expanded to a relative path starting with the name of one of the
1985 starting directories, rather than just the basename of the matched
1989 Before @code{find} exits, any partially-built command lines are
1990 executed. This happens even if the exit was caused by the
1991 @samp{-quit} action. However, some types of error (for example not
1992 being able to invoke @code{stat()} on the current directory) can cause
1993 an immediate fatal exit. In this situation, any partially-built
1994 command lines will not be invoked (this prevents possible infinite
1997 Another, but less secure, way to run a command on more than one file
1998 at once, is to use the @code{xargs} command, which is invoked like
2002 xargs @r{[}@var{option}@dots{}@r{]} @r{[}@var{command} @r{[}@var{initial-arguments}@r{]}@r{]}
2005 @code{xargs} normally reads arguments from the standard input. These
2006 arguments are delimited by blanks (which can be protected with double
2007 or single quotes or a backslash) or newlines. It executes the
2008 @var{command} (default is @file{/bin/echo}) one or more times with any
2009 @var{initial-arguments} followed by arguments read from standard
2010 input. Blank lines on the standard input are ignored. If the
2011 @samp{-L} option is in use, trailing blanks indicate that @code{xargs}
2012 should consider the following line to be part of this one.
2014 Instead of blank-delimited names, it is safer to use @samp{find
2015 -print0} or @samp{find -fprint0} and process the output by giving the
2016 @samp{-0} or @samp{--null} option to GNU @code{xargs}, GNU @code{tar},
2017 GNU @code{cpio}, or @code{perl}. The @code{locate} command also has a
2018 @samp{-0} or @samp{--null} option which does the same thing.
2020 You can use shell command substitution (backquotes) to process a list
2021 of arguments, like this:
2024 grep -l sprintf `find $HOME -name '*.c' -print`
2027 However, that method produces an error if the length of the @samp{.c}
2028 file names exceeds the operating system's command line length limit.
2029 @code{xargs} avoids that problem by running the command as many times
2030 as necessary without exceeding the limit:
2033 find $HOME -name '*.c' -print | xargs grep -l sprintf
2036 However, if the command needs to have its standard input be a terminal
2037 (@code{less}, for example), you have to use the shell command
2038 substitution method or use the @samp{--arg-file} option of
2041 The @code{xargs} command will process all its input, building command
2042 lines and executing them, unless one of the commands exits with a
2043 status of 255 (this will cause xargs to issue an error message and
2044 stop) or it reads a line contains the end of file string specified
2045 with the @samp{--eof} option.
2048 * Unsafe File Name Handling::
2049 * Safe File Name Handling::
2050 * Unusual Characters in File Names::
2051 * Limiting Command Size::
2052 * Interspersing File Names::
2055 @node Unsafe File Name Handling
2056 @subsubsection Unsafe File Name Handling
2058 Because file names can contain quotes, backslashes, blank characters,
2059 and even newlines, it is not safe to process them using @code{xargs}
2060 in its default mode of operation. But since most files' names do not
2061 contain blanks, this problem occurs only infrequently. If you are
2062 only searching through files that you know have safe names, then you
2063 need not be concerned about it.
2065 @c This example is adapted from:
2066 @c From: pfalstad@stone.Princeton.EDU (Paul John Falstad)
2067 @c Newsgroups: comp.unix.shell
2068 @c Subject: Re: Beware xargs security holes
2069 @c Date: 16 Oct 90 19:12:06 GMT
2071 In many applications, if @code{xargs} botches processing a file
2072 because its name contains special characters, some data might be lost.
2073 The importance of this problem depends on the importance of the data
2074 and whether anyone notices the loss soon enough to correct it.
2075 However, here is an extreme example of the problems that using
2076 blank-delimited names can cause. If the following command is run
2077 daily from @code{cron}, then any user can remove any file on the
2081 find / -name '#*' -atime +7 -print | xargs rm
2084 For example, you could do something like this:
2092 and then @code{cron} would delete @file{/vmunix}, if it ran
2093 @code{xargs} with @file{/} as its current directory.
2095 To delete other files, for example @file{/u/joeuser/.plan}, you could
2103 eg$ mkdir u u/joeuser u/joeuser/.plan'
2105 eg$ echo > u/joeuser/.plan'
2108 eg$ find . -name '#*' -print | xargs echo
2109 ./# ./# /u/joeuser/.plan /#foo
2112 @node Safe File Name Handling
2113 @subsubsection Safe File Name Handling
2115 Here is how to make @code{find} output file names so that they can be
2116 used by other programs without being mangled or misinterpreted. You
2117 can process file names generated this way by giving the @samp{-0} or
2118 @samp{--null} option to GNU @code{xargs}, GNU @code{tar}, GNU
2119 @code{cpio}, or @code{perl}.
2121 @deffn Action -print0
2122 True; print the entire file name on the standard output, followed by a
2126 @deffn Action -fprint0 file
2127 True; like @samp{-print0} but write to @var{file} like @samp{-fprint}
2128 (@pxref{Print File Name}). The output file is always created.
2131 As of findutils version 4.2.4, the @code{locate} program also has a
2132 @samp{--null} option which does the same thing. For similarity with
2133 @code{xargs}, the short form of the option @samp{-0} can also be used.
2135 If you want to be able to handle file names safely but need to run
2136 commands which want to be connected to a terminal on their input, you
2137 can use the @samp{--arg-file} option to @code{xargs} like this:
2140 find / -name xyzzy -print0 > list
2141 xargs --null --arg-file=list munge
2144 The example above runs the @code{munge} program on all the files named
2145 @file{xyzzy} that we can find, but @code{munge}'s input will still be
2146 the terminal (or whatever the shell was using as standard input). If
2147 your shell has the ``process substitution'' feature @samp{<(...)}, you
2148 can do this in just one step:
2151 xargs --null --arg-file=<(find / -name xyzzy -print0) munge
2154 @node Unusual Characters in File Names
2155 @subsubsection Unusual Characters in File Names
2156 As discussed above, you often need to be careful about how the names
2157 of files are handled by @code{find} and other programs. If the output
2158 of @code{find} is not going to another program but instead is being
2159 shown on a terminal, this can still be a problem. For example, some
2160 character sequences can reprogram the function keys on some terminals.
2161 @xref{Security Considerations}, for a discussion of other security
2162 problems relating to @code{find}.
2164 Unusual characters are handled differently by various
2165 actions, as described below.
2170 Always print the exact file name, unchanged, even if the output is
2171 going to a terminal.
2174 Always print the exact file name, unchanged. This will probably
2175 change in a future release.
2178 Unusual characters are always escaped. White space, backslash, and
2179 double quote characters are printed using C-style escaping (for
2180 example @samp{\f}, @samp{\"}). Other unusual characters are printed
2181 using an octal escape. Other printable characters (for @samp{-ls} and
2182 @samp{-fls} these are the characters between octal 041 and 0176) are
2186 If the output is not going to a terminal, it is printed as-is.
2187 Otherwise, the result depends on which directive is in use:
2190 @item %D, %F, %H, %Y, %y
2191 These expand to values which are not under control of files' owners,
2192 and so are printed as-is.
2193 @item %a, %b, %c, %d, %g, %G, %i, %k, %m, %M, %n, %s, %t, %u, %U
2194 These have values which are under the control of files' owners but
2195 which cannot be used to send arbitrary data to the terminal, and so
2196 these are printed as-is.
2197 @item %f, %h, %l, %p, %P
2198 The output of these directives is quoted if the output is going to a
2201 This quoting is performed in the same way as for GNU @code{ls}. This
2202 is not the same quoting mechanism as the one used for @samp{-ls} and
2203 @samp{fls}. If you are able to decide what format to use for the
2204 output of @code{find} then it is normally better to use @samp{\0} as a
2205 terminator than to use newline, as file names can contain white space
2206 and newline characters.
2210 Quoting is handled in the same way as for the @samp{%p} directive of
2211 @samp{-printf} and @samp{-fprintf}. If you are using @code{find} in a
2212 script or in a situation where the matched files might have arbitrary
2213 names, you should consider using @samp{-print0} instead of
2218 The @code{locate} program quotes and escapes unusual characters in
2219 file names in the same way as @code{find}'s @samp{-print} action.
2221 The behaviours described above may change soon, as the treatment of
2222 unprintable characters is harmonised for @samp{-ls}, @samp{-fls},
2223 @samp{-print}, @samp{-fprint}, @samp{-printf} and @samp{-fprintf}.
2225 @node Limiting Command Size
2226 @subsubsection Limiting Command Size
2228 @code{xargs} gives you control over how many arguments it passes to
2229 the command each time it executes it. By default, it uses up to
2230 @code{ARG_MAX} - 2k, or 128k, whichever is smaller, characters per
2231 command. It uses as many lines and arguments as fit within that
2232 limit. The following options modify those values.
2235 @item --no-run-if-empty
2237 If the standard input does not contain any nonblanks, do not run the
2238 command. By default, the command is run once even if there is no
2239 input. This option is a GNU extension.
2241 @item --max-lines@r{[}=@var{max-lines}@r{]}
2242 @itemx -L @var{max-lines}
2243 @itemx -l@r{[}@var{max-lines}@r{]}
2244 Use at most @var{max-lines} nonblank input lines per command line;
2245 @var{max-lines} defaults to 1 if omitted; omitting the argument is not
2246 allowed in the case of the @samp{-L} option. Trailing blanks cause an
2247 input line to be logically continued on the next input line, for the
2248 purpose of counting the lines. Implies @samp{-x}. The preferred name
2249 for this option is @samp{-L} as this is specified by POSIX.
2251 @item --max-args=@var{max-args}
2252 @itemx -n @var{max-args}
2253 Use at most @var{max-args} arguments per command line. Fewer than
2254 @var{max-args} arguments will be used if the size (see the @samp{-s}
2255 option) is exceeded, unless the @samp{-x} option is given, in which
2256 case @code{xargs} will exit.
2258 @item --max-chars=@var{max-chars}
2259 @itemx -s @var{max-chars}
2260 Use at most @var{max-chars} characters per command line, including the
2261 command initial arguments and the terminating nulls at the ends of the
2262 argument strings. If you specify a value for this option which is too
2263 large or small, a warning message is printed and the appropriate upper
2264 or lower limit is used instead. You can use @samp{--show-limits}
2265 option to understand the command-line limits applying to @code{xargs}
2266 and how this is affected by any other options.
2268 @item --max-procs=@var{max-procs}
2269 @itemx -P @var{max-procs}
2270 Run up to @var{max-procs} processes at a time; the default is 1. If
2271 @var{max-procs} is 0, @code{xargs} will run as many processes as
2272 possible at a time. Use the @samp{-n}, @samp{-s}, or @samp{-L} option
2273 with @samp{-P}; otherwise chances are that the command will be run
2277 @node Interspersing File Names
2278 @subsubsection Interspersing File Names
2280 @code{xargs} can insert the name of the file it is processing between
2281 arguments you give for the command. Unless you also give options to
2282 limit the command size (@pxref{Limiting Command Size}), this mode of
2283 operation is equivalent to @samp{find -exec} (@pxref{Single File}).
2286 @item --replace@r{[}=@var{replace-str}@r{]}
2287 @itemx -I @var{replace-str}
2288 @itemx -i @var{replace-str}
2289 Replace occurrences of @var{replace-str} in the initial arguments with
2290 names read from the input. Also, unquoted blanks do not terminate
2291 arguments; instead, the input is split at newlines only. For the
2292 @samp{-i} option, if @var{replace-str} is omitted for @samp{--replace}
2293 or @samp{-i}, it defaults to @samp{@{@}} (like for @samp{find -exec}).
2294 Implies @samp{-x} and @samp{-l 1}. @samp{-i} is deprecated in favour
2295 of @samp{-I}. As an example, to sort each file in the @file{bills}
2296 directory, leaving the output in that file name with @file{.sorted}
2297 appended, you could do:
2300 find bills -type f | xargs -I XX sort -o XX.sorted XX
2304 The equivalent command using @samp{find -execdir} is:
2307 find bills -type f -execdir sort -o '@{@}.sorted' '@{@}' ';'
2312 When you use the @samp{-I} option, each line read from the input is
2313 buffered internally. This means that there is an upper limit on the
2314 length of input line that xargs will accept when used with the
2315 @samp{-I} option. To work around this limitation, you can use the
2316 @samp{-s} option to increase the amount of buffer space that xargs
2317 uses, and you can also use an extra invocation of xargs to ensure that
2318 very long lines do not occur. For example:
2321 somecommand | xargs -s 50000 echo | xargs -I '@{@}' -s 100000 rm '@{@}'
2324 Here, the first invocation of @code{xargs} has no input line length
2325 limit because it doesn't use the @samp{-I} option. The second
2326 invocation of @code{xargs} does have such a limit, but we have ensured
2327 that the it never encounters a line which is longer than it can
2330 This is not an ideal solution. Instead, the @samp{-I} option should
2331 not impose a line length limit (apart from any limit imposed by the
2332 operating system) and so one might consider this limitation to be a
2333 bug. A better solution would be to allow @code{xargs -I} to
2334 automatically move to a larger value for the @samp{-s} option when
2337 This sort of problem doesn't occur with the output of @code{find}
2338 because it emits just one filename per line.
2341 @subsection Querying
2343 To ask the user whether to execute a command on a single file, you can
2344 use the @code{find} primary @samp{-okdir} instead of @samp{-execdir},
2345 and the @code{find} primary @samp{-ok} instead of @samp{-exec}:
2347 @deffn Action -okdir command ;
2348 Like @samp{-execdir} (@pxref{Single File}), but ask the user first (on
2349 the standard input); if the response does not start with @samp{y} or
2350 @samp{Y}, do not run the command, and return false. If the command is
2351 run, its standard input is redirected from @file{/dev/null}.
2354 @deffn Action -ok command ;
2355 This insecure variant of the @samp{-okdir} action is specified by
2356 POSIX. The main difference is that the command is executed in the
2357 directory from which @code{find} was invoked, meaning that @samp{@{@}}
2358 is expanded to a relative path starting with the name of one of the
2359 starting directories, rather than just the basename of the matched
2360 file. If the command is run, its standard input is redirected from
2364 When processing multiple files with a single command, to query the
2365 user you give @code{xargs} the following option. When using this
2366 option, you might find it useful to control the number of files
2367 processed per invocation of the command (@pxref{Limiting Command
2373 Prompt the user about whether to run each command line and read a line
2374 from the terminal. Only run the command line if the response starts
2375 with @samp{y} or @samp{Y}. Implies @samp{-t}.
2379 @section Delete Files
2381 @deffn Action -delete
2382 Delete files or directories; true if removal succeeded. If the
2383 removal failed, an error message is issued.
2385 The use of the @samp{-delete} action on the command line automatically
2386 turns on the @samp{-depth} option (@pxref{find Expressions}).
2390 @section Adding Tests
2392 You can test for file attributes that none of the @code{find} builtin
2393 tests check. To do this, use @code{xargs} to run a program that
2394 filters a list of files printed by @code{find}. If possible, use
2395 @code{find} builtin tests to pare down the list, so the program run by
2396 @code{xargs} has less work to do. The tests builtin to @code{find}
2397 will likely run faster than tests that other programs perform.
2399 For reasons of efficiency it is often useful to limit the number of
2400 times an external program has to be run. For this reason, it is often
2401 a good idea to implement ``extended'' tests by using @code{xargs}.
2403 For example, here is a way to print the names of all of the unstripped
2404 binaries in the @file{/usr/local} directory tree. Builtin tests avoid
2405 running @code{file} on files that are not regular files or are not
2409 find /usr/local -type f -perm /a=x | xargs file |
2410 grep 'not stripped' | cut -d: -f1
2414 The @code{cut} program removes everything after the file name from the
2415 output of @code{file}.
2417 However, using @code{xargs} can present important security problems
2418 (@pxref{Security Considerations}). These can be avoided by using
2419 @samp{-execdir}. The @samp{-execdir} action is also a useful way of
2420 putting your own test in the middle of a set of other tests or actions
2421 for @code{find} (for example, you might want to use @samp{-prune}).
2423 @c Idea from Martin Weitzel.
2424 To place a special test somewhere in the middle of a @code{find}
2425 expression, you can use @samp{-execdir} (or, less securely,
2426 @samp{-exec}) to run a program that performs the test. Because
2427 @samp{-execdir} evaluates to the exit status of the executed program,
2428 you can use a program (which can be a shell script) that tests for a
2429 special attribute and make it exit with a true (zero) or false
2430 (non-zero) status. It is a good idea to place such a special test
2431 @emph{after} the builtin tests, because it starts a new process which
2432 could be avoided if a builtin test evaluates to false.
2434 Here is a shell script called @code{unstripped} that checks whether
2435 its argument is an unstripped binary file:
2439 file "$1" | grep -q "not stripped"
2443 This script relies on the shell exiting with the status of
2444 the last command in the pipeline, in this case @code{grep}. The
2445 @code{grep} command exits with a true status if it found any matches,
2446 false if not. Here is an example of using the script (assuming it is
2447 in your search path). It lists the stripped executables (and shell
2448 scripts) in the file @file{sbins} and the unstripped ones in
2452 find /usr/local -type f -perm /a=x \
2453 \( -execdir unstripped '@{@}' \; -fprint ubins -o -fprint sbins \)
2457 @node Databases, File Permissions, Actions, Top
2458 @chapter File Name Databases
2460 The file name databases used by @code{locate} contain lists of files
2461 that were in particular directory trees when the databases were last
2462 updated. The file name of the default database is determined when
2463 @code{locate} and @code{updatedb} are configured and installed. The
2464 frequency with which the databases are updated and the directories for
2465 which they contain entries depend on how often @code{updatedb} is run,
2466 and with which arguments.
2468 You can obtain some statistics about the databases by using
2469 @samp{locate --statistics}.
2472 * Database Locations::
2473 * Database Formats::
2474 * Newline Handling::
2478 @node Database Locations
2479 @section Database Locations
2481 There can be multiple file name databases. Users can select which
2482 databases @code{locate} searches using the @code{LOCATE_PATH}
2483 environment variable or a command line option. The system
2484 administrator can choose the file name of the default database, the
2485 frequency with which the databases are updated, and the directories
2486 for which they contain entries. File name databases are updated by
2487 running the @code{updatedb} program, typically nightly.
2489 In networked environments, it often makes sense to build a database at
2490 the root of each filesystem, containing the entries for that
2491 filesystem. @code{updatedb} is then run for each filesystem on the
2492 fileserver where that filesystem is on a local disk, to prevent
2493 thrashing the network.
2495 @xref{Invoking updatedb},
2496 for the description of the options to @code{updatedb}, which specify
2497 which directories would each database contain entries for.
2500 @node Database Formats
2501 @section Database Formats
2503 The file name databases contain lists of files that were in particular
2504 directory trees when the databases were last updated. The file name
2505 database format changed starting with GNU @code{locate} version 4.0 to
2506 allow machines with different byte orderings to share the databases.
2507 The new GNU @code{locate} can read both the old and new database
2508 formats. However, old versions of @code{locate} and @code{find}
2509 produce incorrect results if given a new-format database.
2511 Support for the old database format will eventually be discontinued,
2512 first in @code{updatedb} and later in @code{xargs}.
2514 If you run @samp{locate --statistics}, the resulting summary indicates
2515 the type of each @code{locate} database.
2519 * New Database Format::
2521 * Old Database Format::
2524 @node New Database Format
2525 @subsection New Database Format
2527 @code{updatedb} runs a program called @code{frcode} to
2528 @dfn{front-compress} the list of file names, which reduces the
2529 database size by a factor of 4 to 5. Front-compression (also known as
2530 incremental encoding) works as follows.
2532 The database entries are a sorted list (case-insensitively, for users'
2533 convenience). Since the list is sorted, each entry is likely to share
2534 a prefix (initial string) with the previous entry. Each database
2535 entry begins with an offset-differential count byte, which is the
2536 additional number of characters of prefix of the preceding entry to
2537 use beyond the number that the preceding entry is using of its
2538 predecessor. (The counts can be negative.) Following the count is a
2539 null-terminated ASCII remainder---the part of the name that follows
2542 If the offset-differential count is larger than can be stored in a
2543 byte (+/-127), the byte has the value 0x80 and the count follows in a
2544 2-byte word, with the high byte first (network byte order).
2546 Every database begins with a dummy entry for a file called
2547 @file{LOCATE02}, which @code{locate} checks for to ensure that the
2548 database file has the correct format; it ignores the entry in doing
2551 Databases cannot be concatenated together, even if the first (dummy)
2552 entry is trimmed from all but the first database. This is because the
2553 offset-differential count in the first entry of the second and
2554 following databases will be wrong.
2556 In the output of @samp{locate --statistics}, the new database format
2557 is referred to as @samp{LOCATE02}.
2559 @node Sample Database
2560 @subsection Sample Database
2562 Sample input to @code{frcode}:
2563 @c with nulls changed to newlines:
2567 /usr/src/cmd/aardvark.c
2568 /usr/src/cmd/armadillo.c
2572 Length of the longest prefix of the preceding entry to share:
2581 Output from @code{frcode}, with trailing nulls changed to newlines
2582 and count bytes made printable:
2592 (6 = 14 - 8, and -9 = 5 - 14)
2594 @node Old Database Format
2595 @subsection Old Database Format
2597 The old database format is used by Unix @code{locate} and @code{find}
2598 programs and earlier releases of the GNU ones. @code{updatedb}
2599 produces this format if given the @samp{--old-format} option.
2601 @code{updatedb} runs programs called @code{bigram} and @code{code} to
2602 produce old-format databases. The old format differs from the new one
2603 in the following ways. Instead of each entry starting with an
2604 offset-differential count byte and ending with a null, byte values
2605 from 0 through 28 indicate offset-differential counts from -14 through
2606 14. The byte value indicating that a long offset-differential count
2607 follows is 0x1e (30), not 0x80. The long counts are stored in host
2608 byte order, which is not necessarily network byte order, and host
2609 integer word size, which is usually 4 bytes. They also represent a
2610 count 14 less than their value. The database lines have no
2611 termination byte; the start of the next line is indicated by its first
2612 byte having a value <= 30.
2614 In addition, instead of starting with a dummy entry, the old database
2615 format starts with a 256 byte table containing the 128 most common
2616 bigrams in the file list. A bigram is a pair of adjacent bytes.
2617 Bytes in the database that have the high bit set are indexes (with the
2618 high bit cleared) into the bigram table. The bigram and
2619 offset-differential count coding makes these databases 20-25% smaller
2620 than the new format, but makes them not 8-bit clean. Any byte in a
2621 file name that is in the ranges used for the special codes is replaced
2622 in the database by a question mark, which not coincidentally is the
2623 shell wildcard to match a single character.
2625 The old format therefore cannot faithfully store entries with
2626 non-ASCII characters. It therefore should not be used in
2627 internationalised environments.
2629 The output of @samp{locate --statistics} will give an incorrect count
2630 of the number of file names containing newlines or high-bit characters
2631 for old-format databases.
2633 @node Newline Handling
2634 @section Newline Handling
2636 Within the database, file names are terminated with a null character.
2637 This is the case for both the old and the new format.
2639 When the new database format is being used, the compression technique
2640 used to generate the database though relies on the ability to sort the
2641 list of files before they are presented to @code{frcode}.
2643 If the system's sort command allows its input list of files to be
2644 separated with null characters via the @samp{-z} option, this option
2645 is used and therefore @code{updatedb} and @code{locate} will both
2646 correctly handle file names containing newlines. If the @code{sort}
2647 command lacks support for this, the list of files is delimited with
2648 the newline character, meaning that parts of file names containing
2649 newlines will be incorrectly sorted. This can result in both
2650 incorrect matches and incorrect failures to match.
2652 On the other hand, if you are using the old database format, file
2653 names with embedded newlines are not correctly handled. There is no
2654 technical limitation which enforces this, it's just that the
2655 @code{bigram} program has not been updated to support lists of file
2656 names separated by nulls.
2658 So, if you are using the new database format (this is the default) and
2659 your system uses GNU @code{sort}, newlines will be correctly handled
2660 at all times. Otherwise, newlines may not be correctly handled.
2662 @node File Permissions, Reference, Databases, Top
2663 @chapter File Permissions
2667 @node Reference, Common Tasks, File Permissions, Top
2670 Below are summaries of the command line syntax for the programs
2671 discussed in this manual.
2676 * Invoking updatedb::
2678 * Regular Expressions::
2679 * Environment Variables::
2682 @node Invoking find, Invoking locate, , Reference
2683 @section Invoking @code{find}
2686 find @r{[-H] [-L] [-P] [-D @var{debugoptions}] [-O@var{level}]} @r{[}@var{file}@dots{}@r{]} @r{[}@var{expression}@r{]}
2689 @code{find} searches the directory tree rooted at each file name
2690 @var{file} by evaluating the @var{expression} on each file it finds in
2693 The command line may begin with the @samp{-H}, @samp{-L}, @samp{-P},
2694 @samp{-D} and @samp{-O} options. These are followed by a list of
2695 files or directories that should be searched. If no files to search
2696 are specified, the current directory (@file{.}) is used.
2698 This list of files to search is followed by a list of expressions
2699 describing the files we wish to search for. The first part of the
2700 expression is recognised by the fact that it begins with @samp{-}
2701 followed by some other letters (for example @samp{-print}), or is
2702 either @samp{(} or @samp{!}. Any arguments after it are the rest of
2705 If no expression is given, the expression @samp{-print} is used.
2707 The @code{find} command exits with status zero if all files matched
2708 are processed successfully, greater than zero if errors occur.
2710 The @code{find} program also recognises two options for administrative
2715 Print a summary of the command line usage and exit.
2717 Print the version number of @code{find} and exit.
2720 The @samp{-version} option is a synonym for @samp{--version}
2724 * Filesystem Traversal Options::
2725 * Warning Messages::
2726 * Optimisation Options::
2728 * Find Expressions::
2731 @node Filesystem Traversal Options, Warning Messages,, Invoking find
2732 @subsection Filesystem Traversal Options
2734 The options @samp{-H}, @samp{-L} or @samp{-P} may be specified at the
2735 start of the command line (if none of these is specified, @samp{-P} is
2736 assumed). If you specify more than one of these options, the last one
2737 specified takes effect (but note that the @samp{-follow} option is
2738 equivalent to @samp{-L}).
2742 Never follow symbolic links (this is the default), except in the case
2743 of the @samp{-xtype} predicate.
2745 Always follow symbolic links, except in the case of the @samp{-xtype}
2748 Follow symbolic links specified in the list of files to search, or
2749 which are otherwise specified on the command line.
2752 If @code{find} would follow a symbolic link, but cannot for any reason
2753 (for example, because it has insufficient permissions or the link is
2754 broken), it falls back on using the properties of the symbolic link
2755 itself. @ref{Symbolic Links} for a more complete description of how
2756 symbolic links are handled.
2758 @node Warning Messages, Optimisation Options, Filesystem Traversal Options, Invoking find
2759 @subsection Warning Messages
2761 If there is an error on the @code{find} command line, an error message
2762 is normally issued. However, there are some usages that are
2763 inadvisable but which @code{find} should still accept. Under these
2764 circumstances, @code{find} may issue a warning message. By default,
2765 warnings are enabled only if @code{find} is being run interactively
2766 (specifically, if the standard input is a terminal). Warning messages
2767 can be controlled explicitly by the use of options on the command
2772 Issue warning messages where appropriate.
2774 Do not issue warning messages.
2777 These options take effect at the point on the command line where they
2778 are specified. Therefore it's not useful to specify @samp{-nowarn} at
2779 the end of the command line. The warning messages affected by the
2780 above options are triggered by:
2784 Use of the @samp{-d} option which is deprecated; please use
2785 @samp{-depth} instead, since the latter is POSIX-compliant.
2787 Use of the @samp{-ipath} option which is deprecated; please use
2788 @samp{-iwholename} instead.
2790 Specifying an option (for example @samp{-mindepth}) after a non-option
2791 (for example @samp{-type} or @samp{-print}) on the command line.
2794 The default behaviour above is designed to work in that way so that
2795 existing shell scripts don't generate spurious errors, but people will
2796 be made aware of the problem.
2798 Some warning messages are issued for less common or more serious
2799 problems, and consequently cannot be turned off:
2803 Use of an unrecognised backslash escape sequence with @samp{-fprintf}
2805 Use of an unrecognised formatting directive with @samp{-fprintf}
2808 @node Optimisation Options, Debug Options, Warning Messages, Invoking find
2809 @subsection Optimisation Options
2811 The @samp{-O@var{level}} option sets @code{find}'s optimisation level
2812 to @var{level}. The default optimisation level is 1.
2814 At certain optimisation levels, @code{find} reorders tests to speed up
2815 execution while preserving the overall effect; that is, predicates
2816 with side effects are not reordered relative to each other. The
2817 optimisations performed at each optimisation level are as follows.
2821 Currently equivalent to optimisation level 1.
2824 This is the default optimisation level and corresponds to the
2825 traditional behaviour. Expressions are reordered so that tests based
2826 only on the names of files (for example@samp{ -name} and
2827 @samp{-regex}) are performed first.
2830 Any @samp{-type} or @samp{-xtype} tests are performed after any tests
2831 based only on the names of files, but before any tests that require
2832 information from the inode. On many modern versions of Unix, file
2833 types are returned by @code{readdir()} and so these predicates are
2834 faster to evaluate than predicates which need to stat the file first.
2837 At this optimisation level, the full cost-based query optimiser is
2838 enabled. The order of tests is modified so that cheap (i.e., fast)
2839 tests are performed first and more expensive ones are performed later,
2840 if necessary. Within each cost band, predicates are evaluated earlier
2841 or later according to whether they are likely to succeed or not. For
2842 @samp{-o}, predicates which are likely to succeed are evaluated
2843 earlier, and for @samp{-a}, predicates which are likely to fail are
2848 @node Debug Options, Find Expressions, Optimisation Options, Invoking find
2849 @subsection Debug Options
2851 The @samp{-D} option makes @code{find} produce diagnostic output.
2852 Much of the information is useful only for diagnosing problems, and so
2853 most people will not find this option helpful.
2855 The list of debug options should be comma separated. Compatibility of
2856 the debug options is not guaranteed between releases of findutils.
2857 For a complete list of valid debug options, see the output of
2858 @code{find -D help}. Valid debug options include:
2861 Explain the debugging options.
2863 Show the expression tree in its original and optimised form.
2865 Print messages as files are examined with the stat and lstat system
2866 calls. The find program tries to minimise such calls.
2868 Prints diagnostic information relating to the optimisation of the
2869 expression tree; see the @samp{-O} option.
2872 @node Find Expressions,, Debug Options, Invoking find
2873 @subsection Find Expressions
2875 The final part of the @code{find} command line is a list of
2876 expressions. @xref{Primary Index}, for a summary of all of the tests,
2877 actions, and options that the expression can contain. If the
2878 expression is missing, @samp{-print} is assumed.
2880 @node Invoking locate, Invoking updatedb, Invoking find, Reference
2881 @section Invoking @code{locate}
2884 locate @r{[}@var{option}@dots{}@r{]} @var{pattern}@dots{}
2887 For each @var{pattern} given @code{locate} searches one or more file
2888 name databases returning each match of @var{pattern}.
2890 For each @var{pattern} given @code{locate} searches one or more file
2891 name databases returning each match of @var{pattern}.
2896 Print only names which match all non-option arguments, not those
2897 matching one or more non-option arguments.
2901 The specified pattern is matched against just the last component of
2902 the name of a file in the @code{locate} database. This last
2903 component is also called the ``base name''. For example, the base
2904 name of @file{/tmp/mystuff/foo.old.c} is @file{foo.old.c}. If the
2905 pattern contains metacharacters, it must match the base name exactly.
2906 If not, it must match part of the base name.
2910 Instead of printing the matched file names, just print the total
2911 number of matches found, unless @samp{--print} (@samp{-p}) is also
2915 @item --database=@var{path}
2916 @itemx -d @var{path}
2917 Instead of searching the default @code{locate} database, @code{locate} search the file
2918 name databases in @var{path}, which is a colon-separated list of
2919 database file names. You can also use the environment variable
2920 @code{LOCATE_PATH} to set the list of database files to search. The
2921 option overrides the environment variable if both are used. Empty
2922 elements in @var{path} (that is, a leading or trailing colon, or two
2923 colons in a row) are taken to stand for the default database.
2924 A database can be supplied on stdin, using @samp{-} as an element
2925 of @samp{path}. If more than one element of @samp{path} is @samp{-},
2926 later instances are ignored (but a warning message is printed).
2930 Only print out such names which currently exist (instead of such names
2931 which existed when the database was created). Note that this may slow
2932 down the program a lot, if there are many matches in the database.
2933 The way in which broken symbolic links are treated is affected by the
2934 @samp{-L}, @samp{-P} and @samp{-H} options. Please note that it is
2935 possible for the file to be deleted after @code{locate} has checked
2936 that it exists, but before you use it.
2938 @item --non-existing
2940 Only print out such names which currently do not exist (instead of
2941 such names which existed when the database was created). Note that
2942 this may slow down the program a lot, if there are many matches in the
2943 database. The way in which broken symbolic links are treated is
2944 affected by the @samp{-L}, @samp{-P} and @samp{-H} options. Please
2945 note that @code{locate} checks that the file does not exist, but a
2946 file of the same name might be created after @code{locate}'s check but
2947 before you read @code{locate}'s output.
2951 If testing for the existence of files (with the @samp{-e} or @samp{-E}
2952 options), consider broken symbolic links to be non-existing. This is
2953 the default behaviour.
2958 If testing for the existence of files (with the @samp{-e} or @samp{-E}
2959 options), treat broken symbolic links as if they were existing files.
2960 The @samp{-H} form of this option is provided purely for similarity
2961 with @code{find}; the use of @samp{-P} is recommended over @samp{-H}.
2965 Ignore case distinctions in both the pattern and the file names.
2969 Limit the number of results printed to N. When used with the
2970 @samp{--count} option, the value printed will never be larger than
2972 @item --max-database-age=D
2973 Normally, @code{locate} will issue a warning message when it searches
2974 a database which is more than 8 days old. This option changes that
2975 value to something other than 8. The effect of specifying a negative
2979 Accepted but does nothing. The option is supported only to provide
2980 compatibility with BSD's @code{locate}.
2984 Results are separated with the ASCII NUL character rather than the
2985 newline character. To get the full benefit of the use of this option,
2986 use the new @code{locate} database format (that is the default
2991 Print search results when they normally would not, because of the
2992 presence of @samp{--statistics} (@samp{-S}) or @samp{--count}
2997 The specified pattern is matched against the whole name of the file in
2998 the @code{locate} database. If the pattern contains metacharacters,
2999 it must match exactly. If not, it must match part of the whole file
3000 name. This is the default behaviour.
3004 Instead of using substring or shell glob matching, the pattern
3005 specified on the command line is understood to be a regular
3006 expression. GNU Emacs-style regular expressions are assumed unless
3007 the @samp{--regextype} option is also given. File names from the
3008 @code{locate} database are matched using the specified regular
3009 expression. If the @samp{-i} flag is also given, matching is
3010 case-insensitive. Matches are performed against the whole path name,
3011 and so by default a pathname will be matched if any part of it matches
3012 the specified regular expression. The regular expression may use
3013 @samp{^} or @samp{$} to anchor a match at the beginning or end of a
3017 This option changes the regular expression syntax and behaviour used
3018 by the @samp{--regex} option. @ref{Regular Expressions} for more
3019 information on the regular expression dialects understood by GNU
3024 Accepted but does nothing. The option is supported only to provide
3025 compatibility with BSD's @code{locate}.
3029 Print some summary information for each @code{locate} database. No
3030 search is performed unless non-option arguments are given.
3031 Although the BSD version of locate also has this option, the format of the
3032 output is different.
3035 Print a summary of the command line usage for @code{locate} and exit.
3038 Print the version number of @code{locate} and exit.
3041 @node Invoking updatedb, Invoking xargs, Invoking locate, Reference
3042 @section Invoking @code{updatedb}
3045 updatedb @r{[}@var{option}@dots{}@r{]}
3048 @code{updatedb} creates and updates the database of file names used by
3049 @code{locate}. @code{updatedb} generates a list of files similar to
3050 the output of @code{find} and then uses utilities for optimizing the
3051 database for performance. @code{updatedb} is often run periodically
3052 as a @code{cron} job and configured with environment variables or
3053 command options. Typically, operating systems have a shell script
3054 that ``exports'' configurations for variable definitions and uses
3055 another shell script that ``sources'' the configuration file into the
3056 environment and then executes @code{updatedb} in the environment.
3058 @code{updatedb} creates and updates the database of file names used by
3059 @code{locate}. @code{updatedb} generates a list of files similar to
3060 the output of @code{find} and then uses utilities for optimizing the
3061 database for performance. @code{updatedb} is often run periodically
3062 as a @code{cron} job and configured with environment variables or
3063 command options. Typically, operating systems have a shell script
3064 that ``exports'' configurations for variable definitions and uses
3065 another shell script that ``sources'' the configuration file into the
3066 environment and then executes @code{updatedb} in the environment.
3069 @item --findoptions='@var{OPTION}@dots{}'
3070 Global options to pass on to @code{find}.
3071 The environment variable @code{FINDOPTIONS} also sets this value.
3074 @item --localpaths='@var{path}@dots{}'
3075 Non-network directories to put in the database.
3076 Default is @file{/}.
3078 @item --netpaths='@var{path}@dots{}'
3079 Network (NFS, AFS, RFS, etc.) directories to put in the database.
3080 The environment variable @code{NETPATHS} also sets this value.
3083 @item --prunepaths='@var{path}@dots{}'
3084 Directories to omit from the database, which would otherwise be
3085 included. The environment variable @code{PRUNEPATHS} also sets this
3086 value. Default is @file{/tmp /usr/tmp /var/tmp /afs}. The paths are
3087 used as regular expressions (with @code{find ... -regex}, so you need
3088 to specify these paths in the same way that @code{find} will encounter
3089 them. This means for example that the paths must not include trailing
3092 @item --prunefs='@var{path}@dots{}'
3093 Filesystems to omit from the database, which would otherwise be
3094 included. Note that files are pruned when a filesystem is reached;
3095 Any filesystem mounted under an undesired filesystem will be ignored.
3096 The environment variable @code{PRUNEFS} also sets this value. Default
3097 is @file{nfs NFS proc}.
3099 @item --output=@var{dbfile}
3100 The database file to build. Default is system-dependent, but
3101 typically @file{/usr/local/var/locatedb}.
3103 @item --localuser=@var{user}
3104 The user to search the non-network directories as, using @code{su}.
3105 Default is to search the non-network directories as the current user.
3106 You can also use the environment variable @code{LOCALUSER} to set this user.
3108 @item --netuser=@var{user}
3109 The user to search network directories as, using @code{su}. Default
3110 @code{user} is @code{daemon}. You can also use the environment variable
3111 @code{NETUSER} to set this user.
3114 Generate a @code{locate} database in the old format, for compatibility
3115 with versions of @code{locate} other than GNU @code{locate}. Using
3116 this option means that @code{locate} will not be able to properly
3117 handle non-ASCII characters in file names (that is, file names
3118 containing characters which have the eighth bit set, such as many of
3119 the characters from the ISO-8859-1 character set).
3121 Print a summary of the command line usage and exit.
3123 Print the version number of @code{updatedb} and exit.
3126 @node Invoking xargs, Regular Expressions, Invoking updatedb, Reference
3127 @section Invoking @code{xargs}
3130 xargs @r{[}@var{option}@dots{}@r{]} @r{[}@var{command} @r{[}@var{initial-arguments}@r{]}@r{]}
3133 @code{xargs} exits with the following status:
3139 if any invocation of the command exited with status 1-125
3141 if the command exited with status 255
3143 if the command is killed by a signal
3145 if the command cannot be run
3147 if the command is not found
3149 if some other error occurred.
3152 Exit codes greater than 128 are used by the shell to indicate that
3153 a program died due to a fatal signal.
3156 @item --arg-file@r{=@var{inputfile}}
3157 @itemx -a o@r{@var{inputfile}}
3158 Read names from the file @var{inputfile} instead of standard input.
3159 If you use this option, the standard input stream remains unchanged
3160 when commands are run. Otherwise, stdin is redirected from
3165 Input file names are terminated by a null character instead of by
3166 whitespace, and any quotes and backslash characters are not considered
3167 special (every character is taken literally). Disables the end of
3168 file string, which is treated like any other argument.
3170 @item --delimiter @var{delim}
3171 @itemx -d @var{delim}
3173 Input file names are terminated by the specified character @var{delim}
3174 instead of by whitespace, and any quotes and backslash characters are
3175 not considered special (every character is taken literally). Disables
3176 the end of file string, which is treated like any other argument.
3178 The specified delimiter may be a single character, a C-style character
3179 escape such as @samp{\n}, or an octal or hexadecimal escape code.
3180 Octal and hexadecimal escape codes are understood as for the
3181 @code{printf} command. Multibyte characters are not supported.
3184 @item -E @var{eof-str}
3185 @itemx --eof@r{[}=@var{eof-str}@r{]}
3186 @itemx -e@r{[}@var{eof-str}@r{]}
3187 Set the end of file string to @var{eof-str}. If the end of file
3188 string occurs as a line of input, the rest of the input is ignored.
3189 If @var{eof-str} is omitted (@samp{-e}) or blank (either @samp{-e} or
3190 @samp{-E}), there is no end of file string. The @samp{-e} form of
3191 this option is deprecated in favour of the POSIX-compliant @samp{-E}
3192 option, which you should use instead. As of GNU xargs version 4.2.9,
3193 the default behaviour of xargs is not to have a logical end-of-file
3194 marker. The POSIX standard (IEEE Std 1003.1, 2004 Edition) allows
3198 Print a summary of the options to @code{xargs} and exit.
3200 @item -I @var{replace-str}
3201 @itemx --replace@r{[}=@var{replace-str}@r{]}
3202 @itemx -i@r{[}@var{replace-str}@r{]}
3203 Replace occurrences of @var{replace-str} in the initial arguments with
3204 names read from standard input. Also, unquoted blanks do not
3205 terminate arguments; instead, the input is split at newlines only. If
3206 @var{replace-str} is omitted (omitting it is allowed only for
3207 @samp{-i}), it defaults to @samp{@{@}} (like for @samp{find -exec}).
3208 Implies @samp{-x} and @samp{-l 1}. The @samp{-i} option is deprecated
3209 in favour of the @samp{-I} option.
3211 @item -L @var{max-lines}
3212 @itemx --max-lines@r{[}=@var{max-lines}@r{]}
3213 @itemx -l@r{[}@var{max-lines}@r{]}
3214 Use at most @var{max-lines} non-blank input lines per command line.
3215 For @samp{-l}, @var{max-lines} defaults to 1 if omitted. For
3216 @samp{-L}, the argument is mandatory. Trailing blanks cause an input
3217 line to be logically continued on the next input line, for the purpose
3218 of counting the lines. Implies @samp{-x}. The @samp{-l} form of this
3219 option is deprecated in favour of the POSIX-compliant @samp{-L}
3222 @item --max-args=@var{max-args}
3223 @itemx -n @var{max-args}
3224 Use at most @var{max-args} arguments per command line. Fewer than
3225 @var{max-args} arguments will be used if the size (see the @samp{-s}
3226 option) is exceeded, unless the @samp{-x} option is given, in which
3227 case @code{xargs} will exit.
3231 Prompt the user about whether to run each command line and read a line
3232 from the terminal. Only run the command line if the response starts
3233 with @samp{y} or @samp{Y}. Implies @samp{-t}.
3235 @item --no-run-if-empty
3237 If the standard input is completely empty, do not run the
3238 command. By default, the command is run once even if there is no
3241 @item --max-chars=@var{max-chars}
3242 @itemx -s @var{max-chars}
3243 Use at most @var{max-chars} characters per command line, including the
3244 command, initial arguments and any terminating nulls at the ends of
3245 the argument strings.
3248 Display the limits on the command-line length which are imposed by the
3249 operating system, @code{xargs}' choice of buffer size and the
3250 @samp{-s} option. Pipe the input from @file{/dev/null} (and perhaps
3251 specify @samp{--no-run-if-empty}) if you don't want @code{xargs} to do
3256 Print the command line on the standard error output before executing
3260 Print the version number of @code{xargs} and exit.
3264 Exit if the size (see the @samp{-s} option) is exceeded.
3267 @item --max-procs=@var{max-procs}
3268 @itemx -P @var{max-procs}
3269 Run simultaneously up to @var{max-procs} processes at once; the default is 1. If
3270 @var{max-procs} is 0, @code{xargs} will run as many processes as
3271 possible simultaneously.
3275 @node Regular Expressions, Environment Variables, Invoking xargs, Reference
3276 @section Regular Expressions
3278 The @samp{-regex} and @samp{-iregex} tests of @code{find} allow
3279 matching by regular expression, as does the @samp{--regex} option of
3280 @code{locate}. There are many different types of Regular Expression,
3281 but the type used by @code{find} and @code{locate} is the same as is
3282 used in GNU Emacs. Both programs provide an option which allows you
3283 to select an alternative regular expression syntax; for @code{find}
3284 this is the @samp{-regextype} option, and for @code{locate} this is
3285 the @samp{--regextype} option.
3287 These options take a single argument, which indicates the specific
3288 regular expression syntax and behaviour that should be used. This
3289 should be one of the following:
3291 @include regexprops.texi
3293 @node Environment Variables,, Regular Expressions, Reference
3294 @section Environment Variables
3297 Provides a default value for the internationalisation variables that
3300 If set to a non-empty string value, override the values of all the
3301 other internationalisation variables.
3303 The POSIX standard specifies that this variable affects the pattern
3304 matching to be used for the `\-name' option. GNU find uses the
3305 GNU version of the @code{fnmatch} library function.
3307 POSIX also specifies that the `LC_COLLATE' environment
3308 variable affects the interpretation of the user's response to the
3309 query issued by `\-ok', but this is not the case for GNU find.
3311 This variable affects the treatment of character classes used with
3312 the @samp{-name} test, if the system's
3313 @code{fnmatch} library function supports this. It has no effect on the behaviour
3314 of the @samp{-ok} expression.
3316 Determines the locale to be used for internationalised messages.
3318 Determines the location of the internationalisation message catalogues.
3320 Affects the directories which are searched to find the executables
3321 invoked by @samp{-exec}, @samp{-execdir} @samp{-ok} and @samp{-okdir}.
3322 If the @var{PATH} environment variable includes the current directory
3323 (by explicitly including @samp{.} or by having an empty element), and
3324 the find command line includes @samp{-execdir} or @samp{-okdir},
3325 @code{find} will refuse to run. @xref{Security Considerations}, for a
3326 more detailed discussion of security matters.
3328 @item POSIXLY_CORRECT
3329 Determines the block size used by @samp{-ls} and @samp{-fls}.
3330 If @var{POSIXLY_CORRECT} is set, blocks are units of 512 bytes. Otherwise
3331 they are units of 1024 bytes.
3334 Affects the time zone used for some of the time-related format
3335 directives of @samp{-printf} and @samp{-fprintf}.
3340 @node Common Tasks, Worked Examples, Reference, Top
3341 @chapter Common Tasks
3343 The sections that follow contain some extended examples that both give
3344 a good idea of the power of these programs, and show you how to solve
3345 common real-world problems.
3348 * Viewing And Editing::
3351 * Strange File Names::
3352 * Fixing Permissions::
3353 * Classifying Files::
3356 @node Viewing And Editing
3357 @section Viewing And Editing
3359 To view a list of files that meet certain criteria, simply run your
3360 file viewing program with the file names as arguments. Shells
3361 substitute a command enclosed in backquotes with its output, so the
3362 whole command looks like this:
3365 less `find /usr/include -name '*.h' | xargs grep -l mode_t`
3369 You can edit those files by giving an editor name instead of a file
3373 emacs `find /usr/include -name '*.h' | xargs grep -l mode_t`
3376 Because there is a limit to the length of any individual command line,
3377 there is a limit to the number of files that can be handled in this
3378 way. We can get around this difficulty by using xargs like this:
3381 find /usr/include -name '*.h' | xargs grep -l mode_t > todo
3382 xargs --arg-file=todo emacs
3385 Here, @code{xargs} will run @code{emacs} as many times as necessary to
3386 visit all of the files listed in the file @file{todo}.
3391 You can pass a list of files produced by @code{find} to a file
3392 archiving program. GNU @code{tar} and @code{cpio} can both read lists
3393 of file names from the standard input---either delimited by nulls (the
3394 safe way) or by blanks (the lazy, risky default way). To use
3395 null-delimited names, give them the @samp{--null} option. You can
3396 store a file archive in a file, write it on a tape, or send it over a
3397 network to extract on another machine.
3399 One common use of @code{find} to archive files is to send a list of
3400 the files in a directory tree to @code{cpio}. Use @samp{-depth} so if
3401 a directory does not have write permission for its owner, its contents
3402 can still be restored from the archive since the directory's
3403 permissions are restored after its contents. Here is an example of
3404 doing this using @code{cpio}; you could use a more complex @code{find}
3405 expression to archive only certain files.
3408 find . -depth -print0 |
3409 cpio --create --null --format=crc --file=/dev/nrst0
3412 You could restore that archive using this command:
3415 cpio --extract --null --make-dir --unconditional \
3416 --preserve --file=/dev/nrst0
3419 Here are the commands to do the same things using @code{tar}:
3422 find . -depth -print0 |
3423 tar --create --null --files-from=- --file=/dev/nrst0
3425 tar --extract --null --preserve-perm --same-owner \
3429 @c Idea from Rick Sladkey.
3430 Here is an example of copying a directory from one machine to another:
3433 find . -depth -print0 | cpio -0o -Hnewc |
3434 rsh @var{other-machine} "cd `pwd` && cpio -i0dum"
3438 @section Cleaning Up
3440 @c Idea from Jim Meyering.
3441 This section gives examples of removing unwanted files in various
3442 situations. Here is a command to remove the CVS backup files created
3443 when an update requires a merge:
3446 find . -name '.#*' -print0 | xargs -0r rm -f
3449 The command above works, but the following is safer:
3452 find . -name '.#*' -depth -delete
3455 @c Idea from Franc,ois Pinard.
3456 You can run this command to clean out your clutter in @file{/tmp}.
3457 You might place it in the file your shell runs when you log out
3458 (@file{.bash_logout}, @file{.logout}, or @file{.zlogout}, depending on
3459 which shell you use).
3462 find /tmp -depth -user "$LOGNAME" -type f -delete
3465 If your @code{find} command removes directories, you may find that
3466 you get a spurious error message when @code{find} tries to recurse
3467 into a directory that has now been removed. Using the @samp{-depth}
3468 option will normally resolve this problem.
3470 @c Idea from Noah Friedman.
3471 To remove old Emacs backup and auto-save files, you can use a command
3472 like the following. It is especially important in this case to use
3473 null-terminated file names because Emacs packages like the VM mailer
3474 often create temporary file names with spaces in them, like
3475 @file{#reply to David J. MacKenzie<1>#}.
3478 find ~ \( -name '*~' -o -name '#*#' \) -print0 |
3479 xargs --no-run-if-empty --null rm -vf
3482 Removing old files from @file{/tmp} is commonly done from @code{cron}:
3484 @c Idea from Kaveh Ghazi.
3486 find /tmp /var/tmp -not -type d -mtime +3 -delete
3487 find /tmp /var/tmp -depth -mindepth 1 -type d -empty -delete
3490 The second @code{find} command above uses @samp{-depth} so it cleans
3491 out empty directories depth-first, hoping that the parents become
3492 empty and can be removed too. It uses @samp{-mindepth} to avoid
3493 removing @file{/tmp} itself if it becomes totally empty.
3495 @node Strange File Names
3496 @section Strange File Names
3499 @c From: tmatimar@isgtec.com (Ted Timar)
3500 @c Newsgroups: comp.unix.questions,comp.unix.shell,comp.answers,news.answers
3501 @c Subject: Unix - Frequently Asked Questions (2/7) [Frequent posting]
3502 @c Subject: How do I remove a file with funny characters in the filename ?
3503 @c Date: Thu Mar 18 17:16:55 EST 1993
3504 @code{find} can help you remove or rename a file with strange
3505 characters in its name. People are sometimes stymied by files whose
3506 names contain characters such as spaces, tabs, control characters, or
3507 characters with the high bit set. The simplest way to remove such
3511 rm -i @var{some*pattern*that*matches*the*problem*file}
3514 @code{rm} asks you whether to remove each file matching the given
3515 pattern. If you are using an old shell, this approach might not work
3516 if the file name contains a character with the high bit set; the shell
3517 may strip it off. A more reliable way is:
3520 find . -maxdepth 1 @var{tests} -okdir rm '@{@}' \;
3524 where @var{tests} uniquely identify the file. The @samp{-maxdepth 1}
3525 option prevents @code{find} from wasting time searching for the file
3526 in any subdirectories; if there are no subdirectories, you may omit
3527 it. A good way to uniquely identify the problem file is to figure out
3528 its inode number; use
3534 Suppose you have a file whose name contains control characters, and
3535 you have found that its inode number is 12345. This command prompts
3536 you for whether to remove it:
3539 find . -maxdepth 1 -inum 12345 -okdir rm -f '@{@}' \;
3542 If you don't want to be asked, perhaps because the file name may
3543 contain a strange character sequence that will mess up your screen
3544 when printed, then use @samp{-execdir} instead of @samp{-okdir}.
3546 If you want to rename the file instead, you can use @code{mv} instead
3550 find . -maxdepth 1 -inum 12345 -okdir mv '@{@}' @var{new-file-name} \;
3553 @node Fixing Permissions
3554 @section Fixing Permissions
3556 Suppose you want to make sure that everyone can write to the
3557 directories in a certain directory tree. Here is a way to find
3558 directories lacking either user or group write permission (or both),
3559 and fix their permissions:
3562 find . -type d -not -perm -ug=w | xargs chmod ug+w
3566 You could also reverse the operations, if you want to make sure that
3567 directories do @emph{not} have world write permission.
3569 @node Classifying Files
3570 @section Classifying Files
3573 @c From: martin@mwtech.UUCP (Martin Weitzel)
3574 @c Newsgroups: comp.unix.wizards,comp.unix.questions
3575 @c Subject: Advanced usage of 'find' (Re: Unix security automating script)
3576 @c Date: 22 Mar 90 15:05:19 GMT
3577 If you want to classify a set of files into several groups based on
3578 different criteria, you can use the comma operator to perform multiple
3579 independent tests on the files. Here is an example:
3582 find / -type d \( -perm -o=w -fprint allwrite , \
3583 -perm -o=x -fprint allexec \)
3585 echo "Directories that can be written to by everyone:"
3588 echo "Directories with search permissions for everyone:"
3592 @code{find} has only to make one scan through the directory tree
3593 (which is one of the most time consuming parts of its work).
3595 @node Worked Examples, Security Considerations, Common Tasks, Top
3596 @chapter Worked Examples
3598 The tools in the findutils package, and in particular @code{find},
3599 have a large number of options. This means that quite often,
3600 there is more than one way to do things. Some of the options
3601 and facilities only exist for compatibility with other tools, and
3602 findutils provides improved ways of doing things.
3604 This chapter describes a number of useful tasks that are commonly
3605 performed, and compares the different ways of achieving them.
3609 * Updating A Timestamp File::
3612 @node Deleting Files
3613 @section Deleting Files
3615 One of the most common tasks that @code{find} is used for is locating
3616 files that can be deleted. This might include:
3620 Files last modified more than 3 years ago which haven't been accessed
3621 for at least 2 years
3623 Files belonging to a certain user
3625 Temporary files which are no longer required
3628 This example concentrates on the actual deletion task rather than on
3629 sophisticated ways of locating the files that need to be deleted.
3630 We'll assume that the files we want to delete are old files underneath
3631 @file{/var/tmp/stuff}.
3633 @subsection The Traditional Way
3635 The traditional way to delete files in @file{var/tmp/stuff} that have
3636 not been modified in over 90 days would have been:
3639 find /var/tmp/stuff -mtime +90 -exec /bin/rm @{@} \;
3642 The above command uses @samp{-exec} to run the @code{/bin/rm} command
3643 to remove each file. This approach works and in fact would have
3644 worked in Version 7 Unix in 1979. However, there are a number of
3645 problems with this approach.
3648 The most obvious problem with the approach above is that it causes
3649 @code{find} to fork every time it finds a file that needs to delete,
3650 and the child process then has to use the @code{exec} system call to
3651 launch @code{/bin/rm}. All this is quite inefficient. If we are
3652 going to use @code{/bin/rm} to do this job, it is better to make it
3653 delete more than one file at a time.
3655 The most obvious way of doing this is to use the shell's command
3659 /bin/rm `find /var/tmp/stuff -mtime +90 -print`
3661 or you could use the more modern form
3663 /bin/rm $(find /var/tmp/stuff -mtime +90 -print)
3666 The commands above are much more efficient than the first attempt.
3667 However, there is a problem with them. The shell has a maximum
3668 command length which is imposed by the operating system (the actual
3669 limit varies between systems). This means that while the command
3670 expansion technique will usually work, it will suddenly fail when
3671 there are lots of files to delete. Since the task is to delete
3672 unwanted files, this is precisely the time we don't want things to go
3675 @subsection Making Use of xargs
3677 So, is there a way to be more efficient in the use of @code{fork()}
3678 and @code{exec()} without running up against this limit?
3679 Yes, we can be almost optimally efficient by making use
3680 of the @code{xargs} command. The @code{xargs} command reads arguments
3681 from its standard input and builds them into command lines. We can
3685 find /var/tmp/stuff -mtime +90 -print | xargs /bin/rm
3688 For example if the files found by @code{find} are
3689 @file{/var/tmp/stuff/A},
3690 @file{/var/tmp/stuff/B} and
3691 @file{/var/tmp/stuff/C} then @code{xargs} might issue the commands
3694 /bin/rm /var/tmp/stuff/A /var/tmp/stuff/B
3695 /bin/rm /var/tmp/stuff/C
3698 The above assumes that @code{xargs} has a very small maximum command
3699 line length. The real limit is much larger but the idea is that
3700 @code{xargs} will run @code{/bin/rm} as many times as necessary to get
3701 the job done, given the limits on command line length.
3703 This usage of @code{xargs} is pretty efficient, and the @code{xargs}
3704 command is widely implemented (all modern versions of Unix offer it).
3705 So far then, the news is all good. However, there is bad news too.
3707 @subsection Unusual characters in filenames
3709 Unix-like systems allow any characters to appear in file names with
3710 the exception of the ASCII NUL character and the backslash.
3711 Backslashes can occur in path names (as the directory separator) but
3712 not in the names of actual directory entries. This means that the
3713 list of files that @code{xargs} reads could in fact contain white space
3714 characters --- spaces, tabs and newline characters. Since by default,
3715 @code{xargs} assumes that the list of files it is reading uses white
3716 space as an argument separator, it cannot correctly handle the case
3717 where a filename actually includes white space. This makes the
3718 default behaviour of @code{xargs} almost useless for handling
3721 To solve this problem, GNU findutils introduced the @samp{-print0}
3722 action for @code{find}. This uses the ASCII NUL character to separate
3723 the entries in the file list that it produces. This is the ideal
3724 choice of separator since it is the only character that cannot appear
3725 within a path name. The @samp{-0} option to @code{xargs} makes it
3726 assume that arguments are separated with ASCII NUL instead of white
3727 space. It also turns off another misfeature in the default behaviour
3728 of @code{xargs}, which is that it pays attention to quote characters
3729 in its input. Some versions of @code{xargs} also terminate when they
3730 see a lone @samp{_} in the input, but GNU @code{find} no longer does
3731 that (since it has become an optional behaviour in the Unix standard).
3733 So, putting @code{find -print0} together with @code{xargs -0} we get
3737 find /var/tmp/stuff -mtime +90 -print0 | xargs -0 /bin/rm
3740 The result is an efficient way of proceeding that
3741 correctly handles all the possible characters that could appear in the
3742 list of files to delete. This is good news. However, there is, as
3743 I'm sure you're expecting, also more bad news. The problem is that
3744 this is not a portable construct; although other versions of Unix
3745 (notable BSD-derived ones) support @samp{-print0}, it's not
3746 universal. So, is there a more universal mechanism?
3748 @subsection Going back to -exec
3750 There is indeed a more universal mechanism, which is a slight
3751 modification to the @samp{-exec} action. The normal @samp{-exec}
3752 action assumes that the command to run is terminated with a semicolon
3753 (the semicolon normally has to be quoted in order to protect it from
3754 interpretation as the shell command separator). The SVR4 edition of
3755 Unix introduced a slight variation, which involves terminating the
3756 command with @samp{+} instead:
3759 find /var/tmp/stuff -mtime +90 -exec /bin/rm @{@} \+
3762 The above use of @samp{-exec} causes @code{find} to build up a long
3763 command line and then issue it. This can be less efficient than some
3764 uses of @code{xargs}; for example @code{xargs} allows new command
3765 lines to be built up while the previous command is still executing, and
3766 allows you to specify a number of commands to run in parallel.
3767 However, the @code{find @dots{} -exec @dots{} +} construct has the advantage
3768 of wide portability. GNU findutils did not support @samp{-exec @dots{} +}
3769 until version 4.2.12; one of the reasons for this is that it already
3770 had the @samp{-print0} action in any case.
3773 @subsection A more secure version of -exec
3775 The command above seems to be efficient and portable. However,
3776 within it lurks a security problem. The problem is shared with
3777 all the commands we've tried in this worked example so far, too. The
3778 security problem is a race condition; that is, if it is possible for
3779 somebody to manipulate the filesystem that you are searching while you
3780 are searching it, it is possible for them to persuade your @code{find}
3781 command to cause the deletion of a file that you can delete but they
3784 The problem occurs because the @samp{-exec} action is defined by the
3785 @acronym{POSIX} standard to invoke its command with the same working directory
3786 as @code{find} had when it was started. This means that the arguments
3787 which replace the @{@} include a relative path from @code{find}'s
3788 starting point down the file that needs to be deleted. For example,
3791 find /var/tmp/stuff -mtime +90 -exec /bin/rm @{@} \+
3794 might actually issue the command:
3797 /bin/rm /var/tmp/stuff/A /var/tmp/stuff/B /var/tmp/stuff/passwd
3800 Notice the file @file{/var/tmp/stuff/passwd}. Likewise, the command:
3803 cd /var/tmp && find stuff -mtime +90 -exec /bin/rm @{@} \+
3806 might actually issue the command:
3809 /bin/rm stuff/A stuff/B stuff/passwd
3812 If an attacker can rename @file{stuff} to something else (making use
3813 of their write permissions in @file{/var/tmp}) they can replace it
3814 with a symbolic link to @file{/etc}. That means that the
3815 @code{/bin/rm} command will be invoked on @file{/etc/passwd}. If you
3816 are running your @code{find} command as root, the attacker has just managed
3817 to delete a vital file. All they needed to do to achieve this was
3818 replace a subdirectory with a symbolic link at the vital moment.
3820 There is however, a simple solution to the problem. This is an action
3821 which works a lot like @code{-exec} but doesn't need to traverse a
3822 chain of directories to reach the file that it needs to work on. This
3823 is the @samp{-execdir} action, which was introduced by the BSD family
3824 of operating systems. The command,
3827 find /var/tmp/stuff -mtime +90 -execdir /bin/rm @{@} \+
3830 might delete a set of files by performing these actions:
3834 Change directory to /var/tmp/stuff/foo
3836 Invoke @code{/bin/rm ./file1 ./file2 ./file3}
3838 Change directory to /var/tmp/stuff/bar
3840 Invoke @code{/bin/rm ./file99 ./file100 ./file101}
3843 This is a much more secure method. We are no longer exposed to a race
3844 condition. For many typical uses of @code{find}, this is the best
3845 strategy. It's reasonably efficient, but the length of the command
3846 line is limited not just by the operating system limits, but also by
3847 how many files we actually need to delete from each directory.
3849 Is it possible to do any better? In the case of general file
3850 processing, no. However, in the specific case of deleting files it is
3851 indeed possible to do better.
3853 @subsection Using the -delete action
3855 The most efficient and secure method of solving this problem is to use
3856 the @samp{-delete} action:
3859 find /var/tmp/stuff -mtime +90 -delete
3862 This alternative is more efficient than any of the @samp{-exec} or
3863 @samp{-execdir} actions, since it entirely avoids the overhead of
3864 forking a new process and using @code{exec} to run @code{/bin/rm}. It
3865 is also normally more efficient than @code{xargs} for the same
3866 reason. The file deletion is performed from the directory containing
3867 the entry to be deleted, so the @samp{-delete} action has the same
3868 security advantages as the @samp{-execdir} action has.
3870 The @samp{-delete} action was introduced by the BSD family of
3873 @subsection Improving things still further
3875 Is it possible to improve things still further? Not without either
3876 modifying the system library to the operating system or having more specific
3877 knowledge of the layout of the filesystem and disk I/O subsystem, or
3880 The @code{find} command traverses the filesystem, reading
3881 directories. It then issues a separate system call for each file to
3882 be deleted. If we could modify the operating system, there are
3883 potential gains that could be made:
3887 We could have a system call to which we pass more than one filename
3890 Alternatively, we could pass in a list of inode numbers (on GNU/Linux
3891 systems, @code{readdir()} also returns the inode number of each
3892 directory entry) to be deleted.
3895 The above possibilities sound interesting, but from the kernel's point
3896 of view it is difficult to enforce standard Unix access controls for
3897 such processing by inode number. Such a facility would probably
3898 need to be restricted to the superuser.
3900 Another way of improving performance would be to increase the
3901 parallelism of the process. For example if the directory hierarchy we
3902 are searching is actually spread across a number of disks, we might
3903 somehow be able to arrange for @code{find} to process each disk in
3904 parallel. In practice GNU @code{find} doesn't have such an intimate
3905 understanding of the system's filesystem layout and disk I/O
3908 However, since the system administrator can have such an understanding
3909 they can take advantage of it like so:
3912 find /var/tmp/stuff1 -mtime +90 -delete &
3913 find /var/tmp/stuff2 -mtime +90 -delete &
3914 find /var/tmp/stuff3 -mtime +90 -delete &
3915 find /var/tmp/stuff4 -mtime +90 -delete &
3919 In the example above, four separate instances of @code{find} are used
3920 to search four subdirectories in parallel. The @code{wait} command
3921 simply waits for all of these to complete. Whether this approach is
3922 more or less efficient than a single instance of @code{find} depends
3923 on a number of things:
3927 Are the directories being searched in parallel actually on separate
3928 disks? If not, this parallel search might just result in a lot of
3929 disk head movement and so the speed might even be slower.
3931 Other activity - are other programs also doing things on those disks?
3935 @subsection Conclusion
3937 The fastest and most secure way to delete files with the help of
3938 @code{find} is to use @samp{-delete}. Using @code{xargs -0 -P N} can
3939 also make effective use of the disk, but it is not as secure.
3941 In the case where we're doing things other than deleting files, the
3942 most secure alternative is @samp{-execdir @dots{} +}, but this is not as
3943 portable as the insecure action @samp{-exec @dots{} +}.
3945 The @samp{-delete} action is not completely portable, but the only
3946 other possibility which is as secure (@samp{-execdir}) is no more
3947 portable. The most efficient portable alternative is @samp{-exec
3948 @dots{}+}, but this is insecure and isn't supported by versions of GNU
3949 findutils prior to 4.2.12.
3952 @node Updating A Timestamp File
3953 @section Updating A Timestamp File
3955 Suppose we have a directory full of files which is maintained with a
3956 set of automated tools; perhaps one set of tools updates them and
3957 another set of tools uses the result. In this situation, it might be
3958 useful for the second set of tools to know if the files have recently
3959 been changed. It might be useful, for example, to have a 'timestamp'
3960 file which gives the timestamp on the newest file in the collection.
3962 We can use @code{find} to achieve this, but there are several
3963 different ways to do it.
3965 @subsection Updating the Timestamp The Wrong Way
3967 The obvious but wrong answer is just to use @samp{-newer}:-
3970 find subdir -newer timestamp -exec touch -r @{@} timestamp \;
3973 This does the right sort of thing but has a bug. Suppose that two
3974 files in the subdirectory have been updated, and that these are called
3975 @file{file1} and @file{file2}. The command above will update
3976 @file{timestamp} with the modification time of @file{file1} or that of
3977 @file{file2}, but we don't know which one. Since the timestamps on
3978 @file{file1} and @file{file2} will in general be different, this could
3979 well be the wrong value.
3981 One solution to this problem is to modify @code{find} to recheck the
3982 modification time of @file{timestamp} every time a file is to be
3983 compared against it, but that will reduce the performance of
3986 @subsection Using the test utility to compare timestamps
3988 The @code{test} command can be used to compare timestamps:
3991 find subdir -exec test @{@} -nt timestamp \; -exec touch -r @{@} timestamp \;
3994 This will ensure that any changes made to the modification time of
3995 @file{timestamp} that take place during the execution of @code{find}
3996 are taken into account. This resolves our earlier problem, but
3997 unfortunately this runs much more slowly.
3999 @subsection A combined approach
4001 We can of course still use @samp{-newer} to cut down on the number of
4002 calls to @code{test}:
4005 find subdir -newer timestamp -a \
4006 -exec test @{@} -nt timestamp \; -a \
4007 -exec touch -r @{@} timestamp \;
4010 Here, the @samp{-newer} test excludes all the files which are
4011 definitely older than the timestamp, but all the files which are newer
4012 than the old value of the timestamp are compared against the current
4015 This is indeed faster in general, but the speed difference will depend
4016 on how many updated files there are.
4018 @subsection Using -printf and sort to compare timestamps
4020 It is possible to use the @samp{-printf} action to abandon the use of
4021 @code{test} entirely:
4024 newest=$(find subdir -newer timestamp -printf "%A@:%p\n" |
4028 touch -r "$@{newest:-timestamp@}" timestamp
4031 The command above works by generating a list of the timestamps and
4032 names of all the files which are newer than the timestamp. The
4033 @code{sort}, @code{tail} and @code{cut} commands simply pull out the
4034 name of the file with the largest timestamp value (that is, the latest
4035 file). The @code{touch} command is then used to update the timestamp,
4037 The @code{"$@{newest:-timestamp@}"} expression simply expands to the
4038 value of @code{$newest} if that variable is set, but to
4039 @file{timestamp} otherwise. This ensures that an argument is always
4040 given to the @samp{-r} option of the @code{touch} command.
4042 This approach seems quite efficient, but unfortunately it has a bug.
4043 Many operating systems now keep file modification time information at
4044 a granularity which is finer than one second. Unfortunately the
4045 @samp{%A@@} format for @samp{-printf} only prints a whole-number value
4046 currently; that is, these values are at a one-second granularity.
4047 This means that in our example above, @samp{$newest} will be the name
4048 of a file which is no more than one second older than the newest file,
4049 but may indeed be older.
4051 It would be possible to solve this problem with some kind of loop:
4055 newest=$(find subdir -newer timestamp -printf "%A@@:%p\n" |
4059 if test -z "$newest" ; then
4062 touch -r "$newest" timestamp
4067 A better fix for this problem would be to allow the @samp{%A@@} format
4068 to produce a result having a fractional part, too. While this is
4069 planned for GNU @code{find}, it hasn't been done yet.
4071 @subsection Coping with sub-second timestamp resolution
4073 Another tool which often works with timestamps is @code{make}. We can
4074 use @code{find} to generate a @file{Makefile} file on the fly and then
4075 use @code{make} to update the timestamps:
4082 -printf "timestamp:: %p\n\ttouch -r %p timestamp\n\n" > "$makefile"
4087 Unfortunately although the solution above is quite elegant, it fails
4088 to cope with white space within file names, and adjusting it to do so
4089 would require a rather complex shell script.
4092 @subsection Coping with odd filenames too
4094 We can fix both of these problems (looping and problems with white
4095 space), and do things more efficiently too. The following command
4096 works with newlines and doesn't need to sort the list of filenames.
4099 find subdir -newer timestamp -printf "%A@@:%p\0" |
4101 xargs --no-run-if-empty --null -i \
4102 find @{@} -maxdepth 0 -newer timestamp -exec touch -r @{@} timestamp \;
4105 The first @code{find} command generates a list of files which are
4106 newer than the original timestamp file, and prints a list of them with
4107 their timestamps. The @file{newest.pl} script simply filters out all
4108 the filenames which have timestamps which are older than whatever the
4115 my $latest_stamp = undef;
4117 my ($stamp, $name) = split(/:/);
4118 if (!defined($latest_stamp) || ($tstamp > $latest_stamp)) {
4119 $latest_stamp = $stamp;
4122 if ($tstamp >= $latest_stamp) {
4123 push @newest, $name;
4126 print join("\0", @newest);
4130 This prints a list of zero or more files, all of which are newer than
4131 the original timestamp file, and which have the same timestamp as each
4132 other, to the nearest second. The second @code{find} command takes
4133 each resulting file one at a time, and if that is newer than the
4134 timestamp file, the timestamp is updated.
4136 @node Security Considerations, Error Messages, Worked Examples, Top
4137 @chapter Security Considerations
4139 Security considerations are important if you are using @code{find} or
4140 @code{xargs} to search for or process files that don't belong to you
4141 or which other people have control. Security considerations
4142 relating to @code{locate} may also apply if you have files which you
4143 do not want others to see.
4145 The most severe forms of security problems affecting
4146 @code{find} and related programs are when third parties bring
4147 about a situation allowing them to do something
4148 they would normally not be able to accomplish. This is called @emph{privilege
4149 elevation}. This might include deleting files they would not normally
4150 be able to delete. It is common for the operating system to periodically
4151 invoke @code{find} for self-maintenance purposes. These invocations of
4152 @code{find} are particularly problematic from a security point of view
4153 as these are often invoked by the superuser and search the entire
4154 filesystem hierarchy. Generally, the severity of any associated problem depends
4155 on what the system is going to do with the files found by @code{find}.
4158 * Levels of Risk:: What is your level of exposure to security problems?
4159 * Security Considerations for find:: Security problems with find
4160 * Security Considerations for xargs:: Security problems with xargs
4161 * Security Considerations for locate:: Security problems with locate
4162 * Security Summary:: That was all very complex, what does it boil down to?
4166 @node Levels of Risk
4167 @section Levels of Risk
4169 There are some security risks inherent in the use of @code{find},
4170 @code{xargs} and (to a lesser extent) @code{locate}. The severity of
4171 these risks depends on what sort of system you are using:
4175 Multi-user systems where you do not control (or trust) the other
4176 users, and on which you execute @code{find}, including areas where
4177 those other users can manipulate the filesystem (for example beneath
4178 @file{/home} or @file{/tmp}).
4181 Systems where the actions of other users can create file names chosen
4182 by them, but to which they don't have access while @code{find} is
4183 being run. This access might include leaving programs running (shell
4184 background jobs, @code{at} or @code{cron} tasks, for example). On
4185 these sorts of systems, carefully written commands (avoiding use of
4186 @samp{-print} for example) should not expose you to a high degree of
4187 risk. Most systems fall into this category.
4190 Systems to which untrusted parties do not have access, cannot create
4191 file names of their own choice (even remotely) and which contain no
4192 security flaws which might enable an untrusted third party to gain
4193 access. Most systems do not fall into this category because there are
4194 many ways in which external parties can affect the names of files that
4195 are created on your system. The system on which I am writing this for
4196 example automatically downloads software updates from the Internet;
4197 the names of the files in which these updates exist are chosen by
4198 third parties@footnote{Of course, I trust these parties to a large
4199 extent anyway, because I install software provided by them; I choose
4200 to trust them in this way, and that's a deliberate choice}.
4203 In the discussion above, ``risk'' denotes the likelihood that someone
4204 can cause @code{find}, @code{xargs}, @code{locate} or some other
4205 program which is controlled by them to do something you did not
4206 intend. The levels of risk suggested do not take any account of the
4207 consequences of this sort of event. That is, if you operate a ``low
4208 risk'' type system, but the consequences of a security problem are
4209 disastrous, then you should still give serious thought to all the
4210 possible security problems, many of which of course will not be
4211 discussed here -- this section of the manual is intended to be
4212 informative but not comprehensive or exhaustive.
4214 If you are responsible for the operation of a system where the
4215 consequences of a security problem could be very important, you should
4219 @item Define a security policy which defines who is allowed to do what
4221 @item Seek competent advice on how to enforce your policy, detect
4222 breaches of that policy, and take account of any potential problems
4223 that might fall outside the scope of your policy.
4227 @node Security Considerations for find
4228 @section Security Considerations for @code{find}
4231 Some of the actions @code{find} might take have a direct effect;
4232 these include @code{-exec} and @code{-delete}. However, it is also
4233 common to use @code{-print} explicitly or implicitly, and so if
4234 @code{find} produces the wrong list of file names, that can also be a
4235 security problem; consider the case for example where @code{find} is
4236 producing a list of files to be deleted.
4238 We normally assume that the @code{find} command line expresses the
4239 file selection criteria and actions that the user had in mind -- that
4240 is, the command line is ``trusted'' data.
4242 From a security analysis point of view, the output of @code{find}
4243 should be correct; that is, the output should contain only the names
4244 of those files which meet the user's criteria specified on the command
4245 line. This applies for the @code{-exec} and @code{-delete} actions;
4246 one can consider these to be part of the output.
4248 On the other hand, the contents of the filesystem can be manipulated
4249 by other people, and hence we regard this as ``untrusted'' data. This
4250 implies that the @code{find} command line is a filter which converts
4251 the untrusted contents of the filesystem into a correct list of output
4254 The filesystem will in general change while @code{find} is searching
4255 it; in fact, most of the potential security problems with @code{find}
4256 relate to this issue in some way.
4258 @dfn{Race conditions} are a general class of security problem where the
4259 relative ordering of actions taken by @code{find} (for example) and
4260 something else are critically important in getting the correct and expected result@footnote{This is more or less the
4261 definition of the term ``race condition''} .
4263 For @code{find}, an attacker might move or rename files or directories in
4264 the hope that an action might be taken against a file which was not
4265 normally intended to be affected. Alternatively, this sort of attack
4266 might be intended to persuade @code{find} to search part of the
4267 filesystem which would not normally be included in the search
4268 (defeating the @code{-prune} action for example).
4271 * Problems with -exec and filenames::
4272 * Changing the Current Working Directory::
4273 * Race Conditions with -exec::
4274 * Race Conditions with -print and -print0::
4277 @node Problems with -exec and filenames
4278 @subsection Problems with -exec and filenames
4280 It is safe in many cases to use the @samp{-execdir} action with any
4281 file name. Because @samp{-execdir} prefixes the arguments it passes
4282 to programs with @samp{./}, you will not accidentally pass an argument
4283 which is interpreted as an option. For example the file @file{-f}
4284 would be passed to @code{rm} as @file{./-f}, which is harmless.
4286 However, your degree of safety does depend on the nature of the
4287 program you are running. For example constructs such as these two commands
4290 find -exec sh -c "something @{@}" \;
4291 find -execdir sh -c "something @{@}" \;
4294 are very dangerous. The reason for this is that the @samp{@{@}} is
4295 expanded to a filename which might contain a semicolon or other
4296 characters special to the shell. If for example someone creates the
4297 file @file{/tmp/foo; rm -rf $HOME} then the two commands above could
4298 delete someone's home directory.
4300 So for this reason do not run any command which will pass untrusted
4301 data (such as the names of files) to commands which interpret
4302 arguments as commands to be further interpreted (for example
4305 @node Changing the Current Working Directory
4306 @subsection Changing the Current Working Directory
4308 As @code{find} searches the filesystem, it finds subdirectories and
4309 then searches within them by changing its working directory. First,
4310 @code{find} reaches and recognises a subdirectory. It then decides if that
4311 subdirectory meets the criteria for being searched; that is, any
4312 @samp{-xdev} or @samp{-prune} expressions are taken into account. The
4313 @code{find} program will then change working directory and proceed to
4314 search the directory.
4316 A race condition attack might take the form that once the checks
4317 relevant to @samp{-xdev} and @samp{-prune} have been done, an attacker
4318 might rename the directory that was being considered, and put in its
4319 place a symbolic link that actually points somewhere else.
4321 The idea behind this attack is to fool @code{find} into going into the
4322 wrong directory. This would leave @code{find} with a working
4323 directory chosen by an attacker, bypassing any protection apparently
4324 provided by @samp{-xdev} and @samp{-prune}, and any protection
4325 provided by being able to @emph{not} list particular directories on
4326 the @code{find} command line. This form of attack is particularly
4327 problematic if the attacker can predict when the @code{find} command
4328 will be run, as is the case with @code{cron} tasks for example.
4330 GNU @code{find} has specific safeguards to prevent this general class
4331 of problem. The exact form of these safeguards depends on the
4332 properties of your system.
4335 * O_NOFOLLOW:: Safely changing directory using fchdir().
4336 * Systems without O_NOFOLLOW:: Checking for symbolic links after chdir().
4340 @subsubsection O_NOFOLLOW
4342 If your system supports the O_NOFOLLOW flag @footnote{GNU/Linux
4343 (kernel version 2.1.126 and later) and FreeBSD (3.0-CURRENT and later)
4344 support this} to the @code{open(2)} system call, @code{find} uses it
4345 when safely changing directory. The target directory is first opened
4346 and then @code{find} changes working directory with the
4347 @code{fchdir()} system call. This ensures that symbolic links are not
4348 followed, preventing the sort of race condition attack in which use
4349 is made of symbolic links.
4351 If for any reason this approach does not work, @code{find} will fall
4352 back on the method which is normally used if O_NOFOLLOW is not
4355 You can tell if your system supports O_NOFOLLOW by running
4361 This will tell you the version number and which features are enabled.
4362 For example, if I run this on my system now, this gives:
4364 GNU find version 4.2.18-CVS
4365 Features enabled: D_TYPE O_NOFOLLOW(enabled)
4368 Here, you can see that I am running a version of @code{find} which was
4369 built from the development (CVS) code prior to the release of
4370 findutils-4.2.18, and that the D_TYPE and O_NOFOLLOW features are
4371 present. O_NOFOLLOW is qualified with ``enabled''. This simply means
4372 that the current system seems to support O_NOFOLLOW. This check is
4373 needed because it is possible to build @code{find} on a system that
4374 defines O_NOFOLLOW and then run it on a system that ignores the
4375 O_NOFOLLOW flag. We try to detect such cases at startup by checking
4376 the operating system and version number; when this happens you will
4377 see ``O_NOFOLLOW(disabled)'' instead.
4379 @node Systems without O_NOFOLLOW
4380 @subsubsection Systems without O_NOFOLLOW
4382 The strategy for preventing this type of problem on systems that lack
4383 support for the O_NOFOLLOW flag is more complex. Each time
4384 @code{find} changes directory, it examines the directory it is about
4385 to move to, issues the @code{chdir()} system call, and then checks
4386 that it has ended up in the subdirectory it expected. If all is as
4387 expected, processing continues as normal. However, there are two main
4388 reasons why the directory might change: the use of an automounter and
4389 the someone removing the old directory and replacing it with something
4390 else while @code{find} is trying to descend into it.
4392 Where a filesystem ``automounter'' is in use it can be the case that
4393 the use of the @code{chdir()} system call can itself cause a new
4394 filesystem to be mounted at that point. On systems that do not
4395 support O_NOFOLLOW, this will cause @code{find}'s security check to
4398 However, this does not normally represent a security problem, since
4399 the automounter configuration is normally set up by the system
4400 administrator. Therefore, if the @code{chdir()} sanity check fails,
4401 @code{find} will make one more attempt. If that succeeds, execution
4402 carries on as normal. This is the usual case for automounters.
4404 Where an attacker is trying to exploit a race condition, the problem
4405 may not have gone away on the second attempt. If this is the case,
4406 @code{find} will issue a warning message and then ignore that
4407 subdirectory. When this happens, actions such as @samp{-exec} or
4408 @samp{-print} may already have taken place for the problematic
4409 subdirectory. This is because @code{find} applies tests and actions
4410 to directories before searching within them (unless @samp{-depth} was
4413 Because of the nature of the directory-change operation and security
4414 check, in the worst case the only things that @code{find} would have
4415 done with the directory are to move into it and back out to the
4416 original parent. No operations would have been performed within that
4419 @node Race Conditions with -exec
4420 @subsection Race Conditions with -exec
4422 The @samp{-exec} action causes another program to be run. It passes
4423 to the program the name of the file which is being considered at the
4424 time. The invoked program will typically then perform some action
4425 on that file. Once again, there is a race condition which can be
4426 exploited here. We shall take as a specific example the command
4429 find /tmp -path /tmp/umsp/passwd -exec /bin/rm
4432 In this simple example, we are identifying just one file to be deleted
4433 and invoking @code{/bin/rm} to delete it. A problem exists because
4434 there is a time gap between the point where @code{find} decides that
4435 it needs to process the @samp{-exec} action and the point where the
4436 @code{/bin/rm} command actually issues the @code{unlink()} system
4437 call to delete the file from the filesystem. Within this time period, an attacker can rename the
4438 @file{/tmp/umsp} directory, replacing it with a symbolic link to
4439 @file{/etc}. There is no way for @code{/bin/rm} to determine that it
4440 is working on the same file that @code{find} had in mind. Once the
4441 symbolic link is in place, the attacker has persuaded @code{find} to
4442 cause the deletion of the @file{/etc/passwd} file, which is not the
4443 effect intended by the command which was actually invoked.
4445 One possible defence against this type of attack is to modify the
4446 behaviour of @samp{-exec} so that the @code{/bin/rm} command is run
4447 with the argument @file{./passwd} and a suitable choice of working
4448 directory. This would allow the normal sanity check that @code{find}
4449 performs to protect against this form of attack too. Unfortunately,
4450 this strategy cannot be used as the POSIX standard specifies that the
4451 current working directory for commands invoked with @samp{-exec} must
4452 be the same as the current working directory from which @code{find}
4453 was invoked. This means that the @samp{-exec} action is inherently
4454 insecure and can't be fixed.
4456 GNU @code{find} implements a more secure variant of the @samp{-exec}
4457 action, @samp{-execdir}. The @samp{-execdir} action
4458 ensures that it is not necessary to dereference subdirectories to
4459 process target files. The current directory used to invoke programs
4460 is the same as the directory in which the file to be processed exists
4461 (@file{/tmp/umsp} in our example, and only the basename of the file to
4462 be processed is passed to the invoked command, with a @samp{./}
4463 prepended (giving @file{./passwd} in our example).
4465 The @samp{-execdir} action refuses to do anything if the current
4466 directory is included in the @var{$PATH} environment variable. This
4467 is necessary because @samp{-execdir} runs programs in the same
4468 directory in which it finds files -- in general, such a directory
4469 might be writable by untrusted users. For similar reasons,
4470 @samp{-execdir} does not allow @samp{@{@}} to appear in the name of
4471 the command to be run.
4473 @node Race Conditions with -print and -print0
4474 @subsection Race Conditions with -print and -print0
4476 The @samp{-print} and @samp{-print0} actions can be used to produce a
4477 list of files matching some criteria, which can then be used with some
4478 other command, perhaps with @code{xargs}. Unfortunately, this means
4479 that there is an unavoidable time gap between @code{find} deciding
4480 that one or more files meet its criteria and the relevant command
4481 being executed. For this reason, the @samp{-print} and @samp{-print0}
4482 actions are just as insecure as @samp{-exec}.
4484 In fact, since the construction
4487 find @dots{} -print | xargs @enddots{}
4490 does not cope correctly with newlines or other ``white space'' in
4491 file names, and copes poorly with file names containing quotes, the
4492 @samp{-print} action is less secure even than @samp{-print0}.
4495 @comment node-name, next, previous, up
4496 @comment @node Security Considerations for xargs
4497 @node Security Considerations for xargs
4498 @section Security Considerations for @code{xargs}
4500 The description of the race conditions affecting the @samp{-print}
4501 action of @code{find} shows that @code{xargs} cannot be secure if it
4502 is possible for an attacker to modify a filesystem after @code{find}
4503 has started but before @code{xargs} has completed all its actions.
4505 However, there are other security issues that exist even if it is not
4506 possible for an attacker to have access to the filesystem in real
4507 time. Firstly, if it is possible for an attacker to create files with
4508 names of their choice on the filesystem, then @code{xargs} is
4509 insecure unless the @samp{-0} option is used. If a file with the name
4510 @file{/home/someuser/foo/bar\n/etc/passwd} exists (assume that
4511 @samp{\n} stands for a newline character), then @code{find @dots{} -print}
4512 can be persuaded to print three separate lines:
4515 /home/someuser/foo/bar
4520 If it finds a blank line in the input, @code{xargs} will ignore it.
4521 Therefore, if some action is to be taken on the basis of this list of
4522 files, the @file{/etc/passwd} file would be included even if this was
4523 not the intent of the person running find. There are circumstances in
4524 which an attacker can use this to their advantage. The same
4525 consideration applies to file names containing ordinary spaces rather
4526 than newlines, except that of course the list of file names will no
4527 longer contain an ``extra'' newline.
4529 This problem is an unavoidable consequence of the default behaviour of
4530 the @code{xargs} command, which is specified by the POSIX standard.
4531 The only ways to avoid this problem are either to avoid all use of
4532 @code{xargs} in favour for example of @samp{find -exec} or (where
4533 available) @samp{find -execdir}, or to use the @samp{-0} option, which
4534 ensures that @code{xargs} considers file names to be separated by
4535 ASCII NUL characters rather than whitespace. However, useful as this
4536 option is, the POSIX standard does not make it mandatory.
4538 @comment node-name, next, previous, up
4539 @node Security Considerations for locate
4540 @section Security Considerations for @code{locate}
4542 It is fairly unusual for the output of @code{locate} to be fed into
4543 another command. However, if this were to be done, this would raise
4544 the same set of security issues as the use of @samp{find @dots{} -print}.
4545 Although the problems relating to whitespace in file names can be
4546 resolved by using @code{locate}'s @samp{-0} option, this still leaves
4547 the race condition problems associated with @samp{find @dots{} -print0}.
4548 There is no way to avoid these problems in the case of @code{locate}.
4550 @node Security Summary
4553 Where untrusted parties can create files on the system, or affect the
4554 names of files that are created, all uses for @code{find},
4555 @code{locate} and @code{xargs} have known security problems except the
4559 @item Informational use only
4560 Uses where the programs are used to prepare lists of file names upon
4561 which no further action will ever be taken.
4563 @item @samp{-delete}
4564 Use of the @samp{-delete} action with @code{find} to delete files
4565 which meet specified criteria
4567 @item @samp{-execdir}
4568 Use of the @samp{-execdir} action with @code{find} where the
4569 @env{PATH} environment variable contains directories which contain
4570 only trusted programs.
4573 @comment node-name, next, previous, up
4574 @node Error Messages, Primary Index, Security Considerations, Top
4575 @chapter Error Messages
4577 This section describes some of the error messages sometimes made by
4578 @code{find}, @code{xargs}, or @code{locate}, explains them and in some
4579 cases provides advice as to what you should do about this.
4581 This manual is written in English. The GNU findutils software
4582 features translations of error messages for many languages. For this
4583 reason the error messages produced by
4584 the programs are made to be as self-explanatory as possible. This approach avoids leaving people to
4585 figure out which test an English-language error message
4586 corresponds to. Error messages which are self-explanatory
4587 will not normally be mentioned in this document. For
4588 those messages mentioned in this document, only the
4589 English-language version of the message will be listed.
4592 * Error Messages From find::
4593 * Error Messages From xargs::
4594 * Error Messages From locate::
4595 * Error Messages From updatedb::
4598 @node Error Messages From find, Error Messages From xargs, , Error Messages
4599 @section Error Messages From @code{find}
4602 @item invalid predicate `-foo'
4603 This means that the @code{find} command line included something that
4604 started with a dash or other special character. The @code{find}
4605 program tried to interpret this as a test, action or option, but
4606 didn't recognise it. If it was intended to be a test, check what was
4607 specified against the documentation. If, on the other hand, the
4608 string is the name of a file which has been expanded from a wildcard
4609 (for example because you have a @samp{*} on the command line),
4610 consider using @samp{./*} or just @samp{.} instead.
4612 @item unexpected extra predicate
4613 This usually happens if you have an extra bracket on the command line
4614 (for example @samp{find . -print \)}).
4616 @item Warning: filesystem /path/foo has recently been mounted
4617 @itemx Warning: filesystem /path/foo has recently been unmounted
4618 These messages might appear when @code{find} moves into a directory
4619 and finds that the device number and inode are different to what it
4620 expected them to be. If the directory @code{find} has moved into is
4621 on an network filesystem (NFS), it will not issue this message, because
4622 @code{automount} frequently mounts new filesystems on directories as
4623 you move into them (that is how it knows you want to use the
4624 filesystem). So, if you do see this message, be wary ---
4625 @code{automount} may not have been responsible. Consider the
4626 possibility that someone else is manipulating the filesystem while
4627 @code{find} is running. Some people might do this in order to mislead
4628 @code{find} or persuade it to look at one set of files when it thought
4629 it was looking at another set.
4631 @item /path/foo changed during execution of find (old device number 12345, new device number 6789, filesystem type is <whatever>) [ref XXX]
4632 This message is issued when @code{find} moves into a directory and ends up
4633 somewhere it didn't expect to be. This happens in one of two
4634 circumstances. Firstly, this happens when @code{automount} intervenes
4635 on a system where @code{find} doesn't know how to determine what
4636 the current set of mounted filesystems is.
4638 Secondly, this can happen when the device number of a directory
4639 appears to change during a change of current directory, but
4640 @code{find} is moving up the filesystem hierarchy rather than down into it.
4641 In order to prevent @code{find} wandering off into some unexpected
4642 part of the filesystem, we stop it at this point.
4644 @item Don't know how to use getmntent() to read `/etc/mtab'. This is a bug.
4645 This message is issued when a problem similar to the above occurs on a
4646 system where @code{find} doesn't know how to figure out the current
4647 list of mount points. Ask for help on @email{bug-findutils@@gnu.org}.
4649 @item /path/foo/bar changed during execution of find (old inode number 12345, new inode number 67893, filesystem type is <whatever>) [ref XXX]"),
4650 This message is issued when @code{find} moves into a directory and
4651 discovers that the inode number of that directory
4652 is different from the inode number that it obtained when it examined the
4653 directory previously. This usually means that while
4654 @code{find} was deep in a directory hierarchy doing a
4655 time consuming operation, somebody has moved one of the parent directories to
4656 another location in the same filesystem. This may or may not have been done
4657 maliciously. In any case, @code{find} stops at this point
4658 to avoid traversing parts of the filesystem that it wasn't
4659 intended. You can use @code{ls -li} or @code{find /path -inum
4660 12345 -o -inum 67893} to find out more about what has happened.
4662 @item sanity check of the fnmatch() library function failed.
4663 Please submit a bug report. You may well be asked questions about
4664 your system, and if you compiled the @code{findutils} code yourself,
4665 you should keep your copy of the build tree around. The likely
4666 explanation is that your system has a buggy implementation of
4667 @code{fnmatch} that looks enough like the GNU version to fool
4668 @code{configure}, but which doesn't work properly.
4671 This normally happens if you use the @code{-exec} action or
4672 something similar (@code{-ok} and so forth) but the system has run out
4673 of free process slots. This is either because the system is very busy
4674 and the system has reached its maximum process limit, or because you
4675 have a resource limit in place and you've reached it. Check the
4676 system for runaway processes (with @code{ps}, if possible). Some process
4677 slots are normally reserved for use by @samp{root}.
4679 @item some-program terminated by signal 99
4680 Some program which was launched with @code{-exec} or similar was killed
4681 with a fatal signal. This is just an advisory message.
4685 @node Error Messages From xargs, Error Messages From locate, Error Messages From find, Error Messages
4686 @section Error Messages From xargs
4689 @item environment is too large for exec
4690 This message means that you have so many environment variables set (or
4691 such large values for them) that there is no room within the
4692 system-imposed limits on program command line argument length to
4693 invoke any program. This is an unlikely situation and is more likely
4694 result of an attempt to test the limits of @code{xargs}, or break it.
4695 Please try unsetting some environment variables, or exiting the
4696 current shell. You can also use @samp{xargs --show-limits} to
4697 understand the relevant sizes.
4699 @item can not fit single argument within argument list size limit
4700 You are using the @samp{-I} option and @code{xargs} doesn't have
4701 enough space to build a command line because it has read a really
4702 large item and it doesn't fit. You can probably work around this
4703 problem with the @samp{-s} option, but the default size is pretty
4704 large. This is a rare situation and is more likely an attempt to test
4705 the limits of @code{xargs}, or break it. Otherwise, you will need to
4706 try to shorten the problematic argument or not use @code{xargs}.
4709 See the description of the similar message for @code{find}.
4711 @item <program>: exited with status 255; aborting
4712 When a command run by @code{xargs} exits with status 255, @code{xargs}
4713 is supposed to stop. If this is not what you intended, wrap the
4714 program you are trying to invoke in a shell script which doesn't
4717 @item <program>: terminated by signal 99
4718 See the description of the similar message for @code{find}.
4721 @node Error Messages From locate, Error Messages From updatedb, Error Messages From xargs, Error Messages
4722 @section Error Messages From @code{locate}
4725 @item warning: database `/usr/local/var/locatedb' is more than 8 days old
4726 The @code{locate} program relies on a database which is periodically
4727 built by the @code{updatedb} program. That hasn't happened in a long
4728 time. To fix this problem, run @code{updatedb} manually. This can
4729 often happen on systems that are generally not left on, so the
4730 periodic ``cron'' task which normally does this doesn't get a chance
4733 @item locate database `/usr/local/var/locatedb' is corrupt or invalid
4734 This should not happen. Re-run @code{updatedb}. If that works, but
4735 @code{locate} still produces this error, run @code{locate --version}
4736 and @code{updatedb --version}. These should produce the same output.
4737 If not, you are using a mixed toolset; check your @samp{$PATH}
4738 environment variable and your shell aliases (if you have any). If
4739 both programs claim to be GNU versions, this is a bug; all versions of
4740 these programs should interoperate without problem. Ask for help on
4741 @email{bug-findutils@@gnu.org}.
4745 @node Error Messages From updatedb, , Error Messages From locate, Error Messages
4746 @section Error Messages From updatedb
4748 The @code{updatedb} program (and the programs it invokes) do issue
4749 error messages, but none seem to be candidates for guidance. If
4750 you are having a problem understanding one of these, ask for help on
4751 @email{bug-findutils@@gnu.org}.
4754 @node Primary Index, , Error Messages, Top
4755 @unnumbered @code{find} Primary Index
4757 This is a list of all of the primaries (tests, actions, and options)
4758 that make up @code{find} expressions for selecting files. @xref{find
4759 Expressions}, for more information on expressions.
4765 @comment texi related words used by Emacs' spell checker ispell.el
4767 @comment LocalWords: texinfo setfilename settitle setchapternewpage
4768 @comment LocalWords: iftex finalout ifinfo DIR titlepage vskip pt
4769 @comment LocalWords: filll dir samp dfn noindent xref pxref
4770 @comment LocalWords: var deffn texi deffnx itemx emph asis
4771 @comment LocalWords: findex smallexample subsubsection cindex
4772 @comment LocalWords: dircategory direntry itemize
4774 @comment other words used by Emacs' spell checker ispell.el
4775 @comment LocalWords: README fred updatedb xargs Plett Rendell akefile
4776 @comment LocalWords: args grep Filesystems fo foo fOo wildcards iname
4777 @comment LocalWords: ipath regex iregex expr fubar regexps
4778 @comment LocalWords: metacharacters macs sr sc inode lname ilname
4779 @comment LocalWords: sysdep noleaf ls inum xdev filesystems usr atime
4780 @comment LocalWords: ctime mtime amin cmin mmin al daystart Sladkey rm
4781 @comment LocalWords: anewer cnewer bckw rf xtype uname gname uid gid
4782 @comment LocalWords: nouser nogroup chown chgrp perm ch maxdepth
4783 @comment LocalWords: mindepth cpio src CD AFS statted stat fstype ufs
4784 @comment LocalWords: nfs tmp mfs printf fprint dils rw djm Nov lwall
4785 @comment LocalWords: POSIXLY fls fprintf strftime locale's EDT GMT AP
4786 @comment LocalWords: EST diff perl backquotes sprintf Falstad Oct cron
4787 @comment LocalWords: eg vmunix mkdir afs allexec allwrite ARG bigram
4788 @comment LocalWords: bigrams cd chmod comp crc CVS dbfile dum eof
4789 @comment LocalWords: fileserver filesystem fn frcode Ghazi Hnewc iXX
4790 @comment LocalWords: joeuser Kaveh localpaths localuser LOGNAME
4791 @comment LocalWords: Meyering mv netpaths netuser nonblank nonblanks
4792 @comment LocalWords: ois ok Pinard printindex proc procs prunefs
4793 @comment LocalWords: prunepaths pwd RFS rmadillo rmdir rsh sbins str
4794 @comment LocalWords: su Timar ubins ug unstripped vf VM Weitzel
4795 @comment LocalWords: wildcard zlogout basename execdir wholename iwholename
4796 @comment LocalWords: timestamp timestamps Solaris FreeBSD OpenBSD POSIX