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
810 True if the file was last accessed (or its status changed, or it was
811 modified) @var{n} minutes ago. These tests provide finer granularity
812 of measurement than @samp{-atime} et al., but rounding is done in a
813 similar way. For example, to list files in @file{/u/bill} that were
814 last read from 2 to 6 minutes ago:
817 find /u/bill -amin +2 -amin -6
821 @deffn Option -daystart
822 Measure times from the beginning of today rather than from 24 hours
823 ago. So, to list the regular files in your home directory that were
824 modified yesterday, do
827 find ~ -daystart -type f -mtime 1
830 The @samp{-daystart} option is unlike most other options in that it
831 has an effect on the way that other tests are performed. The affected
832 tests are @samp{-amin}, @samp{-cmin}, @samp{-mmin}, @samp{-atime},
833 @samp{-ctime} and @samp{-mtime}. The @samp{-daystart} option only
834 affects the behaviour of any tests which appear after it on the
838 @node Comparing Timestamps
839 @subsection Comparing Timestamps
841 As an alternative to comparing timestamps to the current time, you can
842 compare them to another file's timestamp. That file's timestamp could
843 be updated by another program when some event occurs. Or you could
844 set it to a particular fixed date using the @code{touch} command. For
845 example, to list files in @file{/usr} modified after February 1 of the
848 @c Idea from Rick Sladkey.
850 touch -t 02010000 /tmp/stamp$$
851 find /usr -newer /tmp/stamp$$
855 @deffn Test -anewer file
856 @deffnx Test -cnewer file
857 @deffnx Test -newer file
858 True if the file was last accessed (or its status changed, or it was
859 modified) more recently than @var{file} was modified. These tests are
860 affected by @samp{-follow} only if @samp{-follow} comes before them on
861 the command line. @xref{Symbolic Links}, for more information on
862 @samp{-follow}. As an example, to list any files modified since
863 @file{/bin/sh} was last modified:
866 find . -newer /bin/sh
871 True if the file was last accessed @var{n} days after its status was
872 last changed. Useful for finding files that are not being used, and
873 could perhaps be archived or removed to save disk space.
879 @deffn Test -size n@r{[}bckwMG@r{]}
880 True if the file uses @var{n} units of space, rounding up. The units
881 are 512-byte blocks by default, but they can be changed by adding a
882 one-character suffix to @var{n}:
886 512-byte blocks (never 1024)
890 kilobytes (1024 bytes)
894 Megabytes (units of 1048576 bytes)
896 Gigabytes (units of 1073741824 bytes)
899 The `b' suffix always considers blocks to be 512 bytes. This is not
900 affected by the setting (or non-setting) of the POSIXLY_CORRECT
901 environment variable. This behaviour is different to the behaviour of
902 the @samp{-ls} action). If you want to use 1024-byte units, use the
905 The number can be prefixed with a `+' or a `-'. A plus sign indicates
906 that the test should succeed if the file uses at least @var{n} units
907 of storage (a common use of this test) and a minus sign
908 indicates that the test should succeed if the file uses less than
909 @var{n} units of storage. There is no `=' prefix, because that's the
912 The size does not count indirect blocks, but it does count blocks in
913 sparse files that are not actually allocated. In other words, it's
914 consistent with the result you get for @samp{ls -l} or @samp{wc -c}.
915 This handling of sparse files differs from the output of the @samp{%k}
916 and @samp{%b} format specifiers for the @samp{-printf} predicate.
921 True if the file is empty and is either a regular file or a directory.
922 This might help determine good candidates for deletion. This test is
923 useful with @samp{-depth} (@pxref{Directories}) and @samp{-delete}
924 (@pxref{Single File}).
931 True if the file is of type @var{c}:
935 block (buffered) special
937 character (unbuffered) special
945 symbolic link; if @samp{-L} is in effect, this is true only for broken
946 symbolic links. If you want to search for symbolic links when
947 @samp{-L} is in effect, use @samp{-xtype} instead of @samp{-type}.
956 This test behaves the same as @samp{-type} unless the file is a
957 symbolic link. If the file is a symbolic link, the result is as
958 follows (in the table below, @samp{X} should be understood to
959 represent any letter except @samp{l}):
962 @item @samp{-P -xtype l}
963 True if the symbolic link is broken
964 @item @samp{-P -xtype X}
965 True if the (ultimate) target file is of type @samp{X}.
966 @item @samp{-L -xtype l}
968 @item @samp{-L -xtype X}
969 False unless the symbolic link is broken
972 In other words, for symbolic links, @samp{-xtype} checks the type of
973 the file that @samp{-type} does not check.
975 The @samp{-H} option also affects the behaviour of @samp{-xtype}.
976 When @samp{-H} is in effect, @samp{-xtype} behaves as if @samp{-L} had
977 been specified when examining files listed on the command line, and as
978 if @samp{-P} had been specified otherwise. If neither @samp{-H} nor
979 @samp{-L} was specified, @samp{-xtype} behaves as if @samp{-P} had
982 @xref{Symbolic Links}, for more information on @samp{-follow} and
989 @deffn Test -user uname
990 @deffnx Test -group gname
991 True if the file is owned by user @var{uname} (belongs to group
992 @var{gname}). A numeric ID is allowed.
997 True if the file's numeric user ID (group ID) is @var{n}. These tests
998 support ranges (@samp{+@var{n}} and @samp{-@var{n}}), unlike
999 @samp{-user} and @samp{-group}.
1003 @deffnx Test -nogroup
1004 True if no user corresponds to the file's numeric user ID (no group
1005 corresponds to the numeric group ID). These cases usually mean that
1006 the files belonged to users who have since been removed from the
1007 system. You probably should change the ownership of such files to an
1008 existing user or group, using the @code{chown} or @code{chgrp}
1013 @section File Mode Bits
1015 @xref{File Permissions}, for information on how file mode bits are
1016 structured and how to specify them.
1018 Four tests determine what users can do with files. These are
1019 @samp{-readable}, @samp{-writable}, @samp{-executable} and
1020 @samp{-perm}. The first three tests ask the operating system if the
1021 current user can perform the relevant operation on a file, while
1022 @samp{-perm} just examines the file's mode. The file mode may give
1023 a misleading impression of what the user can actually do, because the
1024 file may have an access control list, or exist on a read-only
1025 filesystem, for example. Of these four tests though, only
1026 @samp{-perm} is specified by the POSIX standard.
1028 The @samp{-readable}, @samp{-writable} and @samp{-executable} tests
1029 are implemented via the @code{access} system call. This is
1030 implemented within the operating system itself. If the file being
1031 considered is on an NFS filesystem, the remote system may allow or
1032 forbid read or write operations for reasons of which the NFS client
1033 cannot take account. This includes user-ID mapping, either in the
1034 general sense or the more restricted sense in which remote superusers
1035 are treated by the NFS server as if they are the local user
1036 @samp{nobody} on the NFS server.
1038 None of the tests in this section should be used to verify that a user
1039 is authorised to perform any operation (on the file being tested or
1040 any other file) because of the possibility of a race condition. That
1041 is, the situation may change between the test and an action being
1042 taken on the basis of the result of that test.
1045 @deffn Test -readable
1046 True if the file can be read by the invoking user.
1049 @deffn Test -writable
1050 True if the file can be written by the invoking user. This is an
1051 in-principle check, and other things may prevent a successful write
1052 operation; for example, the filesystem might be full.
1055 @deffn Test -executable
1056 True if the file can be executed/searched by the invoking user.
1059 @deffn Test -perm pmode
1061 True if the file's mode bits match @var{pmode}, which can be
1062 either a symbolic or numeric @var{mode} (@pxref{File Permissions})
1063 optionally prefixed by @samp{-} or @samp{/}.
1065 A @var{pmode} that starts with neither @samp{-} nor @samp{/} matches
1066 if @var{mode} exactly matches the file mode bits.
1068 A @var{pmode} that starts with @samp{-} matches if
1069 @emph{all} the file mode bits set in @var{mode} are set for the file;
1070 bits not set in @var{mode} are ignored.
1072 A @var{pmode} that starts with @samp{/} matches if
1073 @emph{any} of the file mode bits set in @var{mode} are set for the file;
1074 bits not set in @var{mode} are ignored.
1075 This is a GNU extension.
1077 If you don't use the @samp{/} or @samp{-} form with a symbolic mode
1078 string, you may have to specify a rather complex mode string. For
1079 example @samp{-perm g=w} will only match files that have mode 0020
1080 (that is, ones for which group write permission is the only file mode bit
1081 set). It is more likely that you will want to use the @samp{/} or
1082 @samp{-} forms, for example @samp{-perm -g=w}, which matches any file
1083 with group write permission.
1088 Match files that have read and write permission for their owner,
1089 and group, but that the rest of the world can read but not write to.
1090 Do not match files that meet these criteria but have other file mode
1091 bits set (for example if someone can execute/search the file).
1094 Match files that have read and write permission for their owner,
1095 and group, but that the rest of the world can read but not write to,
1096 without regard to the presence of any extra file mode bits (for
1097 example the executable bit). This matches a file with mode
1101 Match files that are writable by somebody (their owner, or
1102 their group, or anybody else).
1105 Match files that are writable by either their owner or their
1106 group. The files don't have to be writable by both the owner and
1107 group to be matched; either will do.
1109 @item -perm /g+w,o+w
1112 @item -perm /g=w,o=w
1116 Match files that are writable by both their owner and their
1119 @item -perm -444 -perm /222 ! -perm /111
1120 Match files that are readable for everybody, have at least one
1121 write bit set (i.e., somebody can write to them), but that cannot be
1122 executed/searched by anybody. Note that in some shells the @samp{!} must be
1125 @item -perm -a+r -perm /a+w ! -perm /a+x
1129 @item -perm -g+w,o+w
1134 If you specify @samp{-perm /000} or @samp{-perm /mode} where the
1135 symbolic mode @samp{mode} has no bits set, the test currently matches
1136 no files. This differs from the behaviour of @samp{-perm -000}, which
1137 matches all files. The behaviour of @samp{-perm /000} will be changed
1138 to be consistent with the behaviour of @samp{-perm -000}. The change
1139 will probably be made in early 2006.
1147 To search for files based on their contents, you can use the
1148 @code{grep} program. For example, to find out which C source files in
1149 the current directory contain the string @samp{thing}, you can do:
1152 grep -l thing *.[ch]
1155 If you also want to search for the string in files in subdirectories,
1156 you can combine @code{grep} with @code{find} and @code{xargs}, like
1160 find . -name '*.[ch]' | xargs grep -l thing
1163 The @samp{-l} option causes @code{grep} to print only the names of
1164 files that contain the string, rather than the lines that contain it.
1165 The string argument (@samp{thing}) is actually a regular expression,
1166 so it can contain metacharacters. This method can be refined a little
1167 by using the @samp{-r} option to make @code{xargs} not run @code{grep}
1168 if @code{find} produces no output, and using the @code{find} action
1169 @samp{-print0} and the @code{xargs} option @samp{-0} to avoid
1170 misinterpreting files whose names contain spaces:
1173 find . -name '*.[ch]' -print0 | xargs -r -0 grep -l thing
1176 For a fuller treatment of finding files whose contents match a
1177 pattern, see the manual page for @code{grep}.
1180 @section Directories
1182 Here is how to control which directories @code{find} searches, and how
1183 it searches them. These two options allow you to process a horizontal
1184 slice of a directory tree.
1186 @deffn Option -maxdepth levels
1187 Descend at most @var{levels} (a non-negative integer) levels of
1188 directories below the command line arguments. @samp{-maxdepth 0}
1189 means only apply the tests and actions to the command line arguments.
1192 @deffn Option -mindepth levels
1193 Do not apply any tests or actions at levels less than @var{levels} (a
1194 non-negative integer). @samp{-mindepth 1} means process all files
1195 except the command line arguments.
1198 @deffn Option -depth
1199 Process each directory's contents before the directory itself. Doing
1200 this is a good idea when producing lists of files to archive with
1201 @code{cpio} or @code{tar}. If a directory does not have write
1202 permission for its owner, its contents can still be restored from the
1203 archive since the directory's permissions are restored after its
1208 This is a deprecated synonym for @samp{-depth}, for compatibility with
1209 Mac OS X, FreeBSD and OpenBSD. The @samp{-depth} option is a POSIX
1210 feature, so it is better to use that.
1213 @deffn Action -prune
1214 If the file is a directory, do not descend into it. The result is
1215 true. For example, to skip the directory @file{src/emacs} and all
1216 files and directories under it, and print the names of the other files
1220 find . -wholename './src/emacs' -prune -o -print
1223 The above command will not print @file{./src/emacs} among its list of
1224 results. This however is not due to the effect of the @samp{-prune}
1225 action (which only prevents further descent, it doesn't make sure we
1226 ignore that item). Instead, this effect is due to the use of
1227 @samp{-o}. Since the left hand side of the ``or'' condition has
1228 succeeded for @file{./src/emacs}, it is not necessary to evaluate the
1229 right-hand-side (@samp{-print}) at all for this particular file. If
1230 you wanted to print that directory name you could use either an extra
1231 @samp{-print} action:
1234 find . -wholename './src/emacs' -prune -print -o -print
1237 or use the comma operator:
1240 find . -wholename './src/emacs' -prune , -print
1243 If the @samp{-depth} option is in effect, the subdirectories will have
1244 already been visited in any case. Hence @samp{-prune} has no effect
1250 Exit immediately (with return value zero if no errors have occurred).
1251 No child processes will be left running, but no more files specified
1252 on the command line will be processed. For example, @code{find
1253 /tmp/foo /tmp/bar -print -quit} will print only @samp{/tmp/foo}. Any
1254 command lines which have been built by @samp{-exec ... \+} or
1255 @samp{-execdir ... \+} are invoked before the program is executed.
1258 @deffn Option -noleaf
1259 Do not optimize by assuming that directories contain 2 fewer
1260 subdirectories than their hard link count. This option is needed when
1261 searching filesystems that do not follow the Unix directory-link
1262 convention, such as CD-ROM or MS-DOS filesystems or AFS volume mount
1263 points. Each directory on a normal Unix filesystem has at least 2
1264 hard links: its name and its @file{.} entry. Additionally, its
1265 subdirectories (if any) each have a @file{..} entry linked to that
1266 directory. When @code{find} is examining a directory, after it has
1267 statted 2 fewer subdirectories than the directory's link count, it
1268 knows that the rest of the entries in the directory are
1269 non-directories (@dfn{leaf} files in the directory tree). If only the
1270 files' names need to be examined, there is no need to stat them; this
1271 gives a significant increase in search speed.
1274 @deffn Option -ignore_readdir_race
1275 If a file disappears after its name has been read from a directory but
1276 before @code{find} gets around to examining the file with @code{stat},
1277 don't issue an error message. If you don't specify this option, an
1278 error message will be issued. This option can be useful in system
1279 scripts (cron scripts, for example) that examine areas of the
1280 filesystem that change frequently (mail queues, temporary directories,
1281 and so forth), because this scenario is common for those sorts of
1282 directories. Completely silencing error messages from @code{find} is
1283 undesirable, so this option neatly solves the problem. There is no
1284 way to search one part of the filesystem with this option on and part
1285 of it with this option off, though. When this option is turned on and
1286 find discovers that one of the start-point files specified on the
1287 command line does not exist, no error message will be issued.
1291 @deffn Option -noignore_readdir_race
1292 This option reverses the effect of the @samp{-ignore_readdir_race}
1298 @section Filesystems
1300 A @dfn{filesystem} is a section of a disk, either on the local host or
1301 mounted from a remote host over a network. Searching network
1302 filesystems can be slow, so it is common to make @code{find} avoid
1305 There are two ways to avoid searching certain filesystems. One way is
1306 to tell @code{find} to only search one filesystem:
1309 @deffnx Option -mount
1310 Don't descend directories on other filesystems. These options are
1314 The other way is to check the type of filesystem each file is on, and
1315 not descend directories that are on undesirable filesystem types:
1317 @deffn Test -fstype type
1318 True if the file is on a filesystem of type @var{type}. The valid
1319 filesystem types vary among different versions of Unix; an incomplete
1320 list of filesystem types that are accepted on some version of Unix or
1323 ext2 ext3 proc sysfs ufs 4.2 4.3 nfs tmp mfs S51K S52K
1325 You can use @samp{-printf} with the @samp{%F} directive to see the
1326 types of your filesystems. The @samp{%D} directive shows the device
1327 number. @xref{Print File Information}. @samp{-fstype} is usually
1328 used with @samp{-prune} to avoid searching remote filesystems
1329 (@pxref{Directories}).
1332 @node Combining Primaries With Operators
1333 @section Combining Primaries With Operators
1335 Operators build a complex expression from tests and actions.
1336 The operators are, in order of decreasing precedence:
1339 @item @asis{( @var{expr} )}
1341 Force precedence. True if @var{expr} is true.
1343 @item @asis{! @var{expr}}
1344 @itemx @asis{-not @var{expr}}
1347 True if @var{expr} is false. In some shells, it is necessary to
1348 protect the @samp{!} from shell interpretation by quoting it.
1350 @item @asis{@var{expr1 expr2}}
1351 @itemx @asis{@var{expr1} -a @var{expr2}}
1352 @itemx @asis{@var{expr1} -and @var{expr2}}
1355 And; @var{expr2} is not evaluated if @var{expr1} is false.
1357 @item @asis{@var{expr1} -o @var{expr2}}
1358 @itemx @asis{@var{expr1} -or @var{expr2}}
1361 Or; @var{expr2} is not evaluated if @var{expr1} is true.
1363 @item @asis{@var{expr1} , @var{expr2}}
1365 List; both @var{expr1} and @var{expr2} are always evaluated. True if
1366 @var{expr2} is true. The value of @var{expr1} is discarded. This
1367 operator lets you do multiple independent operations on one traversal,
1368 without depending on whether other operations succeeded. The two
1369 operations @var{expr1} and @var{expr2} are not always fully
1370 independent, since @var{expr1} might have side effects like touching
1371 or deleting files, or it might use @samp{-prune} which would also
1375 @code{find} searches the directory tree rooted at each file name by
1376 evaluating the expression from left to right, according to the rules
1377 of precedence, until the outcome is known (the left hand side is false
1378 for @samp{-and}, true for @samp{-or}), at which point @code{find}
1379 moves on to the next file name.
1381 There are two other tests that can be useful in complex expressions:
1391 @node Actions, Databases, Finding Files, Top
1394 There are several ways you can print information about the files that
1395 match the criteria you gave in the @code{find} expression. You can
1396 print the information either to the standard output or to a file that
1397 you name. You can also execute commands that have the file names as
1398 arguments. You can use those commands as further filters to select
1403 * Print File Information::
1409 @node Print File Name
1410 @section Print File Name
1412 @deffn Action -print
1413 True; print the entire file name on the standard output, followed by a
1414 newline. If there is the faintest possibility that one of the files
1415 for which you are searching might contain a newline, you should use
1416 @samp{-print0} instead.
1419 @deffn Action -fprint file
1420 True; print the entire file name into file @var{file}, followed by a
1421 newline. If @var{file} does not exist when @code{find} is run, it is
1422 created; if it does exist, it is truncated to 0 bytes. The named
1423 output file is always created, even if no output is sent to it. The
1424 file names @file{/dev/stdout} and @file{/dev/stderr} are handled
1425 specially; they refer to the standard output and standard error
1426 output, respectively.
1428 If there is the faintest possibility that one of the files for which
1429 you are searching might contain a newline, you should use
1430 @samp{-fprint0} instead.
1434 @c @deffn Option -show-control-chars how
1435 @c This option affects how some of @code{find}'s actions treat
1436 @c unprintable characters in file names. If @samp{how} is
1437 @c @samp{literal}, any subsequent actions (i.e., actions further on in the
1438 @c command line) print file names as-is.
1440 @c If this option is not specified, it currently defaults to @samp{safe}.
1441 @c If @samp{how} is @samp{safe}, C-like backslash escapes are used to
1442 @c indicate the non-printable characters for @samp{-ls} and @samp{-fls}.
1443 @c On the other hand, @samp{-print}, @samp{-fprint}, @samp{-fprintf} and
1444 @c @code{-printf} all quote unprintable characters if the data is going
1445 @c to a tty, and otherwise the data is emitted literally.
1449 @c Escaped if @samp{how} is @samp{safe}
1451 @c Escaped if @samp{how} is @samp{safe}
1453 @c Always quoted if stdout is a tty,
1454 @c @samp{-show-control-chars} is ignored
1456 @c Always literal, never escaped
1458 @c Always quoted if the destination is a tty;
1459 @c @samp{-show-control-chars} is ignored
1461 @c Always literal, never escaped
1463 @c If the destination is a tty, the @samp{%f},
1464 @c @samp{%F}, @samp{%h}, @samp{%l}, @samp{%p},
1465 @c and @samp{%P} directives produce quoted
1466 @c strings if stdout is a tty and are treated
1467 @c literally otherwise.
1469 @c As for @code{-fprintf}.
1474 @node Print File Information
1475 @section Print File Information
1478 True; list the current file in @samp{ls -dils} format on the standard
1479 output. The output looks like this:
1482 204744 17 -rw-r--r-- 1 djm staff 17337 Nov 2 1992 ./lwall-quotes
1489 The inode number of the file. @xref{Hard Links}, for how to find
1490 files based on their inode number.
1493 the number of blocks in the file. The block counts are of 1K blocks,
1494 unless the environment variable @code{POSIXLY_CORRECT} is set, in
1495 which case 512-byte blocks are used. @xref{Size}, for how to find
1496 files based on their size.
1499 The file's type and file mode bits. The type is shown as a dash for a
1500 regular file; for other file types, a letter like for @samp{-type} is
1501 used (@pxref{Type}). The file mode bits are read, write, and execute/search for
1502 the file's owner, its group, and other users, respectively; a dash
1503 means the permission is not granted. @xref{File Permissions}, for
1504 more details about file permissions. @xref{Mode Bits}, for how to
1505 find files based on their file mode bits.
1508 The number of hard links to the file.
1511 The user who owns the file.
1517 The file's size in bytes.
1520 The date the file was last modified.
1523 The file's name. @samp{-ls} quotes non-printable characters in the
1524 file names using C-like backslash escapes. This may change soon, as
1525 the treatment of unprintable characters is harmonised for @samp{-ls},
1526 @samp{-fls}, @samp{-print}, @samp{-fprint}, @samp{-printf} and
1531 @deffn Action -fls file
1532 True; like @samp{-ls} but write to @var{file} like @samp{-fprint}
1533 (@pxref{Print File Name}). The named output file is always created,
1534 even if no output is sent to it.
1537 @deffn Action -printf format
1538 True; print @var{format} on the standard output, interpreting @samp{\}
1539 escapes and @samp{%} directives. Field widths and precisions can be
1540 specified as with the @code{printf} C function. Format flags (like
1541 @samp{#} for example) may not work as you expect because many of the
1542 fields, even numeric ones, are printed with %s. Numeric flags which
1543 are affected in this way include G, U, b, D, k and n. This difference
1544 in behaviour means though that the format flag @samp{-} will work; it
1545 forces left-alignment of the field. Unlike @samp{-print},
1546 @samp{-printf} does not add a newline at the end of the string. If
1547 you want a newline at the end of the string, add a @samp{\n}.
1550 @deffn Action -fprintf file format
1551 True; like @samp{-printf} but write to @var{file} like @samp{-fprint}
1552 (@pxref{Print File Name}). The output file is always created, even if
1553 no output is ever sent to it.
1558 * Format Directives::
1565 The escapes that @samp{-printf} and @samp{-fprintf} recognise are:
1573 Stop printing from this format immediately and flush the output.
1585 A literal backslash (@samp{\}).
1589 The character whose ASCII code is NNN (octal).
1592 A @samp{\} character followed by any other character is treated as an
1593 ordinary character, so they both are printed, and a warning message is
1594 printed to the standard error output (because it was probably a typo).
1596 @node Format Directives
1597 @subsection Format Directives
1599 @samp{-printf} and @samp{-fprintf} support the following format
1600 directives to print information about the file being processed. The C
1601 @code{printf} function, field width and precision specifiers are
1602 supported, as applied to string (%s) types. That is, you can specify
1603 "minimum field width"."maximum field width" for each directive.
1604 Format flags (like @samp{#} for example) may not work as you expect
1605 because many of the fields, even numeric ones, are printed with %s.
1606 The format flag @samp{-} does work; it forces left-alignment of the
1609 @samp{%%} is a literal percent sign. A @samp{%} character followed by
1610 an unrecognised character (i.e., not a known directive or @code{printf}
1611 field width and precision specifier), is discarded (but the
1612 unrecognised character is printed), and a warning message is printed
1613 to the standard error output (because it was probably a typo). Don't
1614 rely on this behaviour, because other directives may be added in the
1617 A @samp{%} at the end of the format argument causes undefined
1618 behaviour since there is no following character. In some locales, it
1619 may hide your door keys, while in others it may remove the final page
1620 from the novel you are reading.
1624 * Ownership Directives::
1626 * Location Directives::
1628 * Formatting Flags::
1631 @node Name Directives
1632 @subsubsection Name Directives
1637 File's name (not the absolute path name, but the name of the file as
1638 it was encountered by @code{find} - that is, as a relative path from
1639 one of the starting points).
1641 File's name with any leading directories removed (only the last
1645 Leading directories of file's name (all but the last element and the
1646 slash before it). If the file's name contains no slashes (for example
1647 because it was named on the command line and is in the current working
1648 directory), then ``%h'' expands to ``.''. This prevents ``%h/%f''
1649 expanding to ``/foo'', which would be surprising and probably not
1653 File's name with the name of the command line argument under which
1654 it was found removed from the beginning.
1657 Command line argument under which file was found.
1661 @node Ownership Directives
1662 @subsubsection Ownership Directives
1667 File's group name, or numeric group ID if the group has no name.
1670 @c TODO: Needs to support # flag and 0 flag
1671 File's numeric group ID.
1674 File's user name, or numeric user ID if the user has no name.
1677 @c TODO: Needs to support # flag
1678 File's numeric user ID.
1680 @c full support, including # and 0.
1681 File's mode bits (in octal). If you always want to have a leading
1682 zero on the number, use the '#' format flag, for example '%#m'.
1684 The file mode bit numbers used are the traditional Unix
1685 numbers, which will be as expected on most systems, but if your
1686 system's file mode bit layout differs from the traditional Unix
1687 semantics, you will see a difference between the mode as printed by
1688 @samp{%m} and the mode as it appears in @code{struct stat}.
1691 File's type and mode bits (in symbolic form, as for @code{ls}). This
1692 directive is supported in findutils 4.2.5 and later.
1695 @node Size Directives
1696 @subsubsection Size Directives
1700 The amount of disk space used for this file in 1K blocks. Since disk
1701 space is allocated in multiples of the filesystem block size this is
1702 usually greater than %s/1024, but it can also be smaller if the file
1703 is a sparse file (that is, it has ``holes'').
1705 The amount of disk space used for this file in 512-byte blocks. Since
1706 disk space is allocated in multiples of the filesystem block size this
1707 is usually greater than %s/1024, but it can also be smaller if the
1708 file is a sparse file (that is, it has ``holes'').
1710 File's size in bytes.
1713 @node Location Directives
1714 @subsubsection Location Directives
1718 File's depth in the directory tree (depth below a file named on the
1719 command line, not depth below the root directory). Files named on the
1720 command line have a depth of 0. Subdirectories immediately below them
1721 have a depth of 1, and so on.
1723 The device number on which the file exists (the @code{st_dev} field of
1724 @code{struct stat}), in decimal.
1726 Type of the filesystem the file is on; this value can be used for
1727 @samp{-fstype} (@pxref{Directories}).
1729 Object of symbolic link (empty string if file is not a symbolic link).
1731 File's inode number (in decimal).
1733 Number of hard links to file.
1735 Type of the file as used with @samp{-type}. If the file is a symbolic
1736 link, @samp{l} will be printed.
1738 Type of the file as used with @samp{-type}. If the file is a symbolic
1739 link, it is dereferenced. If the file is a broken symbolic link,
1740 @samp{N} is printed.
1744 @node Time Directives
1745 @subsubsection Time Directives
1747 Some of these directives use the C @code{ctime} function. Its output
1748 depends on the current locale, but it typically looks like
1751 Wed Nov 2 00:42:36 1994
1756 File's last access time in the format returned by the C @code{ctime}
1759 File's last access time in the format specified by @var{k}
1760 (@pxref{Time Formats}).
1762 File's last status change time in the format returned by the C
1763 @code{ctime} function.
1765 File's last status change time in the format specified by @var{k}
1766 (@pxref{Time Formats}).
1768 File's last modification time in the format returned by the C
1769 @code{ctime} function.
1771 File's last modification time in the format specified by @var{k}
1772 (@pxref{Time Formats}).
1776 @subsection Time Formats
1778 Below are the formats for the directives @samp{%A}, @samp{%C}, and
1779 @samp{%T}, which print the file's timestamps. Some of these formats
1780 might not be available on all systems, due to differences in the C
1781 @code{strftime} function between systems.
1786 * Combined Time Formats::
1789 @node Time Components
1790 @subsubsection Time Components
1792 The following format directives print single components of the time.
1806 time zone (e.g., EDT), or nothing if no time zone is determinable
1812 seconds since Jan. 1, 1970, 00:00 GMT.
1815 @node Date Components
1816 @subsubsection Date Components
1818 The following format directives print single components of the date.
1822 locale's abbreviated weekday name (Sun..Sat)
1824 locale's full weekday name, variable length (Sunday..Saturday)
1827 locale's abbreviated month name (Jan..Dec)
1829 locale's full month name, variable length (January..December)
1833 day of month (01..31)
1837 day of year (001..366)
1839 week number of year with Sunday as first day of week (00..53)
1841 week number of year with Monday as first day of week (00..53)
1845 last two digits of year (00..99)
1848 @node Combined Time Formats
1849 @subsubsection Combined Time Formats
1851 The following format directives print combinations of time and date
1856 time, 12-hour (hh:mm:ss [AP]M)
1858 time, 24-hour (hh:mm:ss)
1860 locale's time representation (H:M:S)
1862 locale's date and time (Sat Nov 04 12:02:33 EST 1989)
1866 locale's date representation (mm/dd/yy)
1868 Date and time, separated by '+', for example `2004-04-28+22:22:05'.
1869 The time is given in the current timezone (which may be affected by
1870 setting the TZ environment variable). This is a GNU extension.
1873 @node Formatting Flags
1874 @subsubsection Formatting Flags
1876 The @samp{%m} and @samp{%d} directives support the @samp{#}, @samp{0}
1877 and @samp{+} flags, but the other directives do not, even if they
1878 print numbers. Numeric directives that do not support these flags
1888 All fields support the format flag @samp{-}, which makes fields
1889 left-aligned. That is, if the field width is greater than the actual
1890 contents of the field, the requisite number of spaces are printed
1891 after the field content instead of before it.
1894 @section Run Commands
1896 You can use the list of file names created by @code{find} or
1897 @code{locate} as arguments to other commands. In this way you can
1898 perform arbitrary actions on the files.
1907 @subsection Single File
1909 Here is how to run a command on one file at a time.
1911 @deffn Action -execdir command ;
1912 Execute @var{command}; true if zero status is returned. @code{find}
1913 takes all arguments after @samp{-exec} to be part of the command until
1914 an argument consisting of @samp{;} is reached. It replaces the string
1915 @samp{@{@}} by the current file name being processed everywhere it
1916 occurs in the command. Both of these constructions need to be escaped
1917 (with a @samp{\}) or quoted to protect them from expansion by the
1918 shell. The command is executed in the directory in which @code{find}
1921 For example, to compare each C header file in or below the current
1922 directory with the file @file{/tmp/master}:
1925 find . -name '*.h' -execdir diff -u '@{@}' /tmp/master ';'
1929 If you use`@samp{-execdir}, you must ensure that the current directory
1930 is not on @var{$PATH}, because otherwise an attacker could make
1931 @samp{find} run commands of their choice simply by leaving a
1932 suitably-named file in the right directory. GNU find will refuse to
1933 run if you use @samp{-execdir} and the current directory is in
1936 Another similar option, @samp{-exec} is supported, but is less secure.
1937 @xref{Security Considerations}, for a discussion of the security
1938 problems surrounding @samp{-exec}.
1941 @deffn Action -exec command ;
1942 This insecure variant of the @samp{-execdir} action is specified by
1943 POSIX. The main difference is that the command is executed in the
1944 directory from which @code{find} was invoked, meaning that @samp{@{@}}
1945 is expanded to a relative path starting with the name of one of the
1946 starting directories, rather than just the basename of the matched
1949 While some implementations of @code{find} replace the @samp{@{@}} only
1950 where it appears on its own in an argument, GNU @code{find} replaces
1951 @samp{@{@}} wherever it appears.
1955 @node Multiple Files
1956 @subsection Multiple Files
1958 Sometimes you need to process files one at a time. But usually this
1959 is not necessary, and, it is faster to run a command on as many files
1960 as possible at a time, rather than once per file. Doing this saves on
1961 the time it takes to start up the command each time.
1963 The @samp{-execdir} and @samp{-exec} actions have variants that build
1964 command lines containing as many matched files as possible.
1966 @deffn Action -execdir command @{@} +
1967 This works as for @samp{-execdir command ;}, except that the
1968 @samp{@{@}} at the end of the command is expanded to a list of names
1969 of matching files. This expansion is done in such a way as to avoid
1970 exceeding the maximum command line length available on the system.
1971 Only one @samp{@{@}} is allowed within the command, and it must appear
1972 at the end, immediately before the @samp{+}. A @samp{+} appearing in
1973 any position other than immediately after @samp{@{@}} is not
1974 considered to be special (that is, it does not terminate the command).
1978 @deffn Action -exec command @{@} +
1979 This insecure variant of the @samp{-execdir} action is specified by
1980 POSIX. The main difference is that the command is executed in the
1981 directory from which @code{find} was invoked, meaning that @samp{@{@}}
1982 is expanded to a relative path starting with the name of one of the
1983 starting directories, rather than just the basename of the matched
1987 Before @code{find} exits, any partially-built command lines are
1988 executed. This happens even if the exit was caused by the
1989 @samp{-quit} action. However, some types of error (for example not
1990 being able to invoke @code{stat()} on the current directory) can cause
1991 an immediate fatal exit. In this situation, any partially-built
1992 command lines will not be invoked (this prevents possible infinite
1995 Another, but less secure, way to run a command on more than one file
1996 at once, is to use the @code{xargs} command, which is invoked like
2000 xargs @r{[}@var{option}@dots{}@r{]} @r{[}@var{command} @r{[}@var{initial-arguments}@r{]}@r{]}
2003 @code{xargs} normally reads arguments from the standard input. These
2004 arguments are delimited by blanks (which can be protected with double
2005 or single quotes or a backslash) or newlines. It executes the
2006 @var{command} (default is @file{/bin/echo}) one or more times with any
2007 @var{initial-arguments} followed by arguments read from standard
2008 input. Blank lines on the standard input are ignored. If the
2009 @samp{-L} option is in use, trailing blanks indicate that @code{xargs}
2010 should consider the following line to be part of this one.
2012 Instead of blank-delimited names, it is safer to use @samp{find
2013 -print0} or @samp{find -fprint0} and process the output by giving the
2014 @samp{-0} or @samp{--null} option to GNU @code{xargs}, GNU @code{tar},
2015 GNU @code{cpio}, or @code{perl}. The @code{locate} command also has a
2016 @samp{-0} or @samp{--null} option which does the same thing.
2018 You can use shell command substitution (backquotes) to process a list
2019 of arguments, like this:
2022 grep -l sprintf `find $HOME -name '*.c' -print`
2025 However, that method produces an error if the length of the @samp{.c}
2026 file names exceeds the operating system's command line length limit.
2027 @code{xargs} avoids that problem by running the command as many times
2028 as necessary without exceeding the limit:
2031 find $HOME -name '*.c' -print | xargs grep -l sprintf
2034 However, if the command needs to have its standard input be a terminal
2035 (@code{less}, for example), you have to use the shell command
2036 substitution method or use the @samp{--arg-file} option of
2039 The @code{xargs} command will process all its input, building command
2040 lines and executing them, unless one of the commands exits with a
2041 status of 255 (this will cause xargs to issue an error message and
2042 stop) or it reads a line contains the end of file string specified
2043 with the @samp{--eof} option.
2046 * Unsafe File Name Handling::
2047 * Safe File Name Handling::
2048 * Unusual Characters in File Names::
2049 * Limiting Command Size::
2050 * Interspersing File Names::
2053 @node Unsafe File Name Handling
2054 @subsubsection Unsafe File Name Handling
2056 Because file names can contain quotes, backslashes, blank characters,
2057 and even newlines, it is not safe to process them using @code{xargs}
2058 in its default mode of operation. But since most files' names do not
2059 contain blanks, this problem occurs only infrequently. If you are
2060 only searching through files that you know have safe names, then you
2061 need not be concerned about it.
2063 @c This example is adapted from:
2064 @c From: pfalstad@stone.Princeton.EDU (Paul John Falstad)
2065 @c Newsgroups: comp.unix.shell
2066 @c Subject: Re: Beware xargs security holes
2067 @c Date: 16 Oct 90 19:12:06 GMT
2069 In many applications, if @code{xargs} botches processing a file
2070 because its name contains special characters, some data might be lost.
2071 The importance of this problem depends on the importance of the data
2072 and whether anyone notices the loss soon enough to correct it.
2073 However, here is an extreme example of the problems that using
2074 blank-delimited names can cause. If the following command is run
2075 daily from @code{cron}, then any user can remove any file on the
2079 find / -name '#*' -atime +7 -print | xargs rm
2082 For example, you could do something like this:
2090 and then @code{cron} would delete @file{/vmunix}, if it ran
2091 @code{xargs} with @file{/} as its current directory.
2093 To delete other files, for example @file{/u/joeuser/.plan}, you could
2101 eg$ mkdir u u/joeuser u/joeuser/.plan'
2103 eg$ echo > u/joeuser/.plan'
2106 eg$ find . -name '#*' -print | xargs echo
2107 ./# ./# /u/joeuser/.plan /#foo
2110 @node Safe File Name Handling
2111 @subsubsection Safe File Name Handling
2113 Here is how to make @code{find} output file names so that they can be
2114 used by other programs without being mangled or misinterpreted. You
2115 can process file names generated this way by giving the @samp{-0} or
2116 @samp{--null} option to GNU @code{xargs}, GNU @code{tar}, GNU
2117 @code{cpio}, or @code{perl}.
2119 @deffn Action -print0
2120 True; print the entire file name on the standard output, followed by a
2124 @deffn Action -fprint0 file
2125 True; like @samp{-print0} but write to @var{file} like @samp{-fprint}
2126 (@pxref{Print File Name}). The output file is always created.
2129 As of findutils version 4.2.4, the @code{locate} program also has a
2130 @samp{--null} option which does the same thing. For similarity with
2131 @code{xargs}, the short form of the option @samp{-0} can also be used.
2133 If you want to be able to handle file names safely but need to run
2134 commands which want to be connected to a terminal on their input, you
2135 can use the @samp{--arg-file} option to @code{xargs} like this:
2138 find / -name xyzzy -print0 > list
2139 xargs --null --arg-file=list munge
2142 The example above runs the @code{munge} program on all the files named
2143 @file{xyzzy} that we can find, but @code{munge}'s input will still be
2144 the terminal (or whatever the shell was using as standard input). If
2145 your shell has the ``process substitution'' feature @samp{<(...)}, you
2146 can do this in just one step:
2149 xargs --null --arg-file=<(find / -name xyzzy -print0) munge
2152 @node Unusual Characters in File Names
2153 @subsubsection Unusual Characters in File Names
2154 As discussed above, you often need to be careful about how the names
2155 of files are handled by @code{find} and other programs. If the output
2156 of @code{find} is not going to another program but instead is being
2157 shown on a terminal, this can still be a problem. For example, some
2158 character sequences can reprogram the function keys on some terminals.
2159 @xref{Security Considerations}, for a discussion of other security
2160 problems relating to @code{find}.
2162 Unusual characters are handled differently by various
2163 actions, as described below.
2168 Always print the exact file name, unchanged, even if the output is
2169 going to a terminal.
2172 Always print the exact file name, unchanged. This will probably
2173 change in a future release.
2176 Unusual characters are always escaped. White space, backslash, and
2177 double quote characters are printed using C-style escaping (for
2178 example @samp{\f}, @samp{\"}). Other unusual characters are printed
2179 using an octal escape. Other printable characters (for @samp{-ls} and
2180 @samp{-fls} these are the characters between octal 041 and 0176) are
2184 If the output is not going to a terminal, it is printed as-is.
2185 Otherwise, the result depends on which directive is in use:
2188 @item %D, %F, %H, %Y, %y
2189 These expand to values which are not under control of files' owners,
2190 and so are printed as-is.
2191 @item %a, %b, %c, %d, %g, %G, %i, %k, %m, %M, %n, %s, %t, %u, %U
2192 These have values which are under the control of files' owners but
2193 which cannot be used to send arbitrary data to the terminal, and so
2194 these are printed as-is.
2195 @item %f, %h, %l, %p, %P
2196 The output of these directives is quoted if the output is going to a
2199 This quoting is performed in the same way as for GNU @code{ls}. This
2200 is not the same quoting mechanism as the one used for @samp{-ls} and
2201 @samp{fls}. If you are able to decide what format to use for the
2202 output of @code{find} then it is normally better to use @samp{\0} as a
2203 terminator than to use newline, as file names can contain white space
2204 and newline characters.
2208 Quoting is handled in the same way as for the @samp{%p} directive of
2209 @samp{-printf} and @samp{-fprintf}. If you are using @code{find} in a
2210 script or in a situation where the matched files might have arbitrary
2211 names, you should consider using @samp{-print0} instead of
2216 The @code{locate} program quotes and escapes unusual characters in
2217 file names in the same way as @code{find}'s @samp{-print} action.
2219 The behaviours described above may change soon, as the treatment of
2220 unprintable characters is harmonised for @samp{-ls}, @samp{-fls},
2221 @samp{-print}, @samp{-fprint}, @samp{-printf} and @samp{-fprintf}.
2223 @node Limiting Command Size
2224 @subsubsection Limiting Command Size
2226 @code{xargs} gives you control over how many arguments it passes to
2227 the command each time it executes it. By default, it uses up to
2228 @code{ARG_MAX} - 2k, or 128k, whichever is smaller, characters per
2229 command. It uses as many lines and arguments as fit within that
2230 limit. The following options modify those values.
2233 @item --no-run-if-empty
2235 If the standard input does not contain any nonblanks, do not run the
2236 command. By default, the command is run once even if there is no
2237 input. This option is a GNU extension.
2239 @item --max-lines@r{[}=@var{max-lines}@r{]}
2240 @itemx -L @var{max-lines}
2241 @itemx -l@r{[}@var{max-lines}@r{]}
2242 Use at most @var{max-lines} nonblank input lines per command line;
2243 @var{max-lines} defaults to 1 if omitted; omitting the argument is not
2244 allowed in the case of the @samp{-L} option. Trailing blanks cause an
2245 input line to be logically continued on the next input line, for the
2246 purpose of counting the lines. Implies @samp{-x}. The preferred name
2247 for this option is @samp{-L} as this is specified by POSIX.
2249 @item --max-args=@var{max-args}
2250 @itemx -n @var{max-args}
2251 Use at most @var{max-args} arguments per command line. Fewer than
2252 @var{max-args} arguments will be used if the size (see the @samp{-s}
2253 option) is exceeded, unless the @samp{-x} option is given, in which
2254 case @code{xargs} will exit.
2256 @item --max-chars=@var{max-chars}
2257 @itemx -s @var{max-chars}
2258 Use at most @var{max-chars} characters per command line, including the
2259 command initial arguments and the terminating nulls at the ends of the
2260 argument strings. If you specify a value for this option which is too
2261 large or small, a warning message is printed and the appropriate upper
2262 or lower limit is used instead. You can use @samp{--show-limits}
2263 option to understand the command-line limits applying to @code{xargs}
2264 and how this is affected by any other options.
2266 @item --max-procs=@var{max-procs}
2267 @itemx -P @var{max-procs}
2268 Run up to @var{max-procs} processes at a time; the default is 1. If
2269 @var{max-procs} is 0, @code{xargs} will run as many processes as
2270 possible at a time. Use the @samp{-n}, @samp{-s}, or @samp{-L} option
2271 with @samp{-P}; otherwise chances are that the command will be run
2275 @node Interspersing File Names
2276 @subsubsection Interspersing File Names
2278 @code{xargs} can insert the name of the file it is processing between
2279 arguments you give for the command. Unless you also give options to
2280 limit the command size (@pxref{Limiting Command Size}), this mode of
2281 operation is equivalent to @samp{find -exec} (@pxref{Single File}).
2284 @item --replace@r{[}=@var{replace-str}@r{]}
2285 @itemx -I @var{replace-str}
2286 @itemx -i @var{replace-str}
2287 Replace occurrences of @var{replace-str} in the initial arguments with
2288 names read from the input. Also, unquoted blanks do not terminate
2289 arguments; instead, the input is split at newlines only. For the
2290 @samp{-i} option, if @var{replace-str} is omitted for @samp{--replace}
2291 or @samp{-i}, it defaults to @samp{@{@}} (like for @samp{find -exec}).
2292 Implies @samp{-x} and @samp{-l 1}. @samp{-i} is deprecated in favour
2293 of @samp{-I}. As an example, to sort each file in the @file{bills}
2294 directory, leaving the output in that file name with @file{.sorted}
2295 appended, you could do:
2298 find bills -type f | xargs -I XX sort -o XX.sorted XX
2302 The equivalent command using @samp{find -execdir} is:
2305 find bills -type f -execdir sort -o '@{@}.sorted' '@{@}' ';'
2310 When you use the @samp{-I} option, each line read from the input is
2311 buffered internally. This means that there is an upper limit on the
2312 length of input line that xargs will accept when used with the
2313 @samp{-I} option. To work around this limitation, you can use the
2314 @samp{-s} option to increase the amount of buffer space that xargs
2315 uses, and you can also use an extra invocation of xargs to ensure that
2316 very long lines do not occur. For example:
2319 somecommand | xargs -s 50000 echo | xargs -I '@{@}' -s 100000 rm '@{@}'
2322 Here, the first invocation of @code{xargs} has no input line length
2323 limit because it doesn't use the @samp{-I} option. The second
2324 invocation of @code{xargs} does have such a limit, but we have ensured
2325 that the it never encounters a line which is longer than it can
2328 This is not an ideal solution. Instead, the @samp{-I} option should
2329 not impose a line length limit (apart from any limit imposed by the
2330 operating system) and so one might consider this limitation to be a
2331 bug. A better solution would be to allow @code{xargs -I} to
2332 automatically move to a larger value for the @samp{-s} option when
2335 This sort of problem doesn't occur with the output of @code{find}
2336 because it emits just one filename per line.
2339 @subsection Querying
2341 To ask the user whether to execute a command on a single file, you can
2342 use the @code{find} primary @samp{-okdir} instead of @samp{-execdir},
2343 and the @code{find} primary @samp{-ok} instead of @samp{-exec}:
2345 @deffn Action -okdir command ;
2346 Like @samp{-execdir} (@pxref{Single File}), but ask the user first (on
2347 the standard input); if the response does not start with @samp{y} or
2348 @samp{Y}, do not run the command, and return false. If the command is
2349 run, its standard input is redirected from @file{/dev/null}.
2352 @deffn Action -ok command ;
2353 This insecure variant of the @samp{-okdir} action is specified by
2354 POSIX. The main difference is that the command is executed in the
2355 directory from which @code{find} was invoked, meaning that @samp{@{@}}
2356 is expanded to a relative path starting with the name of one of the
2357 starting directories, rather than just the basename of the matched
2358 file. If the command is run, its standard input is redirected from
2362 When processing multiple files with a single command, to query the
2363 user you give @code{xargs} the following option. When using this
2364 option, you might find it useful to control the number of files
2365 processed per invocation of the command (@pxref{Limiting Command
2371 Prompt the user about whether to run each command line and read a line
2372 from the terminal. Only run the command line if the response starts
2373 with @samp{y} or @samp{Y}. Implies @samp{-t}.
2377 @section Delete Files
2379 @deffn Action -delete
2380 Delete files or directories; true if removal succeeded. If the
2381 removal failed, an error message is issued.
2383 The use of the @samp{-delete} action on the command line automatically
2384 turns on the @samp{-depth} option (@pxref{find Expressions}).
2388 @section Adding Tests
2390 You can test for file attributes that none of the @code{find} builtin
2391 tests check. To do this, use @code{xargs} to run a program that
2392 filters a list of files printed by @code{find}. If possible, use
2393 @code{find} builtin tests to pare down the list, so the program run by
2394 @code{xargs} has less work to do. The tests builtin to @code{find}
2395 will likely run faster than tests that other programs perform.
2397 For reasons of efficiency it is often useful to limit the number of
2398 times an external program has to be run. For this reason, it is often
2399 a good idea to implement ``extended'' tests by using @code{xargs}.
2401 For example, here is a way to print the names of all of the unstripped
2402 binaries in the @file{/usr/local} directory tree. Builtin tests avoid
2403 running @code{file} on files that are not regular files or are not
2407 find /usr/local -type f -perm /a=x | xargs file |
2408 grep 'not stripped' | cut -d: -f1
2412 The @code{cut} program removes everything after the file name from the
2413 output of @code{file}.
2415 However, using @code{xargs} can present important security problems
2416 (@pxref{Security Considerations}). These can be avoided by using
2417 @samp{-execdir}. The @samp{-execdir} action is also a useful way of
2418 putting your own test in the middle of a set of other tests or actions
2419 for @code{find} (for example, you might want to use @samp{-prune}).
2421 @c Idea from Martin Weitzel.
2422 To place a special test somewhere in the middle of a @code{find}
2423 expression, you can use @samp{-execdir} (or, less securely,
2424 @samp{-exec}) to run a program that performs the test. Because
2425 @samp{-execdir} evaluates to the exit status of the executed program,
2426 you can use a program (which can be a shell script) that tests for a
2427 special attribute and make it exit with a true (zero) or false
2428 (non-zero) status. It is a good idea to place such a special test
2429 @emph{after} the builtin tests, because it starts a new process which
2430 could be avoided if a builtin test evaluates to false.
2432 Here is a shell script called @code{unstripped} that checks whether
2433 its argument is an unstripped binary file:
2437 file "$1" | grep -q "not stripped"
2441 This script relies on the shell exiting with the status of
2442 the last command in the pipeline, in this case @code{grep}. The
2443 @code{grep} command exits with a true status if it found any matches,
2444 false if not. Here is an example of using the script (assuming it is
2445 in your search path). It lists the stripped executables (and shell
2446 scripts) in the file @file{sbins} and the unstripped ones in
2450 find /usr/local -type f -perm /a=x \
2451 \( -execdir unstripped '@{@}' \; -fprint ubins -o -fprint sbins \)
2455 @node Databases, File Permissions, Actions, Top
2456 @chapter File Name Databases
2458 The file name databases used by @code{locate} contain lists of files
2459 that were in particular directory trees when the databases were last
2460 updated. The file name of the default database is determined when
2461 @code{locate} and @code{updatedb} are configured and installed. The
2462 frequency with which the databases are updated and the directories for
2463 which they contain entries depend on how often @code{updatedb} is run,
2464 and with which arguments.
2466 You can obtain some statistics about the databases by using
2467 @samp{locate --statistics}.
2470 * Database Locations::
2471 * Database Formats::
2472 * Newline Handling::
2476 @node Database Locations
2477 @section Database Locations
2479 There can be multiple file name databases. Users can select which
2480 databases @code{locate} searches using the @code{LOCATE_PATH}
2481 environment variable or a command line option. The system
2482 administrator can choose the file name of the default database, the
2483 frequency with which the databases are updated, and the directories
2484 for which they contain entries. File name databases are updated by
2485 running the @code{updatedb} program, typically nightly.
2487 In networked environments, it often makes sense to build a database at
2488 the root of each filesystem, containing the entries for that
2489 filesystem. @code{updatedb} is then run for each filesystem on the
2490 fileserver where that filesystem is on a local disk, to prevent
2491 thrashing the network.
2493 @xref{Invoking updatedb},
2494 for the description of the options to @code{updatedb}, which specify
2495 which directories would each database contain entries for.
2498 @node Database Formats
2499 @section Database Formats
2501 The file name databases contain lists of files that were in particular
2502 directory trees when the databases were last updated. The file name
2503 database format changed starting with GNU @code{locate} version 4.0 to
2504 allow machines with different byte orderings to share the databases.
2505 The new GNU @code{locate} can read both the old and new database
2506 formats. However, old versions of @code{locate} and @code{find}
2507 produce incorrect results if given a new-format database.
2509 Support for the old database format will eventually be discontinued,
2510 first in @code{updatedb} and later in @code{xargs}.
2512 If you run @samp{locate --statistics}, the resulting summary indicates
2513 the type of each @code{locate} database.
2517 * New Database Format::
2519 * Old Database Format::
2522 @node New Database Format
2523 @subsection New Database Format
2525 @code{updatedb} runs a program called @code{frcode} to
2526 @dfn{front-compress} the list of file names, which reduces the
2527 database size by a factor of 4 to 5. Front-compression (also known as
2528 incremental encoding) works as follows.
2530 The database entries are a sorted list (case-insensitively, for users'
2531 convenience). Since the list is sorted, each entry is likely to share
2532 a prefix (initial string) with the previous entry. Each database
2533 entry begins with an offset-differential count byte, which is the
2534 additional number of characters of prefix of the preceding entry to
2535 use beyond the number that the preceding entry is using of its
2536 predecessor. (The counts can be negative.) Following the count is a
2537 null-terminated ASCII remainder---the part of the name that follows
2540 If the offset-differential count is larger than can be stored in a
2541 byte (+/-127), the byte has the value 0x80 and the count follows in a
2542 2-byte word, with the high byte first (network byte order).
2544 Every database begins with a dummy entry for a file called
2545 @file{LOCATE02}, which @code{locate} checks for to ensure that the
2546 database file has the correct format; it ignores the entry in doing
2549 Databases cannot be concatenated together, even if the first (dummy)
2550 entry is trimmed from all but the first database. This is because the
2551 offset-differential count in the first entry of the second and
2552 following databases will be wrong.
2554 In the output of @samp{locate --statistics}, the new database format
2555 is referred to as @samp{LOCATE02}.
2557 @node Sample Database
2558 @subsection Sample Database
2560 Sample input to @code{frcode}:
2561 @c with nulls changed to newlines:
2565 /usr/src/cmd/aardvark.c
2566 /usr/src/cmd/armadillo.c
2570 Length of the longest prefix of the preceding entry to share:
2579 Output from @code{frcode}, with trailing nulls changed to newlines
2580 and count bytes made printable:
2590 (6 = 14 - 8, and -9 = 5 - 14)
2592 @node Old Database Format
2593 @subsection Old Database Format
2595 The old database format is used by Unix @code{locate} and @code{find}
2596 programs and earlier releases of the GNU ones. @code{updatedb}
2597 produces this format if given the @samp{--old-format} option.
2599 @code{updatedb} runs programs called @code{bigram} and @code{code} to
2600 produce old-format databases. The old format differs from the new one
2601 in the following ways. Instead of each entry starting with an
2602 offset-differential count byte and ending with a null, byte values
2603 from 0 through 28 indicate offset-differential counts from -14 through
2604 14. The byte value indicating that a long offset-differential count
2605 follows is 0x1e (30), not 0x80. The long counts are stored in host
2606 byte order, which is not necessarily network byte order, and host
2607 integer word size, which is usually 4 bytes. They also represent a
2608 count 14 less than their value. The database lines have no
2609 termination byte; the start of the next line is indicated by its first
2610 byte having a value <= 30.
2612 In addition, instead of starting with a dummy entry, the old database
2613 format starts with a 256 byte table containing the 128 most common
2614 bigrams in the file list. A bigram is a pair of adjacent bytes.
2615 Bytes in the database that have the high bit set are indexes (with the
2616 high bit cleared) into the bigram table. The bigram and
2617 offset-differential count coding makes these databases 20-25% smaller
2618 than the new format, but makes them not 8-bit clean. Any byte in a
2619 file name that is in the ranges used for the special codes is replaced
2620 in the database by a question mark, which not coincidentally is the
2621 shell wildcard to match a single character.
2623 The old format therefore cannot faithfully store entries with
2624 non-ASCII characters. It therefore should not be used in
2625 internationalised environments.
2627 The output of @samp{locate --statistics} will give an incorrect count
2628 of the number of file names containing newlines or high-bit characters
2629 for old-format databases.
2631 @node Newline Handling
2632 @section Newline Handling
2634 Within the database, file names are terminated with a null character.
2635 This is the case for both the old and the new format.
2637 When the new database format is being used, the compression technique
2638 used to generate the database though relies on the ability to sort the
2639 list of files before they are presented to @code{frcode}.
2641 If the system's sort command allows its input list of files to be
2642 separated with null characters via the @samp{-z} option, this option
2643 is used and therefore @code{updatedb} and @code{locate} will both
2644 correctly handle file names containing newlines. If the @code{sort}
2645 command lacks support for this, the list of files is delimited with
2646 the newline character, meaning that parts of file names containing
2647 newlines will be incorrectly sorted. This can result in both
2648 incorrect matches and incorrect failures to match.
2650 On the other hand, if you are using the old database format, file
2651 names with embedded newlines are not correctly handled. There is no
2652 technical limitation which enforces this, it's just that the
2653 @code{bigram} program has not been updated to support lists of file
2654 names separated by nulls.
2656 So, if you are using the new database format (this is the default) and
2657 your system uses GNU @code{sort}, newlines will be correctly handled
2658 at all times. Otherwise, newlines may not be correctly handled.
2660 @node File Permissions, Reference, Databases, Top
2661 @chapter File Permissions
2665 @node Reference, Common Tasks, File Permissions, Top
2668 Below are summaries of the command line syntax for the programs
2669 discussed in this manual.
2674 * Invoking updatedb::
2676 * Regular Expressions::
2677 * Environment Variables::
2680 @node Invoking find, Invoking locate, , Reference
2681 @section Invoking @code{find}
2684 find @r{[-H] [-L] [-P] [-D @var{debugoptions}] [-O@var{level}]} @r{[}@var{file}@dots{}@r{]} @r{[}@var{expression}@r{]}
2687 @code{find} searches the directory tree rooted at each file name
2688 @var{file} by evaluating the @var{expression} on each file it finds in
2691 The command line may begin with the @samp{-H}, @samp{-L}, @samp{-P},
2692 @samp{-D} and @samp{-O} options. These are followed by a list of
2693 files or directories that should be searched. If no files to search
2694 are specified, the current directory (@file{.}) is used.
2696 This list of files to search is followed by a list of expressions
2697 describing the files we wish to search for. The first part of the
2698 expression is recognised by the fact that it begins with @samp{-}
2699 followed by some other letters (for example @samp{-print}), or is
2700 either @samp{(} or @samp{!}. Any arguments after it are the rest of
2703 If no expression is given, the expression @samp{-print} is used.
2705 The @code{find} command exits with status zero if all files matched
2706 are processed successfully, greater than zero if errors occur.
2708 The @code{find} program also recognises two options for administrative
2713 Print a summary of the command line usage and exit.
2715 Print the version number of @code{find} and exit.
2718 The @samp{-version} option is a synonym for @samp{--version}
2722 * Filesystem Traversal Options::
2723 * Warning Messages::
2724 * Optimisation Options::
2726 * Find Expressions::
2729 @node Filesystem Traversal Options, Warning Messages,, Invoking find
2730 @subsection Filesystem Traversal Options
2732 The options @samp{-H}, @samp{-L} or @samp{-P} may be specified at the
2733 start of the command line (if none of these is specified, @samp{-P} is
2734 assumed). If you specify more than one of these options, the last one
2735 specified takes effect (but note that the @samp{-follow} option is
2736 equivalent to @samp{-L}).
2740 Never follow symbolic links (this is the default), except in the case
2741 of the @samp{-xtype} predicate.
2743 Always follow symbolic links, except in the case of the @samp{-xtype}
2746 Follow symbolic links specified in the list of files to search, or
2747 which are otherwise specified on the command line.
2750 If @code{find} would follow a symbolic link, but cannot for any reason
2751 (for example, because it has insufficient permissions or the link is
2752 broken), it falls back on using the properties of the symbolic link
2753 itself. @ref{Symbolic Links} for a more complete description of how
2754 symbolic links are handled.
2756 @node Warning Messages, Optimisation Options, Filesystem Traversal Options, Invoking find
2757 @subsection Warning Messages
2759 If there is an error on the @code{find} command line, an error message
2760 is normally issued. However, there are some usages that are
2761 inadvisable but which @code{find} should still accept. Under these
2762 circumstances, @code{find} may issue a warning message. By default,
2763 warnings are enabled only if @code{find} is being run interactively
2764 (specifically, if the standard input is a terminal). Warning messages
2765 can be controlled explicitly by the use of options on the command
2770 Issue warning messages where appropriate.
2772 Do not issue warning messages.
2775 These options take effect at the point on the command line where they
2776 are specified. Therefore it's not useful to specify @samp{-nowarn} at
2777 the end of the command line. The warning messages affected by the
2778 above options are triggered by:
2782 Use of the @samp{-d} option which is deprecated; please use
2783 @samp{-depth} instead, since the latter is POSIX-compliant.
2785 Use of the @samp{-ipath} option which is deprecated; please use
2786 @samp{-iwholename} instead.
2788 Specifying an option (for example @samp{-mindepth}) after a non-option
2789 (for example @samp{-type} or @samp{-print}) on the command line.
2792 The default behaviour above is designed to work in that way so that
2793 existing shell scripts don't generate spurious errors, but people will
2794 be made aware of the problem.
2796 Some warning messages are issued for less common or more serious
2797 problems, and consequently cannot be turned off:
2801 Use of an unrecognised backslash escape sequence with @samp{-fprintf}
2803 Use of an unrecognised formatting directive with @samp{-fprintf}
2806 @node Optimisation Options, Debug Options, Warning Messages, Invoking find
2807 @subsection Optimisation Options
2809 The @samp{-O@var{level}} option sets @code{find}'s optimisation level
2810 to @var{level}. The default optimisation level is 1.
2812 At certain optimisation levels, @code{find} reorders tests to speed up
2813 execution while preserving the overall effect; that is, predicates
2814 with side effects are not reordered relative to each other. The
2815 optimisations performed at each optimisation level are as follows.
2819 Currently equivalent to optimisation level 1.
2822 This is the default optimisation level and corresponds to the
2823 traditional behaviour. Expressions are reordered so that tests based
2824 only on the names of files (for example@samp{ -name} and
2825 @samp{-regex}) are performed first.
2828 Any @samp{-type} or @samp{-xtype} tests are performed after any tests
2829 based only on the names of files, but before any tests that require
2830 information from the inode. On many modern versions of Unix, file
2831 types are returned by @code{readdir()} and so these predicates are
2832 faster to evaluate than predicates which need to stat the file first.
2835 At this optimisation level, the full cost-based query optimiser is
2836 enabled. The order of tests is modified so that cheap (i.e., fast)
2837 tests are performed first and more expensive ones are performed later,
2838 if necessary. Within each cost band, predicates are evaluated earlier
2839 or later according to whether they are likely to succeed or not. For
2840 @samp{-o}, predicates which are likely to succeed are evaluated
2841 earlier, and for @samp{-a}, predicates which are likely to fail are
2846 @node Debug Options, Find Expressions, Optimisation Options, Invoking find
2847 @subsection Debug Options
2849 The @samp{-D} option makes @code{find} produce diagnostic output.
2850 Much of the information is useful only for diagnosing problems, and so
2851 most people will not find this option helpful.
2853 The list of debug options should be comma separated. Compatibility of
2854 the debug options is not guaranteed between releases of findutils.
2855 For a complete list of valid debug options, see the output of
2856 @code{find -D help}. Valid debug options include:
2859 Explain the debugging options.
2861 Show the expression tree in its original and optimised form.
2863 Print messages as files are examined with the stat and lstat system
2864 calls. The find program tries to minimise such calls.
2866 Prints diagnostic information relating to the optimisation of the
2867 expression tree; see the @samp{-O} option.
2870 @node Find Expressions,, Debug Options, Invoking find
2871 @subsection Find Expressions
2873 The final part of the @code{find} command line is a list of
2874 expressions. @xref{Primary Index}, for a summary of all of the tests,
2875 actions, and options that the expression can contain. If the
2876 expression is missing, @samp{-print} is assumed.
2878 @node Invoking locate, Invoking updatedb, Invoking find, Reference
2879 @section Invoking @code{locate}
2882 locate @r{[}@var{option}@dots{}@r{]} @var{pattern}@dots{}
2885 For each @var{pattern} given @code{locate} searches one or more file
2886 name databases returning each match of @var{pattern}.
2888 For each @var{pattern} given @code{locate} searches one or more file
2889 name databases returning each match of @var{pattern}.
2894 Print only names which match all non-option arguments, not those
2895 matching one or more non-option arguments.
2899 The specified pattern is matched against just the last component of
2900 the name of a file in the @code{locate} database. This last
2901 component is also called the ``base name''. For example, the base
2902 name of @file{/tmp/mystuff/foo.old.c} is @file{foo.old.c}. If the
2903 pattern contains metacharacters, it must match the base name exactly.
2904 If not, it must match part of the base name.
2908 Instead of printing the matched file names, just print the total
2909 number of matches found, unless @samp{--print} (@samp{-p}) is also
2913 @item --database=@var{path}
2914 @itemx -d @var{path}
2915 Instead of searching the default @code{locate} database, @code{locate} search the file
2916 name databases in @var{path}, which is a colon-separated list of
2917 database file names. You can also use the environment variable
2918 @code{LOCATE_PATH} to set the list of database files to search. The
2919 option overrides the environment variable if both are used. Empty
2920 elements in @var{path} (that is, a leading or trailing colon, or two
2921 colons in a row) are taken to stand for the default database.
2922 A database can be supplied on stdin, using @samp{-} as an element
2923 of @samp{path}. If more than one element of @samp{path} is @samp{-},
2924 later instances are ignored (but a warning message is printed).
2928 Only print out such names which currently exist (instead of such names
2929 which existed when the database was created). Note that this may slow
2930 down the program a lot, if there are many matches in the database.
2931 The way in which broken symbolic links are treated is affected by the
2932 @samp{-L}, @samp{-P} and @samp{-H} options. Please note that it is
2933 possible for the file to be deleted after @code{locate} has checked
2934 that it exists, but before you use it.
2936 @item --non-existing
2938 Only print out such names which currently do not exist (instead of
2939 such names which existed when the database was created). Note that
2940 this may slow down the program a lot, if there are many matches in the
2941 database. The way in which broken symbolic links are treated is
2942 affected by the @samp{-L}, @samp{-P} and @samp{-H} options. Please
2943 note that @code{locate} checks that the file does not exist, but a
2944 file of the same name might be created after @code{locate}'s check but
2945 before you read @code{locate}'s output.
2949 If testing for the existence of files (with the @samp{-e} or @samp{-E}
2950 options), consider broken symbolic links to be non-existing. This is
2951 the default behaviour.
2956 If testing for the existence of files (with the @samp{-e} or @samp{-E}
2957 options), treat broken symbolic links as if they were existing files.
2958 The @samp{-H} form of this option is provided purely for similarity
2959 with @code{find}; the use of @samp{-P} is recommended over @samp{-H}.
2963 Ignore case distinctions in both the pattern and the file names.
2967 Limit the number of results printed to N. When used with the
2968 @samp{--count} option, the value printed will never be larger than
2970 @item --max-database-age=D
2971 Normally, @code{locate} will issue a warning message when it searches
2972 a database which is more than 8 days old. This option changes that
2973 value to something other than 8. The effect of specifying a negative
2977 Accepted but does nothing. The option is supported only to provide
2978 compatibility with BSD's @code{locate}.
2982 Results are separated with the ASCII NUL character rather than the
2983 newline character. To get the full benefit of the use of this option,
2984 use the new @code{locate} database format (that is the default
2989 Print search results when they normally would not, because of the
2990 presence of @samp{--statistics} (@samp{-S}) or @samp{--count}
2995 The specified pattern is matched against the whole name of the file in
2996 the @code{locate} database. If the pattern contains metacharacters,
2997 it must match exactly. If not, it must match part of the whole file
2998 name. This is the default behaviour.
3002 Instead of using substring or shell glob matching, the pattern
3003 specified on the command line is understood to be a regular
3004 expression. GNU Emacs-style regular expressions are assumed unless
3005 the @samp{--regextype} option is also given. File names from the
3006 @code{locate} database are matched using the specified regular
3007 expression. If the @samp{-i} flag is also given, matching is
3008 case-insensitive. Matches are performed against the whole path name,
3009 and so by default a pathname will be matched if any part of it matches
3010 the specified regular expression. The regular expression may use
3011 @samp{^} or @samp{$} to anchor a match at the beginning or end of a
3015 This option changes the regular expression syntax and behaviour used
3016 by the @samp{--regex} option. @ref{Regular Expressions} for more
3017 information on the regular expression dialects understood by GNU
3022 Accepted but does nothing. The option is supported only to provide
3023 compatibility with BSD's @code{locate}.
3027 Print some summary information for each @code{locate} database. No
3028 search is performed unless non-option arguments are given.
3029 Although the BSD version of locate also has this option, the format of the
3030 output is different.
3033 Print a summary of the command line usage for @code{locate} and exit.
3036 Print the version number of @code{locate} and exit.
3039 @node Invoking updatedb, Invoking xargs, Invoking locate, Reference
3040 @section Invoking @code{updatedb}
3043 updatedb @r{[}@var{option}@dots{}@r{]}
3046 @code{updatedb} creates and updates the database of file names used by
3047 @code{locate}. @code{updatedb} generates a list of files similar to
3048 the output of @code{find} and then uses utilities for optimizing the
3049 database for performance. @code{updatedb} is often run periodically
3050 as a @code{cron} job and configured with environment variables or
3051 command options. Typically, operating systems have a shell script
3052 that ``exports'' configurations for variable definitions and uses
3053 another shell script that ``sources'' the configuration file into the
3054 environment and then executes @code{updatedb} in the environment.
3056 @code{updatedb} creates and updates the database of file names used by
3057 @code{locate}. @code{updatedb} generates a list of files similar to
3058 the output of @code{find} and then uses utilities for optimizing the
3059 database for performance. @code{updatedb} is often run periodically
3060 as a @code{cron} job and configured with environment variables or
3061 command options. Typically, operating systems have a shell script
3062 that ``exports'' configurations for variable definitions and uses
3063 another shell script that ``sources'' the configuration file into the
3064 environment and then executes @code{updatedb} in the environment.
3067 @item --findoptions='@var{OPTION}@dots{}'
3068 Global options to pass on to @code{find}.
3069 The environment variable @code{FINDOPTIONS} also sets this value.
3072 @item --localpaths='@var{path}@dots{}'
3073 Non-network directories to put in the database.
3074 Default is @file{/}.
3076 @item --netpaths='@var{path}@dots{}'
3077 Network (NFS, AFS, RFS, etc.) directories to put in the database.
3078 The environment variable @code{NETPATHS} also sets this value.
3081 @item --prunepaths='@var{path}@dots{}'
3082 Directories to omit from the database, which would otherwise be
3083 included. The environment variable @code{PRUNEPATHS} also sets this
3084 value. Default is @file{/tmp /usr/tmp /var/tmp /afs}. The paths are
3085 used as regular expressions (with @code{find ... -regex}, so you need
3086 to specify these paths in the same way that @code{find} will encounter
3087 them. This means for example that the paths must not include trailing
3090 @item --prunefs='@var{path}@dots{}'
3091 Filesystems to omit from the database, which would otherwise be
3092 included. Note that files are pruned when a filesystem is reached;
3093 Any filesystem mounted under an undesired filesystem will be ignored.
3094 The environment variable @code{PRUNEFS} also sets this value. Default
3095 is @file{nfs NFS proc}.
3097 @item --output=@var{dbfile}
3098 The database file to build. Default is system-dependent, but
3099 typically @file{/usr/local/var/locatedb}.
3101 @item --localuser=@var{user}
3102 The user to search the non-network directories as, using @code{su}.
3103 Default is to search the non-network directories as the current user.
3104 You can also use the environment variable @code{LOCALUSER} to set this user.
3106 @item --netuser=@var{user}
3107 The user to search network directories as, using @code{su}. Default
3108 @code{user} is @code{daemon}. You can also use the environment variable
3109 @code{NETUSER} to set this user.
3112 Generate a @code{locate} database in the old format, for compatibility
3113 with versions of @code{locate} other than GNU @code{locate}. Using
3114 this option means that @code{locate} will not be able to properly
3115 handle non-ASCII characters in file names (that is, file names
3116 containing characters which have the eighth bit set, such as many of
3117 the characters from the ISO-8859-1 character set).
3119 Print a summary of the command line usage and exit.
3121 Print the version number of @code{updatedb} and exit.
3124 @node Invoking xargs, Regular Expressions, Invoking updatedb, Reference
3125 @section Invoking @code{xargs}
3128 xargs @r{[}@var{option}@dots{}@r{]} @r{[}@var{command} @r{[}@var{initial-arguments}@r{]}@r{]}
3131 @code{xargs} exits with the following status:
3137 if any invocation of the command exited with status 1-125
3139 if the command exited with status 255
3141 if the command is killed by a signal
3143 if the command cannot be run
3145 if the command is not found
3147 if some other error occurred.
3150 Exit codes greater than 128 are used by the shell to indicate that
3151 a program died due to a fatal signal.
3154 @item --arg-file@r{=@var{inputfile}}
3155 @itemx -a o@r{@var{inputfile}}
3156 Read names from the file @var{inputfile} instead of standard input.
3157 If you use this option, the standard input stream remains unchanged
3158 when commands are run. Otherwise, stdin is redirected from
3163 Input file names are terminated by a null character instead of by
3164 whitespace, and any quotes and backslash characters are not considered
3165 special (every character is taken literally). Disables the end of
3166 file string, which is treated like any other argument.
3168 @item --delimiter @var{delim}
3169 @itemx -d @var{delim}
3171 Input file names are terminated by the specified character @var{delim}
3172 instead of by whitespace, and any quotes and backslash characters are
3173 not considered special (every character is taken literally). Disables
3174 the end of file string, which is treated like any other argument.
3176 The specified delimiter may be a single character, a C-style character
3177 escape such as @samp{\n}, or an octal or hexadecimal escape code.
3178 Octal and hexadecimal escape codes are understood as for the
3179 @code{printf} command. Multibyte characters are not supported.
3182 @item -E @var{eof-str}
3183 @itemx --eof@r{[}=@var{eof-str}@r{]}
3184 @itemx -e@r{[}@var{eof-str}@r{]}
3185 Set the end of file string to @var{eof-str}. If the end of file
3186 string occurs as a line of input, the rest of the input is ignored.
3187 If @var{eof-str} is omitted (@samp{-e}) or blank (either @samp{-e} or
3188 @samp{-E}), there is no end of file string. The @samp{-e} form of
3189 this option is deprecated in favour of the POSIX-compliant @samp{-E}
3190 option, which you should use instead. As of GNU xargs version 4.2.9,
3191 the default behaviour of xargs is not to have a logical end-of-file
3192 marker. The POSIX standard (IEEE Std 1003.1, 2004 Edition) allows
3196 Print a summary of the options to @code{xargs} and exit.
3198 @item -I @var{replace-str}
3199 @itemx --replace@r{[}=@var{replace-str}@r{]}
3200 @itemx -i@r{[}@var{replace-str}@r{]}
3201 Replace occurrences of @var{replace-str} in the initial arguments with
3202 names read from standard input. Also, unquoted blanks do not
3203 terminate arguments; instead, the input is split at newlines only. If
3204 @var{replace-str} is omitted (omitting it is allowed only for
3205 @samp{-i}), it defaults to @samp{@{@}} (like for @samp{find -exec}).
3206 Implies @samp{-x} and @samp{-l 1}. The @samp{-i} option is deprecated
3207 in favour of the @samp{-I} option.
3209 @item -L @var{max-lines}
3210 @itemx --max-lines@r{[}=@var{max-lines}@r{]}
3211 @itemx -l@r{[}@var{max-lines}@r{]}
3212 Use at most @var{max-lines} non-blank input lines per command line.
3213 For @samp{-l}, @var{max-lines} defaults to 1 if omitted. For
3214 @samp{-L}, the argument is mandatory. Trailing blanks cause an input
3215 line to be logically continued on the next input line, for the purpose
3216 of counting the lines. Implies @samp{-x}. The @samp{-l} form of this
3217 option is deprecated in favour of the POSIX-compliant @samp{-L}
3220 @item --max-args=@var{max-args}
3221 @itemx -n @var{max-args}
3222 Use at most @var{max-args} arguments per command line. Fewer than
3223 @var{max-args} arguments will be used if the size (see the @samp{-s}
3224 option) is exceeded, unless the @samp{-x} option is given, in which
3225 case @code{xargs} will exit.
3229 Prompt the user about whether to run each command line and read a line
3230 from the terminal. Only run the command line if the response starts
3231 with @samp{y} or @samp{Y}. Implies @samp{-t}.
3233 @item --no-run-if-empty
3235 If the standard input is completely empty, do not run the
3236 command. By default, the command is run once even if there is no
3239 @item --max-chars=@var{max-chars}
3240 @itemx -s @var{max-chars}
3241 Use at most @var{max-chars} characters per command line, including the
3242 command, initial arguments and any terminating nulls at the ends of
3243 the argument strings.
3246 Display the limits on the command-line length which are imposed by the
3247 operating system, @code{xargs}' choice of buffer size and the
3248 @samp{-s} option. Pipe the input from @file{/dev/null} (and perhaps
3249 specify @samp{--no-run-if-empty}) if you don't want @code{xargs} to do
3254 Print the command line on the standard error output before executing
3258 Print the version number of @code{xargs} and exit.
3262 Exit if the size (see the @samp{-s} option) is exceeded.
3265 @item --max-procs=@var{max-procs}
3266 @itemx -P @var{max-procs}
3267 Run simultaneously up to @var{max-procs} processes at once; the default is 1. If
3268 @var{max-procs} is 0, @code{xargs} will run as many processes as
3269 possible simultaneously.
3273 @node Regular Expressions, Environment Variables, Invoking xargs, Reference
3274 @section Regular Expressions
3276 The @samp{-regex} and @samp{-iregex} tests of @code{find} allow
3277 matching by regular expression, as does the @samp{--regex} option of
3278 @code{locate}. There are many different types of Regular Expression,
3279 but the type used by @code{find} and @code{locate} is the same as is
3280 used in GNU Emacs. Both programs provide an option which allows you
3281 to select an alternative regular expression syntax; for @code{find}
3282 this is the @samp{-regextype} option, and for @code{locate} this is
3283 the @samp{--regextype} option.
3285 These options take a single argument, which indicates the specific
3286 regular expression syntax and behaviour that should be used. This
3287 should be one of the following:
3289 @include regexprops.texi
3291 @node Environment Variables,, Regular Expressions, Reference
3292 @section Environment Variables
3295 Provides a default value for the internationalisation variables that
3298 If set to a non-empty string value, override the values of all the
3299 other internationalisation variables.
3301 The POSIX standard specifies that this variable affects the pattern
3302 matching to be used for the `\-name' option. GNU find uses the
3303 GNU version of the @code{fnmatch} library function.
3305 POSIX also specifies that the `LC_COLLATE' environment
3306 variable affects the interpretation of the user's response to the
3307 query issued by `\-ok', but this is not the case for GNU find.
3309 This variable affects the treatment of character classes used with
3310 the @samp{-name} test, if the system's
3311 @code{fnmatch} library function supports this. It has no effect on the behaviour
3312 of the @samp{-ok} expression.
3314 Determines the locale to be used for internationalised messages.
3316 Determines the location of the internationalisation message catalogues.
3318 Affects the directories which are searched to find the executables
3319 invoked by @samp{-exec}, @samp{-execdir} @samp{-ok} and @samp{-okdir}.
3320 If the @var{PATH} environment variable includes the current directory
3321 (by explicitly including @samp{.} or by having an empty element), and
3322 the find command line includes @samp{-execdir} or @samp{-okdir},
3323 @code{find} will refuse to run. @xref{Security Considerations}, for a
3324 more detailed discussion of security matters.
3326 @item POSIXLY_CORRECT
3327 Determines the block size used by @samp{-ls} and @samp{-fls}.
3328 If @var{POSIXLY_CORRECT} is set, blocks are units of 512 bytes. Otherwise
3329 they are units of 1024 bytes.
3332 Affects the time zone used for some of the time-related format
3333 directives of @samp{-printf} and @samp{-fprintf}.
3338 @node Common Tasks, Worked Examples, Reference, Top
3339 @chapter Common Tasks
3341 The sections that follow contain some extended examples that both give
3342 a good idea of the power of these programs, and show you how to solve
3343 common real-world problems.
3346 * Viewing And Editing::
3349 * Strange File Names::
3350 * Fixing Permissions::
3351 * Classifying Files::
3354 @node Viewing And Editing
3355 @section Viewing And Editing
3357 To view a list of files that meet certain criteria, simply run your
3358 file viewing program with the file names as arguments. Shells
3359 substitute a command enclosed in backquotes with its output, so the
3360 whole command looks like this:
3363 less `find /usr/include -name '*.h' | xargs grep -l mode_t`
3367 You can edit those files by giving an editor name instead of a file
3371 emacs `find /usr/include -name '*.h' | xargs grep -l mode_t`
3374 Because there is a limit to the length of any individual command line,
3375 there is a limit to the number of files that can be handled in this
3376 way. We can get around this difficulty by using xargs like this:
3379 find /usr/include -name '*.h' | xargs grep -l mode_t > todo
3380 xargs --arg-file=todo emacs
3383 Here, @code{xargs} will run @code{emacs} as many times as necessary to
3384 visit all of the files listed in the file @file{todo}.
3389 You can pass a list of files produced by @code{find} to a file
3390 archiving program. GNU @code{tar} and @code{cpio} can both read lists
3391 of file names from the standard input---either delimited by nulls (the
3392 safe way) or by blanks (the lazy, risky default way). To use
3393 null-delimited names, give them the @samp{--null} option. You can
3394 store a file archive in a file, write it on a tape, or send it over a
3395 network to extract on another machine.
3397 One common use of @code{find} to archive files is to send a list of
3398 the files in a directory tree to @code{cpio}. Use @samp{-depth} so if
3399 a directory does not have write permission for its owner, its contents
3400 can still be restored from the archive since the directory's
3401 permissions are restored after its contents. Here is an example of
3402 doing this using @code{cpio}; you could use a more complex @code{find}
3403 expression to archive only certain files.
3406 find . -depth -print0 |
3407 cpio --create --null --format=crc --file=/dev/nrst0
3410 You could restore that archive using this command:
3413 cpio --extract --null --make-dir --unconditional \
3414 --preserve --file=/dev/nrst0
3417 Here are the commands to do the same things using @code{tar}:
3420 find . -depth -print0 |
3421 tar --create --null --files-from=- --file=/dev/nrst0
3423 tar --extract --null --preserve-perm --same-owner \
3427 @c Idea from Rick Sladkey.
3428 Here is an example of copying a directory from one machine to another:
3431 find . -depth -print0 | cpio -0o -Hnewc |
3432 rsh @var{other-machine} "cd `pwd` && cpio -i0dum"
3436 @section Cleaning Up
3438 @c Idea from Jim Meyering.
3439 This section gives examples of removing unwanted files in various
3440 situations. Here is a command to remove the CVS backup files created
3441 when an update requires a merge:
3444 find . -name '.#*' -print0 | xargs -0r rm -f
3447 The command above works, but the following is safer:
3450 find . -name '.#*' -depth -delete
3453 @c Idea from Franc,ois Pinard.
3454 You can run this command to clean out your clutter in @file{/tmp}.
3455 You might place it in the file your shell runs when you log out
3456 (@file{.bash_logout}, @file{.logout}, or @file{.zlogout}, depending on
3457 which shell you use).
3460 find /tmp -depth -user "$LOGNAME" -type f -delete
3463 If your @code{find} command removes directories, you may find that
3464 you get a spurious error message when @code{find} tries to recurse
3465 into a directory that has now been removed. Using the @samp{-depth}
3466 option will normally resolve this problem.
3468 @c Idea from Noah Friedman.
3469 To remove old Emacs backup and auto-save files, you can use a command
3470 like the following. It is especially important in this case to use
3471 null-terminated file names because Emacs packages like the VM mailer
3472 often create temporary file names with spaces in them, like
3473 @file{#reply to David J. MacKenzie<1>#}.
3476 find ~ \( -name '*~' -o -name '#*#' \) -print0 |
3477 xargs --no-run-if-empty --null rm -vf
3480 Removing old files from @file{/tmp} is commonly done from @code{cron}:
3482 @c Idea from Kaveh Ghazi.
3484 find /tmp /var/tmp -not -type d -mtime +3 -delete
3485 find /tmp /var/tmp -depth -mindepth 1 -type d -empty -delete
3488 The second @code{find} command above uses @samp{-depth} so it cleans
3489 out empty directories depth-first, hoping that the parents become
3490 empty and can be removed too. It uses @samp{-mindepth} to avoid
3491 removing @file{/tmp} itself if it becomes totally empty.
3493 @node Strange File Names
3494 @section Strange File Names
3497 @c From: tmatimar@isgtec.com (Ted Timar)
3498 @c Newsgroups: comp.unix.questions,comp.unix.shell,comp.answers,news.answers
3499 @c Subject: Unix - Frequently Asked Questions (2/7) [Frequent posting]
3500 @c Subject: How do I remove a file with funny characters in the filename ?
3501 @c Date: Thu Mar 18 17:16:55 EST 1993
3502 @code{find} can help you remove or rename a file with strange
3503 characters in its name. People are sometimes stymied by files whose
3504 names contain characters such as spaces, tabs, control characters, or
3505 characters with the high bit set. The simplest way to remove such
3509 rm -i @var{some*pattern*that*matches*the*problem*file}
3512 @code{rm} asks you whether to remove each file matching the given
3513 pattern. If you are using an old shell, this approach might not work
3514 if the file name contains a character with the high bit set; the shell
3515 may strip it off. A more reliable way is:
3518 find . -maxdepth 1 @var{tests} -okdir rm '@{@}' \;
3522 where @var{tests} uniquely identify the file. The @samp{-maxdepth 1}
3523 option prevents @code{find} from wasting time searching for the file
3524 in any subdirectories; if there are no subdirectories, you may omit
3525 it. A good way to uniquely identify the problem file is to figure out
3526 its inode number; use
3532 Suppose you have a file whose name contains control characters, and
3533 you have found that its inode number is 12345. This command prompts
3534 you for whether to remove it:
3537 find . -maxdepth 1 -inum 12345 -okdir rm -f '@{@}' \;
3540 If you don't want to be asked, perhaps because the file name may
3541 contain a strange character sequence that will mess up your screen
3542 when printed, then use @samp{-execdir} instead of @samp{-okdir}.
3544 If you want to rename the file instead, you can use @code{mv} instead
3548 find . -maxdepth 1 -inum 12345 -okdir mv '@{@}' @var{new-file-name} \;
3551 @node Fixing Permissions
3552 @section Fixing Permissions
3554 Suppose you want to make sure that everyone can write to the
3555 directories in a certain directory tree. Here is a way to find
3556 directories lacking either user or group write permission (or both),
3557 and fix their permissions:
3560 find . -type d -not -perm -ug=w | xargs chmod ug+w
3564 You could also reverse the operations, if you want to make sure that
3565 directories do @emph{not} have world write permission.
3567 @node Classifying Files
3568 @section Classifying Files
3571 @c From: martin@mwtech.UUCP (Martin Weitzel)
3572 @c Newsgroups: comp.unix.wizards,comp.unix.questions
3573 @c Subject: Advanced usage of 'find' (Re: Unix security automating script)
3574 @c Date: 22 Mar 90 15:05:19 GMT
3575 If you want to classify a set of files into several groups based on
3576 different criteria, you can use the comma operator to perform multiple
3577 independent tests on the files. Here is an example:
3580 find / -type d \( -perm -o=w -fprint allwrite , \
3581 -perm -o=x -fprint allexec \)
3583 echo "Directories that can be written to by everyone:"
3586 echo "Directories with search permissions for everyone:"
3590 @code{find} has only to make one scan through the directory tree
3591 (which is one of the most time consuming parts of its work).
3593 @node Worked Examples, Security Considerations, Common Tasks, Top
3594 @chapter Worked Examples
3596 The tools in the findutils package, and in particular @code{find},
3597 have a large number of options. This means that quite often,
3598 there is more than one way to do things. Some of the options
3599 and facilities only exist for compatibility with other tools, and
3600 findutils provides improved ways of doing things.
3602 This chapter describes a number of useful tasks that are commonly
3603 performed, and compares the different ways of achieving them.
3607 * Updating A Timestamp File::
3610 @node Deleting Files
3611 @section Deleting Files
3613 One of the most common tasks that @code{find} is used for is locating
3614 files that can be deleted. This might include:
3618 Files last modified more than 3 years ago which haven't been accessed
3619 for at least 2 years
3621 Files belonging to a certain user
3623 Temporary files which are no longer required
3626 This example concentrates on the actual deletion task rather than on
3627 sophisticated ways of locating the files that need to be deleted.
3628 We'll assume that the files we want to delete are old files underneath
3629 @file{/var/tmp/stuff}.
3631 @subsection The Traditional Way
3633 The traditional way to delete files in @file{var/tmp/stuff} that have
3634 not been modified in over 90 days would have been:
3637 find /var/tmp/stuff -mtime +90 -exec /bin/rm @{@} \;
3640 The above command uses @samp{-exec} to run the @code{/bin/rm} command
3641 to remove each file. This approach works and in fact would have
3642 worked in Version 7 Unix in 1979. However, there are a number of
3643 problems with this approach.
3646 The most obvious problem with the approach above is that it causes
3647 @code{find} to fork every time it finds a file that needs to delete,
3648 and the child process then has to use the @code{exec} system call to
3649 launch @code{/bin/rm}. All this is quite inefficient. If we are
3650 going to use @code{/bin/rm} to do this job, it is better to make it
3651 delete more than one file at a time.
3653 The most obvious way of doing this is to use the shell's command
3657 /bin/rm `find /var/tmp/stuff -mtime +90 -print`
3659 or you could use the more modern form
3661 /bin/rm $(find /var/tmp/stuff -mtime +90 -print)
3664 The commands above are much more efficient than the first attempt.
3665 However, there is a problem with them. The shell has a maximum
3666 command length which is imposed by the operating system (the actual
3667 limit varies between systems). This means that while the command
3668 expansion technique will usually work, it will suddenly fail when
3669 there are lots of files to delete. Since the task is to delete
3670 unwanted files, this is precisely the time we don't want things to go
3673 @subsection Making Use of xargs
3675 So, is there a way to be more efficient in the use of @code{fork()}
3676 and @code{exec()} without running up against this limit?
3677 Yes, we can be almost optimally efficient by making use
3678 of the @code{xargs} command. The @code{xargs} command reads arguments
3679 from its standard input and builds them into command lines. We can
3683 find /var/tmp/stuff -mtime +90 -print | xargs /bin/rm
3686 For example if the files found by @code{find} are
3687 @file{/var/tmp/stuff/A},
3688 @file{/var/tmp/stuff/B} and
3689 @file{/var/tmp/stuff/C} then @code{xargs} might issue the commands
3692 /bin/rm /var/tmp/stuff/A /var/tmp/stuff/B
3693 /bin/rm /var/tmp/stuff/C
3696 The above assumes that @code{xargs} has a very small maximum command
3697 line length. The real limit is much larger but the idea is that
3698 @code{xargs} will run @code{/bin/rm} as many times as necessary to get
3699 the job done, given the limits on command line length.
3701 This usage of @code{xargs} is pretty efficient, and the @code{xargs}
3702 command is widely implemented (all modern versions of Unix offer it).
3703 So far then, the news is all good. However, there is bad news too.
3705 @subsection Unusual characters in filenames
3707 Unix-like systems allow any characters to appear in file names with
3708 the exception of the ASCII NUL character and the backslash.
3709 Backslashes can occur in path names (as the directory separator) but
3710 not in the names of actual directory entries. This means that the
3711 list of files that @code{xargs} reads could in fact contain white space
3712 characters --- spaces, tabs and newline characters. Since by default,
3713 @code{xargs} assumes that the list of files it is reading uses white
3714 space as an argument separator, it cannot correctly handle the case
3715 where a filename actually includes white space. This makes the
3716 default behaviour of @code{xargs} almost useless for handling
3719 To solve this problem, GNU findutils introduced the @samp{-print0}
3720 action for @code{find}. This uses the ASCII NUL character to separate
3721 the entries in the file list that it produces. This is the ideal
3722 choice of separator since it is the only character that cannot appear
3723 within a path name. The @samp{-0} option to @code{xargs} makes it
3724 assume that arguments are separated with ASCII NUL instead of white
3725 space. It also turns off another misfeature in the default behaviour
3726 of @code{xargs}, which is that it pays attention to quote characters
3727 in its input. Some versions of @code{xargs} also terminate when they
3728 see a lone @samp{_} in the input, but GNU @code{find} no longer does
3729 that (since it has become an optional behaviour in the Unix standard).
3731 So, putting @code{find -print0} together with @code{xargs -0} we get
3735 find /var/tmp/stuff -mtime +90 -print0 | xargs -0 /bin/rm
3738 The result is an efficient way of proceeding that
3739 correctly handles all the possible characters that could appear in the
3740 list of files to delete. This is good news. However, there is, as
3741 I'm sure you're expecting, also more bad news. The problem is that
3742 this is not a portable construct; although other versions of Unix
3743 (notable BSD-derived ones) support @samp{-print0}, it's not
3744 universal. So, is there a more universal mechanism?
3746 @subsection Going back to -exec
3748 There is indeed a more universal mechanism, which is a slight
3749 modification to the @samp{-exec} action. The normal @samp{-exec}
3750 action assumes that the command to run is terminated with a semicolon
3751 (the semicolon normally has to be quoted in order to protect it from
3752 interpretation as the shell command separator). The SVR4 edition of
3753 Unix introduced a slight variation, which involves terminating the
3754 command with @samp{+} instead:
3757 find /var/tmp/stuff -mtime +90 -exec /bin/rm @{@} \+
3760 The above use of @samp{-exec} causes @code{find} to build up a long
3761 command line and then issue it. This can be less efficient than some
3762 uses of @code{xargs}; for example @code{xargs} allows new command
3763 lines to be built up while the previous command is still executing, and
3764 allows you to specify a number of commands to run in parallel.
3765 However, the @code{find @dots{} -exec @dots{} +} construct has the advantage
3766 of wide portability. GNU findutils did not support @samp{-exec @dots{} +}
3767 until version 4.2.12; one of the reasons for this is that it already
3768 had the @samp{-print0} action in any case.
3771 @subsection A more secure version of -exec
3773 The command above seems to be efficient and portable. However,
3774 within it lurks a security problem. The problem is shared with
3775 all the commands we've tried in this worked example so far, too. The
3776 security problem is a race condition; that is, if it is possible for
3777 somebody to manipulate the filesystem that you are searching while you
3778 are searching it, it is possible for them to persuade your @code{find}
3779 command to cause the deletion of a file that you can delete but they
3782 The problem occurs because the @samp{-exec} action is defined by the
3783 @acronym{POSIX} standard to invoke its command with the same working directory
3784 as @code{find} had when it was started. This means that the arguments
3785 which replace the @{@} include a relative path from @code{find}'s
3786 starting point down the file that needs to be deleted. For example,
3789 find /var/tmp/stuff -mtime +90 -exec /bin/rm @{@} \+
3792 might actually issue the command:
3795 /bin/rm /var/tmp/stuff/A /var/tmp/stuff/B /var/tmp/stuff/passwd
3798 Notice the file @file{/var/tmp/stuff/passwd}. Likewise, the command:
3801 cd /var/tmp && find stuff -mtime +90 -exec /bin/rm @{@} \+
3804 might actually issue the command:
3807 /bin/rm stuff/A stuff/B stuff/passwd
3810 If an attacker can rename @file{stuff} to something else (making use
3811 of their write permissions in @file{/var/tmp}) they can replace it
3812 with a symbolic link to @file{/etc}. That means that the
3813 @code{/bin/rm} command will be invoked on @file{/etc/passwd}. If you
3814 are running your @code{find} command as root, the attacker has just managed
3815 to delete a vital file. All they needed to do to achieve this was
3816 replace a subdirectory with a symbolic link at the vital moment.
3818 There is however, a simple solution to the problem. This is an action
3819 which works a lot like @code{-exec} but doesn't need to traverse a
3820 chain of directories to reach the file that it needs to work on. This
3821 is the @samp{-execdir} action, which was introduced by the BSD family
3822 of operating systems. The command,
3825 find /var/tmp/stuff -mtime +90 -execdir /bin/rm @{@} \+
3828 might delete a set of files by performing these actions:
3832 Change directory to /var/tmp/stuff/foo
3834 Invoke @code{/bin/rm ./file1 ./file2 ./file3}
3836 Change directory to /var/tmp/stuff/bar
3838 Invoke @code{/bin/rm ./file99 ./file100 ./file101}
3841 This is a much more secure method. We are no longer exposed to a race
3842 condition. For many typical uses of @code{find}, this is the best
3843 strategy. It's reasonably efficient, but the length of the command
3844 line is limited not just by the operating system limits, but also by
3845 how many files we actually need to delete from each directory.
3847 Is it possible to do any better? In the case of general file
3848 processing, no. However, in the specific case of deleting files it is
3849 indeed possible to do better.
3851 @subsection Using the -delete action
3853 The most efficient and secure method of solving this problem is to use
3854 the @samp{-delete} action:
3857 find /var/tmp/stuff -mtime +90 -delete
3860 This alternative is more efficient than any of the @samp{-exec} or
3861 @samp{-execdir} actions, since it entirely avoids the overhead of
3862 forking a new process and using @code{exec} to run @code{/bin/rm}. It
3863 is also normally more efficient than @code{xargs} for the same
3864 reason. The file deletion is performed from the directory containing
3865 the entry to be deleted, so the @samp{-delete} action has the same
3866 security advantages as the @samp{-execdir} action has.
3868 The @samp{-delete} action was introduced by the BSD family of
3871 @subsection Improving things still further
3873 Is it possible to improve things still further? Not without either
3874 modifying the system library to the operating system or having more specific
3875 knowledge of the layout of the filesystem and disk I/O subsystem, or
3878 The @code{find} command traverses the filesystem, reading
3879 directories. It then issues a separate system call for each file to
3880 be deleted. If we could modify the operating system, there are
3881 potential gains that could be made:
3885 We could have a system call to which we pass more than one filename
3888 Alternatively, we could pass in a list of inode numbers (on GNU/Linux
3889 systems, @code{readdir()} also returns the inode number of each
3890 directory entry) to be deleted.
3893 The above possibilities sound interesting, but from the kernel's point
3894 of view it is difficult to enforce standard Unix access controls for
3895 such processing by inode number. Such a facility would probably
3896 need to be restricted to the superuser.
3898 Another way of improving performance would be to increase the
3899 parallelism of the process. For example if the directory hierarchy we
3900 are searching is actually spread across a number of disks, we might
3901 somehow be able to arrange for @code{find} to process each disk in
3902 parallel. In practice GNU @code{find} doesn't have such an intimate
3903 understanding of the system's filesystem layout and disk I/O
3906 However, since the system administrator can have such an understanding
3907 they can take advantage of it like so:
3910 find /var/tmp/stuff1 -mtime +90 -delete &
3911 find /var/tmp/stuff2 -mtime +90 -delete &
3912 find /var/tmp/stuff3 -mtime +90 -delete &
3913 find /var/tmp/stuff4 -mtime +90 -delete &
3917 In the example above, four separate instances of @code{find} are used
3918 to search four subdirectories in parallel. The @code{wait} command
3919 simply waits for all of these to complete. Whether this approach is
3920 more or less efficient than a single instance of @code{find} depends
3921 on a number of things:
3925 Are the directories being searched in parallel actually on separate
3926 disks? If not, this parallel search might just result in a lot of
3927 disk head movement and so the speed might even be slower.
3929 Other activity - are other programs also doing things on those disks?
3933 @subsection Conclusion
3935 The fastest and most secure way to delete files with the help of
3936 @code{find} is to use @samp{-delete}. Using @code{xargs -0 -P N} can
3937 also make effective use of the disk, but it is not as secure.
3939 In the case where we're doing things other than deleting files, the
3940 most secure alternative is @samp{-execdir @dots{} +}, but this is not as
3941 portable as the insecure action @samp{-exec @dots{} +}.
3943 The @samp{-delete} action is not completely portable, but the only
3944 other possibility which is as secure (@samp{-execdir}) is no more
3945 portable. The most efficient portable alternative is @samp{-exec
3946 @dots{}+}, but this is insecure and isn't supported by versions of GNU
3947 findutils prior to 4.2.12.
3950 @node Updating A Timestamp File
3951 @section Updating A Timestamp File
3953 Suppose we have a directory full of files which is maintained with a
3954 set of automated tools; perhaps one set of tools updates them and
3955 another set of tools uses the result. In this situation, it might be
3956 useful for the second set of tools to know if the files have recently
3957 been changed. It might be useful, for example, to have a 'timestamp'
3958 file which gives the timestamp on the newest file in the collection.
3960 We can use @code{find} to achieve this, but there are several
3961 different ways to do it.
3963 @subsection Updating the Timestamp The Wrong Way
3965 The obvious but wrong answer is just to use @samp{-newer}:-
3968 find subdir -newer timestamp -exec touch -r @{@} timestamp \;
3971 This does the right sort of thing but has a bug. Suppose that two
3972 files in the subdirectory have been updated, and that these are called
3973 @file{file1} and @file{file2}. The command above will update
3974 @file{timestamp} with the modification time of @file{file1} or that of
3975 @file{file2}, but we don't know which one. Since the timestamps on
3976 @file{file1} and @file{file2} will in general be different, this could
3977 well be the wrong value.
3979 One solution to this problem is to modify @code{find} to recheck the
3980 modification time of @file{timestamp} every time a file is to be
3981 compared against it, but that will reduce the performance of
3984 @subsection Using the test utility to compare timestamps
3986 The @code{test} command can be used to compare timestamps:
3989 find subdir -exec test @{@} -nt timestamp \; -exec touch -r @{@} timestamp \;
3992 This will ensure that any changes made to the modification time of
3993 @file{timestamp} that take place during the execution of @code{find}
3994 are taken into account. This resolves our earlier problem, but
3995 unfortunately this runs much more slowly.
3997 @subsection A combined approach
3999 We can of course still use @samp{-newer} to cut down on the number of
4000 calls to @code{test}:
4003 find subdir -newer timestamp -a \
4004 -exec test @{@} -nt timestamp \; -a \
4005 -exec touch -r @{@} timestamp \;
4008 Here, the @samp{-newer} test excludes all the files which are
4009 definitely older than the timestamp, but all the files which are newer
4010 than the old value of the timestamp are compared against the current
4013 This is indeed faster in general, but the speed difference will depend
4014 on how many updated files there are.
4016 @subsection Using -printf and sort to compare timestamps
4018 It is possible to use the @samp{-printf} action to abandon the use of
4019 @code{test} entirely:
4022 newest=$(find subdir -newer timestamp -printf "%A@:%p\n" |
4026 touch -r "$@{newest:-timestamp@}" timestamp
4029 The command above works by generating a list of the timestamps and
4030 names of all the files which are newer than the timestamp. The
4031 @code{sort}, @code{tail} and @code{cut} commands simply pull out the
4032 name of the file with the largest timestamp value (that is, the latest
4033 file). The @code{touch} command is then used to update the timestamp,
4035 The @code{"$@{newest:-timestamp@}"} expression simply expands to the
4036 value of @code{$newest} if that variable is set, but to
4037 @file{timestamp} otherwise. This ensures that an argument is always
4038 given to the @samp{-r} option of the @code{touch} command.
4040 This approach seems quite efficient, but unfortunately it has a bug.
4041 Many operating systems now keep file modification time information at
4042 a granularity which is finer than one second. Unfortunately the
4043 @samp{%A@@} format for @samp{-printf} only prints a whole-number value
4044 currently; that is, these values are at a one-second granularity.
4045 This means that in our example above, @samp{$newest} will be the name
4046 of a file which is no more than one second older than the newest file,
4047 but may indeed be older.
4049 It would be possible to solve this problem with some kind of loop:
4053 newest=$(find subdir -newer timestamp -printf "%A@@:%p\n" |
4057 if test -z "$newest" ; then
4060 touch -r "$newest" timestamp
4065 A better fix for this problem would be to allow the @samp{%A@@} format
4066 to produce a result having a fractional part, too. While this is
4067 planned for GNU @code{find}, it hasn't been done yet.
4069 @subsection Coping with sub-second timestamp resolution
4071 Another tool which often works with timestamps is @code{make}. We can
4072 use @code{find} to generate a @file{Makefile} file on the fly and then
4073 use @code{make} to update the timestamps:
4080 -printf "timestamp:: %p\n\ttouch -r %p timestamp\n\n" > "$makefile"
4085 Unfortunately although the solution above is quite elegant, it fails
4086 to cope with white space within file names, and adjusting it to do so
4087 would require a rather complex shell script.
4090 @subsection Coping with odd filenames too
4092 We can fix both of these problems (looping and problems with white
4093 space), and do things more efficiently too. The following command
4094 works with newlines and doesn't need to sort the list of filenames.
4097 find subdir -newer timestamp -printf "%A@@:%p\0" |
4099 xargs --no-run-if-empty --null -i \
4100 find @{@} -maxdepth 0 -newer timestamp -exec touch -r @{@} timestamp \;
4103 The first @code{find} command generates a list of files which are
4104 newer than the original timestamp file, and prints a list of them with
4105 their timestamps. The @file{newest.pl} script simply filters out all
4106 the filenames which have timestamps which are older than whatever the
4113 my $latest_stamp = undef;
4115 my ($stamp, $name) = split(/:/);
4116 if (!defined($latest_stamp) || ($tstamp > $latest_stamp)) {
4117 $latest_stamp = $stamp;
4120 if ($tstamp >= $latest_stamp) {
4121 push @newest, $name;
4124 print join("\0", @newest);
4128 This prints a list of zero or more files, all of which are newer than
4129 the original timestamp file, and which have the same timestamp as each
4130 other, to the nearest second. The second @code{find} command takes
4131 each resulting file one at a time, and if that is newer than the
4132 timestamp file, the timestamp is updated.
4134 @node Security Considerations, Error Messages, Worked Examples, Top
4135 @chapter Security Considerations
4137 Security considerations are important if you are using @code{find} or
4138 @code{xargs} to search for or process files that don't belong to you
4139 or which other people have control. Security considerations
4140 relating to @code{locate} may also apply if you have files which you
4141 do not want others to see.
4143 The most severe forms of security problems affecting
4144 @code{find} and related programs are when third parties bring
4145 about a situation allowing them to do something
4146 they would normally not be able to accomplish. This is called @emph{privilege
4147 elevation}. This might include deleting files they would not normally
4148 be able to delete. It is common for the operating system to periodically
4149 invoke @code{find} for self-maintenance purposes. These invocations of
4150 @code{find} are particularly problematic from a security point of view
4151 as these are often invoked by the superuser and search the entire
4152 filesystem hierarchy. Generally, the severity of any associated problem depends
4153 on what the system is going to do with the files found by @code{find}.
4156 * Levels of Risk:: What is your level of exposure to security problems?
4157 * Security Considerations for find:: Security problems with find
4158 * Security Considerations for xargs:: Security problems with xargs
4159 * Security Considerations for locate:: Security problems with locate
4160 * Security Summary:: That was all very complex, what does it boil down to?
4164 @node Levels of Risk
4165 @section Levels of Risk
4167 There are some security risks inherent in the use of @code{find},
4168 @code{xargs} and (to a lesser extent) @code{locate}. The severity of
4169 these risks depends on what sort of system you are using:
4173 Multi-user systems where you do not control (or trust) the other
4174 users, and on which you execute @code{find}, including areas where
4175 those other users can manipulate the filesystem (for example beneath
4176 @file{/home} or @file{/tmp}).
4179 Systems where the actions of other users can create file names chosen
4180 by them, but to which they don't have access while @code{find} is
4181 being run. This access might include leaving programs running (shell
4182 background jobs, @code{at} or @code{cron} tasks, for example). On
4183 these sorts of systems, carefully written commands (avoiding use of
4184 @samp{-print} for example) should not expose you to a high degree of
4185 risk. Most systems fall into this category.
4188 Systems to which untrusted parties do not have access, cannot create
4189 file names of their own choice (even remotely) and which contain no
4190 security flaws which might enable an untrusted third party to gain
4191 access. Most systems do not fall into this category because there are
4192 many ways in which external parties can affect the names of files that
4193 are created on your system. The system on which I am writing this for
4194 example automatically downloads software updates from the Internet;
4195 the names of the files in which these updates exist are chosen by
4196 third parties@footnote{Of course, I trust these parties to a large
4197 extent anyway, because I install software provided by them; I choose
4198 to trust them in this way, and that's a deliberate choice}.
4201 In the discussion above, ``risk'' denotes the likelihood that someone
4202 can cause @code{find}, @code{xargs}, @code{locate} or some other
4203 program which is controlled by them to do something you did not
4204 intend. The levels of risk suggested do not take any account of the
4205 consequences of this sort of event. That is, if you operate a ``low
4206 risk'' type system, but the consequences of a security problem are
4207 disastrous, then you should still give serious thought to all the
4208 possible security problems, many of which of course will not be
4209 discussed here -- this section of the manual is intended to be
4210 informative but not comprehensive or exhaustive.
4212 If you are responsible for the operation of a system where the
4213 consequences of a security problem could be very important, you should
4217 @item Define a security policy which defines who is allowed to do what
4219 @item Seek competent advice on how to enforce your policy, detect
4220 breaches of that policy, and take account of any potential problems
4221 that might fall outside the scope of your policy.
4225 @node Security Considerations for find
4226 @section Security Considerations for @code{find}
4229 Some of the actions @code{find} might take have a direct effect;
4230 these include @code{-exec} and @code{-delete}. However, it is also
4231 common to use @code{-print} explicitly or implicitly, and so if
4232 @code{find} produces the wrong list of file names, that can also be a
4233 security problem; consider the case for example where @code{find} is
4234 producing a list of files to be deleted.
4236 We normally assume that the @code{find} command line expresses the
4237 file selection criteria and actions that the user had in mind -- that
4238 is, the command line is ``trusted'' data.
4240 From a security analysis point of view, the output of @code{find}
4241 should be correct; that is, the output should contain only the names
4242 of those files which meet the user's criteria specified on the command
4243 line. This applies for the @code{-exec} and @code{-delete} actions;
4244 one can consider these to be part of the output.
4246 On the other hand, the contents of the filesystem can be manipulated
4247 by other people, and hence we regard this as ``untrusted'' data. This
4248 implies that the @code{find} command line is a filter which converts
4249 the untrusted contents of the filesystem into a correct list of output
4252 The filesystem will in general change while @code{find} is searching
4253 it; in fact, most of the potential security problems with @code{find}
4254 relate to this issue in some way.
4256 @dfn{Race conditions} are a general class of security problem where the
4257 relative ordering of actions taken by @code{find} (for example) and
4258 something else are critically important in getting the correct and expected result@footnote{This is more or less the
4259 definition of the term ``race condition''} .
4261 For @code{find}, an attacker might move or rename files or directories in
4262 the hope that an action might be taken against a file which was not
4263 normally intended to be affected. Alternatively, this sort of attack
4264 might be intended to persuade @code{find} to search part of the
4265 filesystem which would not normally be included in the search
4266 (defeating the @code{-prune} action for example).
4269 * Problems with -exec and filenames::
4270 * Changing the Current Working Directory::
4271 * Race Conditions with -exec::
4272 * Race Conditions with -print and -print0::
4275 @node Problems with -exec and filenames
4276 @subsection Problems with -exec and filenames
4278 It is safe in many cases to use the @samp{-execdir} action with any
4279 file name. Because @samp{-execdir} prefixes the arguments it passes
4280 to programs with @samp{./}, you will not accidentally pass an argument
4281 which is interpreted as an option. For example the file @file{-f}
4282 would be passed to @code{rm} as @file{./-f}, which is harmless.
4284 However, your degree of safety does depend on the nature of the
4285 program you are running. For example constructs such as these two commands
4288 find -exec sh -c "something @{@}" \;
4289 find -execdir sh -c "something @{@}" \;
4292 are very dangerous. The reason for this is that the @samp{@{@}} is
4293 expanded to a filename which might contain a semicolon or other
4294 characters special to the shell. If for example someone creates the
4295 file @file{/tmp/foo; rm -rf $HOME} then the two commands above could
4296 delete someone's home directory.
4298 So for this reason do not run any command which will pass untrusted
4299 data (such as the names of files) to commands which interpret
4300 arguments as commands to be further interpreted (for example
4303 @node Changing the Current Working Directory
4304 @subsection Changing the Current Working Directory
4306 As @code{find} searches the filesystem, it finds subdirectories and
4307 then searches within them by changing its working directory. First,
4308 @code{find} reaches and recognises a subdirectory. It then decides if that
4309 subdirectory meets the criteria for being searched; that is, any
4310 @samp{-xdev} or @samp{-prune} expressions are taken into account. The
4311 @code{find} program will then change working directory and proceed to
4312 search the directory.
4314 A race condition attack might take the form that once the checks
4315 relevant to @samp{-xdev} and @samp{-prune} have been done, an attacker
4316 might rename the directory that was being considered, and put in its
4317 place a symbolic link that actually points somewhere else.
4319 The idea behind this attack is to fool @code{find} into going into the
4320 wrong directory. This would leave @code{find} with a working
4321 directory chosen by an attacker, bypassing any protection apparently
4322 provided by @samp{-xdev} and @samp{-prune}, and any protection
4323 provided by being able to @emph{not} list particular directories on
4324 the @code{find} command line. This form of attack is particularly
4325 problematic if the attacker can predict when the @code{find} command
4326 will be run, as is the case with @code{cron} tasks for example.
4328 GNU @code{find} has specific safeguards to prevent this general class
4329 of problem. The exact form of these safeguards depends on the
4330 properties of your system.
4333 * O_NOFOLLOW:: Safely changing directory using fchdir().
4334 * Systems without O_NOFOLLOW:: Checking for symbolic links after chdir().
4338 @subsubsection O_NOFOLLOW
4340 If your system supports the O_NOFOLLOW flag @footnote{GNU/Linux
4341 (kernel version 2.1.126 and later) and FreeBSD (3.0-CURRENT and later)
4342 support this} to the @code{open(2)} system call, @code{find} uses it
4343 when safely changing directory. The target directory is first opened
4344 and then @code{find} changes working directory with the
4345 @code{fchdir()} system call. This ensures that symbolic links are not
4346 followed, preventing the sort of race condition attack in which use
4347 is made of symbolic links.
4349 If for any reason this approach does not work, @code{find} will fall
4350 back on the method which is normally used if O_NOFOLLOW is not
4353 You can tell if your system supports O_NOFOLLOW by running
4359 This will tell you the version number and which features are enabled.
4360 For example, if I run this on my system now, this gives:
4362 GNU find version 4.2.18-CVS
4363 Features enabled: D_TYPE O_NOFOLLOW(enabled)
4366 Here, you can see that I am running a version of @code{find} which was
4367 built from the development (CVS) code prior to the release of
4368 findutils-4.2.18, and that the D_TYPE and O_NOFOLLOW features are
4369 present. O_NOFOLLOW is qualified with ``enabled''. This simply means
4370 that the current system seems to support O_NOFOLLOW. This check is
4371 needed because it is possible to build @code{find} on a system that
4372 defines O_NOFOLLOW and then run it on a system that ignores the
4373 O_NOFOLLOW flag. We try to detect such cases at startup by checking
4374 the operating system and version number; when this happens you will
4375 see ``O_NOFOLLOW(disabled)'' instead.
4377 @node Systems without O_NOFOLLOW
4378 @subsubsection Systems without O_NOFOLLOW
4380 The strategy for preventing this type of problem on systems that lack
4381 support for the O_NOFOLLOW flag is more complex. Each time
4382 @code{find} changes directory, it examines the directory it is about
4383 to move to, issues the @code{chdir()} system call, and then checks
4384 that it has ended up in the subdirectory it expected. If all is as
4385 expected, processing continues as normal. However, there are two main
4386 reasons why the directory might change: the use of an automounter and
4387 the someone removing the old directory and replacing it with something
4388 else while @code{find} is trying to descend into it.
4390 Where a filesystem ``automounter'' is in use it can be the case that
4391 the use of the @code{chdir()} system call can itself cause a new
4392 filesystem to be mounted at that point. On systems that do not
4393 support O_NOFOLLOW, this will cause @code{find}'s security check to
4396 However, this does not normally represent a security problem, since
4397 the automounter configuration is normally set up by the system
4398 administrator. Therefore, if the @code{chdir()} sanity check fails,
4399 @code{find} will make one more attempt. If that succeeds, execution
4400 carries on as normal. This is the usual case for automounters.
4402 Where an attacker is trying to exploit a race condition, the problem
4403 may not have gone away on the second attempt. If this is the case,
4404 @code{find} will issue a warning message and then ignore that
4405 subdirectory. When this happens, actions such as @samp{-exec} or
4406 @samp{-print} may already have taken place for the problematic
4407 subdirectory. This is because @code{find} applies tests and actions
4408 to directories before searching within them (unless @samp{-depth} was
4411 Because of the nature of the directory-change operation and security
4412 check, in the worst case the only things that @code{find} would have
4413 done with the directory are to move into it and back out to the
4414 original parent. No operations would have been performed within that
4417 @node Race Conditions with -exec
4418 @subsection Race Conditions with -exec
4420 The @samp{-exec} action causes another program to be run. It passes
4421 to the program the name of the file which is being considered at the
4422 time. The invoked program will typically then perform some action
4423 on that file. Once again, there is a race condition which can be
4424 exploited here. We shall take as a specific example the command
4427 find /tmp -path /tmp/umsp/passwd -exec /bin/rm
4430 In this simple example, we are identifying just one file to be deleted
4431 and invoking @code{/bin/rm} to delete it. A problem exists because
4432 there is a time gap between the point where @code{find} decides that
4433 it needs to process the @samp{-exec} action and the point where the
4434 @code{/bin/rm} command actually issues the @code{unlink()} system
4435 call to delete the file from the filesystem. Within this time period, an attacker can rename the
4436 @file{/tmp/umsp} directory, replacing it with a symbolic link to
4437 @file{/etc}. There is no way for @code{/bin/rm} to determine that it
4438 is working on the same file that @code{find} had in mind. Once the
4439 symbolic link is in place, the attacker has persuaded @code{find} to
4440 cause the deletion of the @file{/etc/passwd} file, which is not the
4441 effect intended by the command which was actually invoked.
4443 One possible defence against this type of attack is to modify the
4444 behaviour of @samp{-exec} so that the @code{/bin/rm} command is run
4445 with the argument @file{./passwd} and a suitable choice of working
4446 directory. This would allow the normal sanity check that @code{find}
4447 performs to protect against this form of attack too. Unfortunately,
4448 this strategy cannot be used as the POSIX standard specifies that the
4449 current working directory for commands invoked with @samp{-exec} must
4450 be the same as the current working directory from which @code{find}
4451 was invoked. This means that the @samp{-exec} action is inherently
4452 insecure and can't be fixed.
4454 GNU @code{find} implements a more secure variant of the @samp{-exec}
4455 action, @samp{-execdir}. The @samp{-execdir} action
4456 ensures that it is not necessary to dereference subdirectories to
4457 process target files. The current directory used to invoke programs
4458 is the same as the directory in which the file to be processed exists
4459 (@file{/tmp/umsp} in our example, and only the basename of the file to
4460 be processed is passed to the invoked command, with a @samp{./}
4461 prepended (giving @file{./passwd} in our example).
4463 The @samp{-execdir} action refuses to do anything if the current
4464 directory is included in the @var{$PATH} environment variable. This
4465 is necessary because @samp{-execdir} runs programs in the same
4466 directory in which it finds files -- in general, such a directory
4467 might be writable by untrusted users. For similar reasons,
4468 @samp{-execdir} does not allow @samp{@{@}} to appear in the name of
4469 the command to be run.
4471 @node Race Conditions with -print and -print0
4472 @subsection Race Conditions with -print and -print0
4474 The @samp{-print} and @samp{-print0} actions can be used to produce a
4475 list of files matching some criteria, which can then be used with some
4476 other command, perhaps with @code{xargs}. Unfortunately, this means
4477 that there is an unavoidable time gap between @code{find} deciding
4478 that one or more files meet its criteria and the relevant command
4479 being executed. For this reason, the @samp{-print} and @samp{-print0}
4480 actions are just as insecure as @samp{-exec}.
4482 In fact, since the construction
4485 find @dots{} -print | xargs @enddots{}
4488 does not cope correctly with newlines or other ``white space'' in
4489 file names, and copes poorly with file names containing quotes, the
4490 @samp{-print} action is less secure even than @samp{-print0}.
4493 @comment node-name, next, previous, up
4494 @comment @node Security Considerations for xargs
4495 @node Security Considerations for xargs
4496 @section Security Considerations for @code{xargs}
4498 The description of the race conditions affecting the @samp{-print}
4499 action of @code{find} shows that @code{xargs} cannot be secure if it
4500 is possible for an attacker to modify a filesystem after @code{find}
4501 has started but before @code{xargs} has completed all its actions.
4503 However, there are other security issues that exist even if it is not
4504 possible for an attacker to have access to the filesystem in real
4505 time. Firstly, if it is possible for an attacker to create files with
4506 names of their choice on the filesystem, then @code{xargs} is
4507 insecure unless the @samp{-0} option is used. If a file with the name
4508 @file{/home/someuser/foo/bar\n/etc/passwd} exists (assume that
4509 @samp{\n} stands for a newline character), then @code{find @dots{} -print}
4510 can be persuaded to print three separate lines:
4513 /home/someuser/foo/bar
4518 If it finds a blank line in the input, @code{xargs} will ignore it.
4519 Therefore, if some action is to be taken on the basis of this list of
4520 files, the @file{/etc/passwd} file would be included even if this was
4521 not the intent of the person running find. There are circumstances in
4522 which an attacker can use this to their advantage. The same
4523 consideration applies to file names containing ordinary spaces rather
4524 than newlines, except that of course the list of file names will no
4525 longer contain an ``extra'' newline.
4527 This problem is an unavoidable consequence of the default behaviour of
4528 the @code{xargs} command, which is specified by the POSIX standard.
4529 The only ways to avoid this problem are either to avoid all use of
4530 @code{xargs} in favour for example of @samp{find -exec} or (where
4531 available) @samp{find -execdir}, or to use the @samp{-0} option, which
4532 ensures that @code{xargs} considers file names to be separated by
4533 ASCII NUL characters rather than whitespace. However, useful as this
4534 option is, the POSIX standard does not make it mandatory.
4536 @comment node-name, next, previous, up
4537 @node Security Considerations for locate
4538 @section Security Considerations for @code{locate}
4540 It is fairly unusual for the output of @code{locate} to be fed into
4541 another command. However, if this were to be done, this would raise
4542 the same set of security issues as the use of @samp{find @dots{} -print}.
4543 Although the problems relating to whitespace in file names can be
4544 resolved by using @code{locate}'s @samp{-0} option, this still leaves
4545 the race condition problems associated with @samp{find @dots{} -print0}.
4546 There is no way to avoid these problems in the case of @code{locate}.
4548 @node Security Summary
4551 Where untrusted parties can create files on the system, or affect the
4552 names of files that are created, all uses for @code{find},
4553 @code{locate} and @code{xargs} have known security problems except the
4557 @item Informational use only
4558 Uses where the programs are used to prepare lists of file names upon
4559 which no further action will ever be taken.
4561 @item @samp{-delete}
4562 Use of the @samp{-delete} action with @code{find} to delete files
4563 which meet specified criteria
4565 @item @samp{-execdir}
4566 Use of the @samp{-execdir} action with @code{find} where the
4567 @env{PATH} environment variable contains directories which contain
4568 only trusted programs.
4571 @comment node-name, next, previous, up
4572 @node Error Messages, Primary Index, Security Considerations, Top
4573 @chapter Error Messages
4575 This section describes some of the error messages sometimes made by
4576 @code{find}, @code{xargs}, or @code{locate}, explains them and in some
4577 cases provides advice as to what you should do about this.
4579 This manual is written in English. The GNU findutils software
4580 features translations of error messages for many languages. For this
4581 reason the error messages produced by
4582 the programs are made to be as self-explanatory as possible. This approach avoids leaving people to
4583 figure out which test an English-language error message
4584 corresponds to. Error messages which are self-explanatory
4585 will not normally be mentioned in this document. For
4586 those messages mentioned in this document, only the
4587 English-language version of the message will be listed.
4590 * Error Messages From find::
4591 * Error Messages From xargs::
4592 * Error Messages From locate::
4593 * Error Messages From updatedb::
4596 @node Error Messages From find, Error Messages From xargs, , Error Messages
4597 @section Error Messages From @code{find}
4600 @item invalid predicate `-foo'
4601 This means that the @code{find} command line included something that
4602 started with a dash or other special character. The @code{find}
4603 program tried to interpret this as a test, action or option, but
4604 didn't recognise it. If it was intended to be a test, check what was
4605 specified against the documentation. If, on the other hand, the
4606 string is the name of a file which has been expanded from a wildcard
4607 (for example because you have a @samp{*} on the command line),
4608 consider using @samp{./*} or just @samp{.} instead.
4610 @item unexpected extra predicate
4611 This usually happens if you have an extra bracket on the command line
4612 (for example @samp{find . -print \)}).
4614 @item Warning: filesystem /path/foo has recently been mounted
4615 @itemx Warning: filesystem /path/foo has recently been unmounted
4616 These messages might appear when @code{find} moves into a directory
4617 and finds that the device number and inode are different to what it
4618 expected them to be. If the directory @code{find} has moved into is
4619 on an network filesystem (NFS), it will not issue this message, because
4620 @code{automount} frequently mounts new filesystems on directories as
4621 you move into them (that is how it knows you want to use the
4622 filesystem). So, if you do see this message, be wary ---
4623 @code{automount} may not have been responsible. Consider the
4624 possibility that someone else is manipulating the filesystem while
4625 @code{find} is running. Some people might do this in order to mislead
4626 @code{find} or persuade it to look at one set of files when it thought
4627 it was looking at another set.
4629 @item /path/foo changed during execution of find (old device number 12345, new device number 6789, filesystem type is <whatever>) [ref XXX]
4630 This message is issued when @code{find} moves into a directory and ends up
4631 somewhere it didn't expect to be. This happens in one of two
4632 circumstances. Firstly, this happens when @code{automount} intervenes
4633 on a system where @code{find} doesn't know how to determine what
4634 the current set of mounted filesystems is.
4636 Secondly, this can happen when the device number of a directory
4637 appears to change during a change of current directory, but
4638 @code{find} is moving up the filesystem hierarchy rather than down into it.
4639 In order to prevent @code{find} wandering off into some unexpected
4640 part of the filesystem, we stop it at this point.
4642 @item Don't know how to use getmntent() to read `/etc/mtab'. This is a bug.
4643 This message is issued when a problem similar to the above occurs on a
4644 system where @code{find} doesn't know how to figure out the current
4645 list of mount points. Ask for help on @email{bug-findutils@@gnu.org}.
4647 @item /path/foo/bar changed during execution of find (old inode number 12345, new inode number 67893, filesystem type is <whatever>) [ref XXX]"),
4648 This message is issued when @code{find} moves into a directory and
4649 discovers that the inode number of that directory
4650 is different from the inode number that it obtained when it examined the
4651 directory previously. This usually means that while
4652 @code{find} was deep in a directory hierarchy doing a
4653 time consuming operation, somebody has moved one of the parent directories to
4654 another location in the same filesystem. This may or may not have been done
4655 maliciously. In any case, @code{find} stops at this point
4656 to avoid traversing parts of the filesystem that it wasn't
4657 intended. You can use @code{ls -li} or @code{find /path -inum
4658 12345 -o -inum 67893} to find out more about what has happened.
4660 @item sanity check of the fnmatch() library function failed.
4661 Please submit a bug report. You may well be asked questions about
4662 your system, and if you compiled the @code{findutils} code yourself,
4663 you should keep your copy of the build tree around. The likely
4664 explanation is that your system has a buggy implementation of
4665 @code{fnmatch} that looks enough like the GNU version to fool
4666 @code{configure}, but which doesn't work properly.
4669 This normally happens if you use the @code{-exec} action or
4670 something similar (@code{-ok} and so forth) but the system has run out
4671 of free process slots. This is either because the system is very busy
4672 and the system has reached its maximum process limit, or because you
4673 have a resource limit in place and you've reached it. Check the
4674 system for runaway processes (with @code{ps}, if possible). Some process
4675 slots are normally reserved for use by @samp{root}.
4677 @item some-program terminated by signal 99
4678 Some program which was launched with @code{-exec} or similar was killed
4679 with a fatal signal. This is just an advisory message.
4683 @node Error Messages From xargs, Error Messages From locate, Error Messages From find, Error Messages
4684 @section Error Messages From xargs
4687 @item environment is too large for exec
4688 This message means that you have so many environment variables set (or
4689 such large values for them) that there is no room within the
4690 system-imposed limits on program command line argument length to
4691 invoke any program. This is an unlikely situation and is more likely
4692 result of an attempt to test the limits of @code{xargs}, or break it.
4693 Please try unsetting some environment variables, or exiting the
4694 current shell. You can also use @samp{xargs --show-limits} to
4695 understand the relevant sizes.
4697 @item can not fit single argument within argument list size limit
4698 You are using the @samp{-I} option and @code{xargs} doesn't have
4699 enough space to build a command line because it has read a really
4700 large item and it doesn't fit. You can probably work around this
4701 problem with the @samp{-s} option, but the default size is pretty
4702 large. This is a rare situation and is more likely an attempt to test
4703 the limits of @code{xargs}, or break it. Otherwise, you will need to
4704 try to shorten the problematic argument or not use @code{xargs}.
4707 See the description of the similar message for @code{find}.
4709 @item <program>: exited with status 255; aborting
4710 When a command run by @code{xargs} exits with status 255, @code{xargs}
4711 is supposed to stop. If this is not what you intended, wrap the
4712 program you are trying to invoke in a shell script which doesn't
4715 @item <program>: terminated by signal 99
4716 See the description of the similar message for @code{find}.
4719 @node Error Messages From locate, Error Messages From updatedb, Error Messages From xargs, Error Messages
4720 @section Error Messages From @code{locate}
4723 @item warning: database `/usr/local/var/locatedb' is more than 8 days old
4724 The @code{locate} program relies on a database which is periodically
4725 built by the @code{updatedb} program. That hasn't happened in a long
4726 time. To fix this problem, run @code{updatedb} manually. This can
4727 often happen on systems that are generally not left on, so the
4728 periodic ``cron'' task which normally does this doesn't get a chance
4731 @item locate database `/usr/local/var/locatedb' is corrupt or invalid
4732 This should not happen. Re-run @code{updatedb}. If that works, but
4733 @code{locate} still produces this error, run @code{locate --version}
4734 and @code{updatedb --version}. These should produce the same output.
4735 If not, you are using a mixed toolset; check your @samp{$PATH}
4736 environment variable and your shell aliases (if you have any). If
4737 both programs claim to be GNU versions, this is a bug; all versions of
4738 these programs should interoperate without problem. Ask for help on
4739 @email{bug-findutils@@gnu.org}.
4743 @node Error Messages From updatedb, , Error Messages From locate, Error Messages
4744 @section Error Messages From updatedb
4746 The @code{updatedb} program (and the programs it invokes) do issue
4747 error messages, but none seem to be candidates for guidance. If
4748 you are having a problem understanding one of these, ask for help on
4749 @email{bug-findutils@@gnu.org}.
4752 @node Primary Index, , Error Messages, Top
4753 @unnumbered @code{find} Primary Index
4755 This is a list of all of the primaries (tests, actions, and options)
4756 that make up @code{find} expressions for selecting files. @xref{find
4757 Expressions}, for more information on expressions.
4763 @comment texi related words used by Emacs' spell checker ispell.el
4765 @comment LocalWords: texinfo setfilename settitle setchapternewpage
4766 @comment LocalWords: iftex finalout ifinfo DIR titlepage vskip pt
4767 @comment LocalWords: filll dir samp dfn noindent xref pxref
4768 @comment LocalWords: var deffn texi deffnx itemx emph asis
4769 @comment LocalWords: findex smallexample subsubsection cindex
4770 @comment LocalWords: dircategory direntry itemize
4772 @comment other words used by Emacs' spell checker ispell.el
4773 @comment LocalWords: README fred updatedb xargs Plett Rendell akefile
4774 @comment LocalWords: args grep Filesystems fo foo fOo wildcards iname
4775 @comment LocalWords: ipath regex iregex expr fubar regexps
4776 @comment LocalWords: metacharacters macs sr sc inode lname ilname
4777 @comment LocalWords: sysdep noleaf ls inum xdev filesystems usr atime
4778 @comment LocalWords: ctime mtime amin cmin mmin al daystart Sladkey rm
4779 @comment LocalWords: anewer cnewer bckw rf xtype uname gname uid gid
4780 @comment LocalWords: nouser nogroup chown chgrp perm ch maxdepth
4781 @comment LocalWords: mindepth cpio src CD AFS statted stat fstype ufs
4782 @comment LocalWords: nfs tmp mfs printf fprint dils rw djm Nov lwall
4783 @comment LocalWords: POSIXLY fls fprintf strftime locale's EDT GMT AP
4784 @comment LocalWords: EST diff perl backquotes sprintf Falstad Oct cron
4785 @comment LocalWords: eg vmunix mkdir afs allexec allwrite ARG bigram
4786 @comment LocalWords: bigrams cd chmod comp crc CVS dbfile dum eof
4787 @comment LocalWords: fileserver filesystem fn frcode Ghazi Hnewc iXX
4788 @comment LocalWords: joeuser Kaveh localpaths localuser LOGNAME
4789 @comment LocalWords: Meyering mv netpaths netuser nonblank nonblanks
4790 @comment LocalWords: ois ok Pinard printindex proc procs prunefs
4791 @comment LocalWords: prunepaths pwd RFS rmadillo rmdir rsh sbins str
4792 @comment LocalWords: su Timar ubins ug unstripped vf VM Weitzel
4793 @comment LocalWords: wildcard zlogout basename execdir wholename iwholename
4794 @comment LocalWords: timestamp timestamps Solaris FreeBSD OpenBSD POSIX