1 \input texinfo @c -*-texinfo-*-
4 @settitle Finding Files
5 @c For double-sided printing, uncomment:
6 @c @setchapternewpage odd
10 @include ../locate/dblocation.texi
18 * Finding files: (find). Operating on files matching certain criteria.
21 @dircategory Individual utilities
23 * find: (find)Invoking find. Finding and acting on files.
24 * locate: (find)Invoking locate. Finding files in a database.
25 * updatedb: (find)Invoking updatedb. Building the locate database.
26 * xargs: (find)Invoking xargs. Operating on many files.
31 This file documents the GNU utilities for finding files that match
32 certain criteria and performing various operations on them.
34 Copyright @copyright{} 1994, 1996, 1998, 2000, 2001, 2003, 2004, 2005, 2006,
35 2007, 2008, 2009, 2010, 2011 Free Software Foundation, Inc.
37 Permission is granted to copy, distribute and/or modify this document
38 under the terms of the GNU Free Documentation License, Version 1.3 or
39 any later version published by the Free Software Foundation; with no
40 Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
41 Texts. A copy of the license is included in the section entitled
42 ``GNU Free Documentation License''.
47 @subtitle Edition @value{EDITION}, for GNU @code{find} version @value{VERSION}
48 @subtitle @value{UPDATED}
49 @author by David MacKenzie and James Youngman
52 @vskip 0pt plus 1filll
61 @comment node-name, next, previous, up
64 This file documents the GNU utilities for finding files that match
65 certain criteria and performing various actions on them.
67 This is edition @value{EDITION}, for @code{find} version @value{VERSION}.
70 @c The master menu, created with texinfo-master-menu, goes here.
73 * Introduction:: Summary of the tasks this manual describes.
74 * Finding Files:: Finding files that match certain criteria.
75 * Actions:: Doing things to files you have found.
76 * Databases:: Maintaining file name databases.
77 * File Permissions:: How to control access to files.
78 * Date input formats:: Specifying literal times.
79 * Configuration:: Options you can select at compile time.
80 * Reference:: Summary of how to invoke the programs.
81 * Common Tasks:: Solutions to common real-world problems.
82 * Worked Examples:: Examples demonstrating more complex points.
83 * Security Considerations:: Security issues relating to findutils.
84 * Error Messages:: Explanations of some messages you might see.
85 * GNU Free Documentation License:: Copying and sharing this manual.
86 * Primary Index:: The components of @code{find} expressions.
92 This manual shows how to find files that meet criteria you specify,
93 and how to perform various actions on the files that you find. The
94 principal programs that you use to perform these tasks are
95 @code{find}, @code{locate}, and @code{xargs}. Some of the examples in
96 this manual use capabilities specific to the GNU versions of those
99 GNU @code{find} was originally written by Eric Decker, with
100 enhancements by David MacKenzie, Jay Plett, and Tim Wood. GNU
101 @code{xargs} was originally written by Mike Rendell, with enhancements
102 by David MacKenzie. GNU @code{locate} and its associated utilities
103 were originally written by James Woods, with enhancements by David
104 MacKenzie. The idea for @samp{find -print0} and @samp{xargs -0} came
105 from Dan Bernstein. The current maintainer of GNU findutils (and this
106 manual) is James Youngman. Many other people have contributed bug
107 fixes, small improvements, and helpful suggestions. Thanks!
109 To report a bug in GNU findutils, please use the form on the Savannah
111 @code{http://savannah.gnu.org/bugs/?group=findutils}. Reporting bugs
112 this way means that you will then be able to track progress in fixing
115 If you don't have web access, you can also just send mail to the
116 mailing list. The mailing list @email{bug-findutils@@gnu.org} carries
117 discussion of bugs in findutils, questions and answers about the
118 software and discussion of the development of the programs. To join
119 the list, send email to @email{bug-findutils-request@@gnu.org}.
121 Please read any relevant sections of this manual before asking for
122 help on the mailing list. You may also find it helpful to read the
123 NON-BUGS section of the @code{find} manual page.
125 If you ask for help on the mailing list, people will be able to help
126 you much more effectively if you include the following things:
129 @item The version of the software you are running. You can find this
130 out by running @samp{locate --version}.
131 @item What you were trying to do
132 @item The @emph{exact} command line you used
133 @item The @emph{exact} output you got (if this is very long, try to
134 find a smaller example which exhibits the same problem)
135 @item The output you expected to get
138 It may also be the case that the bug you are describing has already
139 been fixed, if it is a bug. Please check the most recent findutils
140 releases at @url{ftp://ftp.gnu.org/gnu/findutils} and, if possible,
141 the development branch at @url{ftp://alpha.gnu.org/gnu/findutils}.
142 If you take the time to check that your bug still exists in current
143 releases, this will greatly help people who want to help you solve
144 your problem. Please also be aware that if you obtained findutils as
145 part of the GNU/Linux 'distribution', the distributions often lag
146 seriously behind findutils releases, even the stable release. Please
147 check the GNU FTP site.
158 For brevity, the word @dfn{file} in this manual means a regular file,
159 a directory, a symbolic link, or any other kind of node that has a
160 directory entry. A directory entry is also called a @dfn{file name}.
161 A file name may contain some, all, or none of the directories in a
162 path that leads to the file. These are all examples of what this
163 manual calls ``file names'':
170 /usr/local/include/termcap.h
173 A @dfn{directory tree} is a directory and the files it contains, all
174 of its subdirectories and the files they contain, etc. It can also be
175 a single non-directory file.
177 These programs enable you to find the files in one or more directory
182 have names that contain certain text or match a certain pattern;
184 are links to certain files;
186 were last used during a certain period of time;
188 are within a certain size range;
190 are of a certain type (regular file, directory, symbolic link, etc.);
192 are owned by a certain user or group;
194 have certain access permissions or special mode bits;
196 contain text that matches a certain pattern;
198 are within a certain depth in the directory tree;
200 or some combination of the above.
203 Once you have found the files you're looking for (or files that are
204 potentially the ones you're looking for), you can do more to them than
205 simply list their names. You can get any combination of the files'
206 attributes, or process the files in many ways, either individually or
207 in groups of various sizes. Actions that you might want to perform on
208 the files you have found include, but are not limited to:
218 change access permissions
223 This manual describes how to perform each of those tasks, and more.
228 The principal programs used for making lists of files that match given
229 criteria and running commands on them are @code{find}, @code{locate},
230 and @code{xargs}. An additional command, @code{updatedb}, is used by
231 system administrators to create databases for @code{locate} to use.
233 @code{find} searches for files in a directory hierarchy and prints
234 information about the files it found. It is run like this:
237 find @r{[}@var{file}@dots{}@r{]} @r{[}@var{expression}@r{]}
241 Here is a typical use of @code{find}. This example prints the names
242 of all files in the directory tree rooted in @file{/usr/src} whose
243 name ends with @samp{.c} and that are larger than 100 Kilobytes.
245 find /usr/src -name '*.c' -size +100k -print
248 Notice that the wildcard must be enclosed in quotes in order to
249 protect it from expansion by the shell.
251 @code{locate} searches special file name databases for file names that
252 match patterns. The system administrator runs the @code{updatedb}
253 program to create the databases. @code{locate} is run like this:
256 locate @r{[}@var{option}@dots{}@r{]} @var{pattern}@dots{}
260 This example prints the names of all files in the default file name
261 database whose name ends with @samp{Makefile} or @samp{makefile}.
262 Which file names are stored in the database depends on how the system
263 administrator ran @code{updatedb}.
265 locate '*[Mm]akefile'
268 The name @code{xargs}, pronounced EX-args, means ``combine
269 arguments.'' @code{xargs} builds and executes command lines by
270 gathering together arguments it reads on the standard input. Most
271 often, these arguments are lists of file names generated by
272 @code{find}. @code{xargs} is run like this:
275 xargs @r{[}@var{option}@dots{}@r{]} @r{[}@var{command} @r{[}@var{initial-arguments}@r{]}@r{]}
279 The following command searches the files listed in the file
280 @file{file-list} and prints all of the lines in them that contain the
283 xargs grep typedef < file-list
286 @node find Expressions
287 @section @code{find} Expressions
289 The expression that @code{find} uses to select files consists of one
290 or more @dfn{primaries}, each of which is a separate command line
291 argument to @code{find}. @code{find} evaluates the expression each
292 time it processes a file. An expression can contain any of the
293 following types of primaries:
297 affect overall operation rather than the processing of a specific
300 return a true or false value, depending on the file's attributes;
302 have side effects and return a true or false value; and
304 connect the other arguments and affect when and whether they are
308 You can omit the operator between two primaries; it defaults to
309 @samp{-and}. @xref{Combining Primaries With Operators}, for ways to
310 connect primaries into more complex expressions. If the expression
311 contains no actions other than @samp{-prune}, @samp{-print} is
312 performed on all files for which the entire expression is true
313 (@pxref{Print File Name}).
315 Options take effect immediately, rather than being evaluated for each
316 file when their place in the expression is reached. Therefore, for
317 clarity, it is best to place them at the beginning of the expression.
318 There are two exceptions to this; @samp{-daystart} and @samp{-follow}
319 have different effects depending on where in the command line they
320 appear. This can be confusing, so it's best to keep them at the
323 Many of the primaries take arguments, which immediately follow them in
324 the next command line argument to @code{find}. Some arguments are
325 file names, patterns, or other strings; others are numbers. Numeric
326 arguments can be specified as
330 for greater than @var{n},
332 for less than @var{n},
338 @chapter Finding Files
340 By default, @code{find} prints to the standard output the names of the
341 files that match the given criteria. @xref{Actions}, for how to get
342 more information about the matching files.
356 * Combining Primaries With Operators::
362 Here are ways to search for files whose name matches a certain
363 pattern. @xref{Shell Pattern Matching}, for a description of the
364 @var{pattern} arguments to these tests.
366 Each of these tests has a case-sensitive version and a
367 case-insensitive version, whose name begins with @samp{i}. In a
368 case-insensitive comparison, the patterns @samp{fo*} and @samp{F??}
369 match the file names @file{Foo}, @samp{FOO}, @samp{foo}, @samp{fOo},
373 * Base Name Patterns::
374 * Full Name Patterns::
375 * Fast Full Name Search::
376 * Shell Pattern Matching:: Wildcards used by these programs.
379 @node Base Name Patterns
380 @subsection Base Name Patterns
382 @deffn Test -name pattern
383 @deffnx Test -iname pattern
384 True if the base of the file name (the path with the leading
385 directories removed) matches shell pattern @var{pattern}. For
386 @samp{-iname}, the match is case-insensitive.@footnote{Because we
387 need to perform case-insensitive matching, the GNU fnmatch
388 implementation is always used; if the C library includes the GNU
389 implementation, we use that and otherwise we use the one from gnulib}
390 To ignore a whole directory tree, use @samp{-prune}
391 (@pxref{Directories}). As an example, to find Texinfo source files in
392 @file{/usr/local/doc}:
395 find /usr/local/doc -name '*.texi'
398 Notice that the wildcard must be enclosed in quotes in order to
399 protect it from expansion by the shell.
401 As of findutils version 4.2.2, patterns for @samp{-name} and
402 @samp{-iname} will match a file name with a leading @samp{.}. For
403 example the command @samp{find /tmp -name \*bar} will match the file
404 @file{/tmp/.foobar}. Braces within the pattern (@samp{@{@}}) are not
405 considered to be special (that is, @code{find . -name 'foo@{1,2@}'}
406 matches a file named @file{foo@{1,2@}}, not the files @file{foo1} and
409 Because the leading directories are removed, the file names considered
410 for a match with @samp{-name} will never include a slash, so
411 @samp{-name a/b} will never match anything (you probably need to use
412 @samp{-path} instead).
416 @node Full Name Patterns
417 @subsection Full Name Patterns
419 @deffn Test -path pattern
420 @deffnx Test -wholename pattern
421 True if the entire file name, starting with the command line argument
422 under which the file was found, matches shell pattern @var{pattern}.
423 To ignore a whole directory tree, use @samp{-prune} rather than
424 checking every file in the tree (@pxref{Directories}). The ``entire
425 file name'' as used by @code{find} starts with the starting-point
426 specified on the command line, and is not converted to an absolute
427 pathname, so for example @code{cd /; find tmp -wholename /tmp} will
428 never match anything.
430 Find compares the @samp{-path} argument with the concatenation of a
431 directory name and the base name of the file it's considering.
432 Since the concatenation will never end with a slash, @samp{-path}
433 arguments ending in @samp{/} will match nothing (except perhaps a
434 start point specified on the command line).
436 The name @samp{-wholename} is GNU-specific, but @samp{-path} is more
437 portable; it is supported by HP-UX @code{find} and is part of the
442 @deffn Test -ipath pattern
443 @deffnx Test -iwholename pattern
444 These tests are like @samp{-wholename} and @samp{-path}, but the match
449 In the context of the tests @samp{-path}, @samp{-wholename},
450 @samp{-ipath} and @samp{-wholename}, a ``full path'' is the name of
451 all the directories traversed from @code{find}'s start point to the
452 file being tested, followed by the base name of the file itself.
453 These paths are often not absolute paths; for example
457 $ mkdir -p foo/bar/baz
458 $ find foo -path foo/bar -print
460 $ find foo -path /tmp/foo/bar -print
461 $ find /tmp/foo -path /tmp/foo/bar -print
465 Notice that the second @code{find} command prints nothing, even though
466 @file{/tmp/foo/bar} exists and was examined by @code{find}.
468 Unlike file name expansion on the command line, a @samp{*} in the pattern
469 will match both @samp{/} and leading dots in file names:
474 $ find . -path '*/*config'
475 ./quux/bar/baz/.config
479 @deffn Test -regex expr
480 @deffnx Test -iregex expr
481 True if the entire file name matches regular expression @var{expr}.
482 This is a match on the whole path, not a search. For example, to
483 match a file named @file{./fubar3}, you can use the regular expression
484 @samp{.*bar.} or @samp{.*b.*3}, but not @samp{f.*r3}. @xref{Regexps,
485 , Syntax of Regular Expressions, emacs, The GNU Emacs Manual}, for a
486 description of the syntax of regular expressions. For @samp{-iregex},
487 the match is case-insensitive.
489 As for @samp{-path}, the candidate file name never ends with a slash,
490 so regular expressions which only match something that ends in slash
493 There are several varieties of regular expressions; by default this
494 test uses POSIX basic regular expressions, but this can be changed
495 with the option @samp{-regextype}.
498 @deffn Option -regextype name
499 This option controls the variety of regular expression syntax
500 understood by the @samp{-regex} and @samp{-iregex} tests. This option
501 is positional; that is, it only affects regular expressions which
502 occur later in the command line. If this option is not given, GNU
503 Emacs regular expressions are assumed. Currently-implemented types
509 Regular expressions compatible with GNU Emacs; this is also the
510 default behaviour if this option is not used.
512 Regular expressions compatible with the POSIX awk command (not GNU awk)
514 POSIX Basic Regular Expressions.
516 Regular expressions compatible with the POSIX egrep command
518 POSIX Extended Regular Expressions
521 @ref{Regular Expressions} for more information on the regular
522 expression dialects understood by GNU findutils.
527 @node Fast Full Name Search
528 @subsection Fast Full Name Search
530 To search for files by name without having to actually scan the
531 directories on the disk (which can be slow), you can use the
532 @code{locate} program. For each shell pattern you give it,
533 @code{locate} searches one or more databases of file names and
534 displays the file names that contain the pattern. @xref{Shell Pattern
535 Matching}, for details about shell patterns.
537 If a pattern is a plain string -- it contains no
538 metacharacters -- @code{locate} displays all file names in the database
539 that contain that string. If a pattern contains
540 metacharacters, @code{locate} only displays file names that match the
541 pattern exactly. As a result, patterns that contain metacharacters
542 should usually begin with a @samp{*}, and will most often end with one
543 as well. The exceptions are patterns that are intended to explicitly
544 match the beginning or end of a file name.
546 If you only want @code{locate} to match against the last component of
547 the file names (the ``base name'' of the files) you can use the
548 @samp{--basename} option. The opposite behaviour is the default, but
549 can be selected explicitly by using the option @samp{--wholename}.
556 is almost equivalent to
558 find @var{directories} -name @var{pattern}
561 where @var{directories} are the directories for which the file name
562 databases contain information. The differences are that the
563 @code{locate} information might be out of date, and that @code{locate}
564 handles wildcards in the pattern slightly differently than @code{find}
565 (@pxref{Shell Pattern Matching}).
567 The file name databases contain lists of files that were on the system
568 when the databases were last updated. The system administrator can
569 choose the file name of the default database, the frequency with which
570 the databases are updated, and the directories for which they contain
573 Here is how to select which file name databases @code{locate}
574 searches. The default is system-dependent. At the time this document
575 was generated, the default was @file{@value{LOCATE_DB}}.
578 @item --database=@var{path}
580 Instead of searching the default file name database, search the file
581 name databases in @var{path}, which is a colon-separated list of
582 database file names. You can also use the environment variable
583 @code{LOCATE_PATH} to set the list of database files to search. The
584 option overrides the environment variable if both are used.
587 GNU @code{locate} can read file name databases generated by the
588 @code{slocate} package. However, these generally contain a list of
589 all the files on the system, and so when using this database,
590 @code{locate} will produce output only for files which are accessible
591 to you. @xref{Invoking locate}, for a description of the
592 @samp{--existing} option which is used to do this.
594 The @code{updatedb} program can also generate database in a format
595 compatible with @code{slocate}. @xref{Invoking updatedb}, for a
596 description of its @samp{--dbformat} and @samp{--output} options.
599 @node Shell Pattern Matching
600 @subsection Shell Pattern Matching
602 @code{find} and @code{locate} can compare file names, or parts of file
603 names, to shell patterns. A @dfn{shell pattern} is a string that may
604 contain the following special characters, which are known as
605 @dfn{wildcards} or @dfn{metacharacters}.
607 You must quote patterns that contain metacharacters to prevent the
608 shell from expanding them itself. Double and single quotes both work;
609 so does escaping with a backslash.
613 Matches any zero or more characters.
616 Matches any one character.
619 Matches exactly one character that is a member of the string
620 @var{string}. This is called a @dfn{character class}. As a
621 shorthand, @var{string} may contain ranges, which consist of two
622 characters with a dash between them. For example, the class
623 @samp{[a-z0-9_]} matches a lowercase letter, a number, or an
624 underscore. You can negate a class by placing a @samp{!} or @samp{^}
625 immediately after the opening bracket. Thus, @samp{[^A-Z@@]} matches
626 any character except an uppercase letter or an at sign.
629 Removes the special meaning of the character that follows it. This
630 works even in character classes.
633 In the @code{find} tests that do shell pattern matching (@samp{-name},
634 @samp{-wholename}, etc.), wildcards in the pattern will match a
635 @samp{.} at the beginning of a file name. This is also the case for
636 @code{locate}. Thus, @samp{find -name '*macs'} will match a file
637 named @file{.emacs}, as will @samp{locate '*macs'}.
639 Slash characters have no special significance in the shell pattern
640 matching that @code{find} and @code{locate} do, unlike in the shell,
641 in which wildcards do not match them. Therefore, a pattern
642 @samp{foo*bar} can match a file name @samp{foo3/bar}, and a pattern
643 @samp{./sr*sc} can match a file name @samp{./src/misc}.
645 If you want to locate some files with the @samp{locate} command but
646 don't need to see the full list you can use the @samp{--limit} option
647 to see just a small number of results, or the @samp{--count} option to
648 display only the total number of matches.
653 There are two ways that files can be linked together. @dfn{Symbolic
654 links} are a special type of file whose contents are a portion of the
655 name of another file. @dfn{Hard links} are multiple directory entries
656 for one file; the file names all have the same index node
657 (@dfn{inode}) number on the disk.
665 @subsection Symbolic Links
667 Symbolic links are names that reference other files. GNU @code{find}
668 will handle symbolic links in one of two ways; firstly, it can
669 dereference the links for you - this means that if it comes across a
670 symbolic link, it examines the file that the link points to, in order
671 to see if it matches the criteria you have specified. Secondly, it
672 can check the link itself in case you might be looking for the actual
673 link. If the file that the symbolic link points to is also within the
674 directory hierarchy you are searching with the @code{find} command,
675 you may not see a great deal of difference between these two
678 By default, @code{find} examines symbolic links themselves when it
679 finds them (and, if it later comes across the linked-to file, it will
680 examine that, too). If you would prefer @code{find} to dereference
681 the links and examine the file that each link points to, specify the
682 @samp{-L} option to @code{find}. You can explicitly specify the
683 default behaviour by using the @samp{-P} option. The @samp{-H}
684 option is a half-way-between option which ensures that any symbolic
685 links listed on the command line are dereferenced, but other symbolic
688 Symbolic links are different from ``hard links'' in the sense that you
689 need permission to search the directories
690 in the linked-to file name to
691 dereference the link. This can mean that even if you specify the
692 @samp{-L} option, @code{find} may not be able to determine the
693 properties of the file that the link points to (because you don't have
694 sufficient permission). In this situation, @code{find} uses the
695 properties of the link itself. This also occurs if a symbolic link
696 exists but points to a file that is missing.
698 The options controlling the behaviour of @code{find} with respect to
699 links are as follows:
703 @code{find} does not dereference symbolic links at all. This is the
704 default behaviour. This option must be specified before any of the
705 file names on the command line.
707 @code{find} does not dereference symbolic links (except in the case of
708 file names on the command line, which are dereferenced). If a
709 symbolic link cannot be dereferenced, the information for the symbolic
710 link itself is used. This option must be specified before any of the
711 file names on the command line.
713 @code{find} dereferences symbolic links where possible, and where this
714 is not possible it uses the properties of the symbolic link itself.
715 This option must be specified before any of the file names on the
716 command line. Use of this option also implies the same behaviour as
717 the @samp{-noleaf} option. If you later use the @samp{-H} or
718 @samp{-P} options, this does not turn off @samp{-noleaf}.
721 This option forms part of the ``expression'' and must be specified
722 after the file names, but it is otherwise equivalent to @samp{-L}.
723 The @samp{-follow} option affects only those tests which appear after
724 it on the command line. This option is deprecated. Where possible,
725 you should use @samp{-L} instead.
728 The following differences in behaviour occur when the @samp{-L} option
733 @code{find} follows symbolic links to directories when searching
736 @samp{-lname} and @samp{-ilname} always return false (unless they
737 happen to match broken symbolic links).
739 @samp{-type} reports the types of the files that symbolic links point
740 to. This means that in combination with @samp{-L}, @samp{-type l}
741 will be true only for broken symbolic links. To check for symbolic
742 links when @samp{-L} has been specified, use @samp{-xtype l}.
744 Implies @samp{-noleaf} (@pxref{Directories}).
747 If the @samp{-L} option or the @samp{-H} option is used,
748 the file names used as arguments to @samp{-newer}, @samp{-anewer}, and
749 @samp{-cnewer} are dereferenced and the timestamp from the pointed-to
750 file is used instead (if possible -- otherwise the timestamp from the
751 symbolic link is used).
753 @deffn Test -lname pattern
754 @deffnx Test -ilname pattern
755 True if the file is a symbolic link whose contents match shell pattern
756 @var{pattern}. For @samp{-ilname}, the match is case-insensitive.
757 @xref{Shell Pattern Matching}, for details about the @var{pattern}
758 argument. If the @samp{-L} option is in effect, this test will always
759 return false for symbolic links unless they are broken. So, to list
760 any symbolic links to @file{sysdep.c} in the current directory and its
761 subdirectories, you can do:
764 find . -lname '*sysdep.c'
769 @subsection Hard Links
771 Hard links allow more than one name to refer to the same file. To
772 find all the names which refer to the same file as @var{name}, use
773 @samp{-samefile NAME}. If you are not using the @samp{-L} option, you
774 can confine your search to one filesystem using the @samp{-xdev}
775 option. This is useful because hard links cannot point outside a
776 single filesystem, so this can cut down on needless searching.
778 If the @samp{-L} option is in effect, and @var{name} is in fact a symbolic
779 link, the symbolic link will be dereferenced. Hence you are searching
780 for other links (hard or symbolic) to the file pointed to by @var{name}. If
781 @samp{-L} is in effect but @var{name} is not itself a symbolic link, other
782 symbolic links to the file @var{name} will be matched.
784 You can also search for files by inode number. This can occasionally
785 be useful in diagnosing problems with filesystems for example, because
786 @code{fsck} tends to print inode numbers. Inode numbers also
787 occasionally turn up in log messages for some types of software, and
788 are used to support the @code{ftok()} library function.
790 You can learn a file's inode number and the number of links to it by
791 running @samp{ls -li} or @samp{find -ls}.
793 You can search for hard links to inode number NUM by using @samp{-inum
794 NUM}. If there are any filesystem mount points below the directory
795 where you are starting the search, use the @samp{-xdev} option unless
796 you are also using the @samp{-L} option. Using @samp{-xdev} this
797 saves needless searching, since hard links to a file must be on the
798 same filesystem. @xref{Filesystems}.
800 @deffn Test -samefile NAME
801 File is a hard link to the same inode as @var{name}. If the @samp{-L}
802 option is in effect, symbolic links to the same file as @var{name} points to
807 File has inode number @var{n}. The @samp{+} and @samp{-} qualifiers
808 also work, though these are rarely useful. Much of the time it is
809 easier to use @samp{-samefile} rather than this option.
812 You can also search for files that have a certain number of links,
813 with @samp{-links}. Directories normally have at least two hard
814 links; their @file{.} entry is the second one. If they have
815 subdirectories, each of those also has a hard link called @file{..} to
816 its parent directory. The @file{.} and @file{..} directory entries
817 are not normally searched unless they are mentioned on the @code{find}
821 File has @var{n} hard links.
824 @deffn Test -links +n
825 File has more than @var{n} hard links.
828 @deffn Test -links -n
829 File has fewer than @var{n} hard links.
835 Each file has three time stamps, which record the last time that
836 certain operations were performed on the file:
840 access (read the file's contents)
842 change the status (modify the file or its attributes)
844 modify (change the file's contents)
847 Some systems also provide a timestamp that indicates when a file was
848 @emph{created}. For example, the UFS2 filesystem under NetBSD-3.1
849 records the @emph{birth time} of each file. This information is also
850 available under other versions of BSD and some versions of Cygwin.
851 However, even on systems which support file birth time, files may
852 exist for which this information was not recorded (for example, UFS1
853 file systems simply do not contain this information).
855 You can search for files whose time stamps are within a certain age
856 range, or compare them to other time stamps.
860 * Comparing Timestamps::
864 @subsection Age Ranges
866 These tests are mainly useful with ranges (@samp{+@var{n}} and
870 @deffnx Test -ctime n
871 @deffnx Test -mtime n
872 True if the file was last accessed (or its status changed, or it was
873 modified) @var{n}*24 hours ago. The number of 24-hour periods since
874 the file's timestamp is always rounded down; therefore 0 means ``less
875 than 24 hours ago'', 1 means ``between 24 and 48 hours ago'', and so
876 forth. Fractional values are supported but this only really makes
877 sense for the case where ranges (@samp{+@var{n}} and @samp{-@var{n}})
884 True if the file was last accessed (or its status changed, or it was
885 modified) @var{n} minutes ago. These tests provide finer granularity
886 of measurement than @samp{-atime} et al., but rounding is done in a
887 similar way (again, fractions are supported). For example, to list
888 files in @file{/u/bill} that were last read from 2 to 6 minutes ago:
891 find /u/bill -amin +2 -amin -6
895 @deffn Option -daystart
896 Measure times from the beginning of today rather than from 24 hours
897 ago. So, to list the regular files in your home directory that were
898 modified yesterday, do
901 find ~/ -daystart -type f -mtime 1
904 The @samp{-daystart} option is unlike most other options in that it
905 has an effect on the way that other tests are performed. The affected
906 tests are @samp{-amin}, @samp{-cmin}, @samp{-mmin}, @samp{-atime},
907 @samp{-ctime} and @samp{-mtime}. The @samp{-daystart} option only
908 affects the behaviour of any tests which appear after it on the
912 @node Comparing Timestamps
913 @subsection Comparing Timestamps
915 @deffn Test -newerXY reference
916 Succeeds if timestamp @samp{X} of the file being considered is newer
917 than timestamp @samp{Y} of the file @file{reference}. The letters
918 @samp{X} and @samp{Y} can be any of the following letters:
922 Last-access time of @file{reference}
924 Birth time of @file{reference} (when this is not known, the test cannot succeed)
926 Last-change time of @file{reference}
928 Last-modification time of @file{reference}
930 The @file{reference} argument is interpreted as a literal time, rather
931 than the name of a file. @xref{Date input formats}, for a description
932 of how the timestamp is understood. Tests of the form @samp{-newerXt}
933 are valid but tests of the form @samp{-newertY} are not.
936 For example the test @code{-newerac /tmp/foo} succeeds for all files
937 which have been accessed more recently than @file{/tmp/foo} was
938 changed. Here @samp{X} is @samp{a} and @samp{Y} is @samp{c}.
940 Not all files have a known birth time. If @samp{Y} is @samp{b} and
941 the birth time of @file{reference} is not available, @code{find} exits
942 with an explanatory error message. If @samp{X} is @samp{b} and we do
943 not know the birth time the file currently being considered, the test
944 simply fails (that is, it behaves like @code{-false} does).
946 Some operating systems (for example, most implementations of Unix) do
947 not support file birth times. Some others, for example NetBSD-3.1,
948 do. Even on operating systems which support file birth times, the
949 information may not be available for specific files. For example,
950 under NetBSD, file birth times are supported on UFS2 file systems, but
951 not UFS1 file systems.
957 There are two ways to list files in @file{/usr} modified after
958 February 1 of the current year. One uses @samp{-newermt}:
961 find /usr -newermt "Feb 1"
964 The other way of doing this works on the versions of find before 4.3.3:
966 @c Idea from Rick Sladkey.
968 touch -t 02010000 /tmp/stamp$$
969 find /usr -newer /tmp/stamp$$
973 @deffn Test -anewer file
974 @deffnx Test -cnewer file
975 @deffnx Test -newer file
976 True if the file was last accessed (or its status changed, or it was
977 modified) more recently than @var{file} was modified. These tests are
978 affected by @samp{-follow} only if @samp{-follow} comes before them on
979 the command line. @xref{Symbolic Links}, for more information on
980 @samp{-follow}. As an example, to list any files modified since
981 @file{/bin/sh} was last modified:
984 find . -newer /bin/sh
989 True if the file was last accessed @var{n} days after its status was
990 last changed. Useful for finding files that are not being used, and
991 could perhaps be archived or removed to save disk space.
997 @deffn Test -size n@r{[}bckwMG@r{]}
998 True if the file uses @var{n} units of space, rounding up. The units
999 are 512-byte blocks by default, but they can be changed by adding a
1000 one-character suffix to @var{n}:
1004 512-byte blocks (never 1024)
1008 kilobytes (1024 bytes)
1012 Megabytes (units of 1048576 bytes)
1014 Gigabytes (units of 1073741824 bytes)
1017 The `b' suffix always considers blocks to be 512 bytes. This is not
1018 affected by the setting (or non-setting) of the @code{POSIXLY_CORRECT}
1019 environment variable. This behaviour is different from the behaviour of
1020 the @samp{-ls} action). If you want to use 1024-byte units, use the
1023 The number can be prefixed with a `+' or a `-'. A plus sign indicates
1024 that the test should succeed if the file uses at least @var{n} units
1025 of storage (a common use of this test) and a minus sign
1026 indicates that the test should succeed if the file uses less than
1027 @var{n} units of storage. There is no `=' prefix, because that's the
1030 The size does not count indirect blocks, but it does count blocks in
1031 sparse files that are not actually allocated. In other words, it's
1032 consistent with the result you get for @samp{ls -l} or @samp{wc -c}.
1033 This handling of sparse files differs from the output of the @samp{%k}
1034 and @samp{%b} format specifiers for the @samp{-printf} predicate.
1039 True if the file is empty and is either a regular file or a directory.
1040 This might help determine good candidates for deletion. This test is
1041 useful with @samp{-depth} (@pxref{Directories}) and @samp{-delete}
1042 (@pxref{Single File}).
1049 True if the file is of type @var{c}:
1053 block (buffered) special
1055 character (unbuffered) special
1063 symbolic link; if @samp{-L} is in effect, this is true only for broken
1064 symbolic links. If you want to search for symbolic links when
1065 @samp{-L} is in effect, use @samp{-xtype} instead of @samp{-type}.
1073 @deffn Test -xtype c
1074 This test behaves the same as @samp{-type} unless the file is a
1075 symbolic link. If the file is a symbolic link, the result is as
1076 follows (in the table below, @samp{X} should be understood to
1077 represent any letter except @samp{l}):
1080 @item @samp{-P -xtype l}
1081 True if the symbolic link is broken
1082 @item @samp{-P -xtype X}
1083 True if the (ultimate) target file is of type @samp{X}.
1084 @item @samp{-L -xtype l}
1086 @item @samp{-L -xtype X}
1087 False unless the symbolic link is broken
1090 In other words, for symbolic links, @samp{-xtype} checks the type of
1091 the file that @samp{-type} does not check.
1093 The @samp{-H} option also affects the behaviour of @samp{-xtype}.
1094 When @samp{-H} is in effect, @samp{-xtype} behaves as if @samp{-L} had
1095 been specified when examining files listed on the command line, and as
1096 if @samp{-P} had been specified otherwise. If neither @samp{-H} nor
1097 @samp{-L} was specified, @samp{-xtype} behaves as if @samp{-P} had
1100 @xref{Symbolic Links}, for more information on @samp{-follow} and
1107 @deffn Test -user uname
1108 @deffnx Test -group gname
1109 True if the file is owned by user @var{uname} (belongs to group
1110 @var{gname}). A numeric ID is allowed.
1115 True if the file's numeric user ID (group ID) is @var{n}. These tests
1116 support ranges (@samp{+@var{n}} and @samp{-@var{n}}), unlike
1117 @samp{-user} and @samp{-group}.
1121 @deffnx Test -nogroup
1122 True if no user corresponds to the file's numeric user ID (no group
1123 corresponds to the numeric group ID). These cases usually mean that
1124 the files belonged to users who have since been removed from the
1125 system. You probably should change the ownership of such files to an
1126 existing user or group, using the @code{chown} or @code{chgrp}
1131 @section File Mode Bits
1133 @xref{File Permissions}, for information on how file mode bits are
1134 structured and how to specify them.
1136 Four tests determine what users can do with files. These are
1137 @samp{-readable}, @samp{-writable}, @samp{-executable} and
1138 @samp{-perm}. The first three tests ask the operating system if the
1139 current user can perform the relevant operation on a file, while
1140 @samp{-perm} just examines the file's mode. The file mode may give
1141 a misleading impression of what the user can actually do, because the
1142 file may have an access control list, or exist on a read-only
1143 filesystem, for example. Of these four tests though, only
1144 @samp{-perm} is specified by the POSIX standard.
1146 The @samp{-readable}, @samp{-writable} and @samp{-executable} tests
1147 are implemented via the @code{access} system call. This is
1148 implemented within the operating system itself. If the file being
1149 considered is on an NFS filesystem, the remote system may allow or
1150 forbid read or write operations for reasons of which the NFS client
1151 cannot take account. This includes user-ID mapping, either in the
1152 general sense or the more restricted sense in which remote superusers
1153 are treated by the NFS server as if they are the local user
1154 @samp{nobody} on the NFS server.
1156 None of the tests in this section should be used to verify that a user
1157 is authorised to perform any operation (on the file being tested or
1158 any other file) because of the possibility of a race condition. That
1159 is, the situation may change between the test and an action being
1160 taken on the basis of the result of that test.
1163 @deffn Test -readable
1164 True if the file can be read by the invoking user.
1167 @deffn Test -writable
1168 True if the file can be written by the invoking user. This is an
1169 in-principle check, and other things may prevent a successful write
1170 operation; for example, the filesystem might be full.
1173 @deffn Test -executable
1174 True if the file can be executed/searched by the invoking user.
1177 @deffn Test -perm pmode
1179 True if the file's mode bits match @var{pmode}, which can be
1180 either a symbolic or numeric @var{mode} (@pxref{File Permissions})
1181 optionally prefixed by @samp{-} or @samp{/}.
1183 A @var{pmode} that starts with neither @samp{-} nor @samp{/} matches
1184 if @var{mode} exactly matches the file mode bits.
1185 (To avoid confusion with an obsolete GNU extension, @var{mode}
1186 must not start with a @samp{+} immediately followed by an octal digit.)
1188 A @var{pmode} that starts with @samp{-} matches if
1189 @emph{all} the file mode bits set in @var{mode} are set for the file;
1190 bits not set in @var{mode} are ignored.
1192 A @var{pmode} that starts with @samp{/} matches if
1193 @emph{any} of the file mode bits set in @var{mode} are set for the file;
1194 bits not set in @var{mode} are ignored.
1195 This is a GNU extension.
1197 If you don't use the @samp{/} or @samp{-} form with a symbolic mode
1198 string, you may have to specify a rather complex mode string. For
1199 example @samp{-perm g=w} will only match files that have mode 0020
1200 (that is, ones for which group write permission is the only file mode bit
1201 set). It is more likely that you will want to use the @samp{/} or
1202 @samp{-} forms, for example @samp{-perm -g=w}, which matches any file
1203 with group write permission.
1208 Match files that have read and write permission for their owner,
1209 and group, but that the rest of the world can read but not write to.
1210 Do not match files that meet these criteria but have other file mode
1211 bits set (for example if someone can execute/search the file).
1214 Match files that have read and write permission for their owner,
1215 and group, but that the rest of the world can read but not write to,
1216 without regard to the presence of any extra file mode bits (for
1217 example the executable bit). This matches a file with mode
1221 Match files that are writable by somebody (their owner, or
1222 their group, or anybody else).
1225 Match files that are writable by either their owner or their
1226 group. The files don't have to be writable by both the owner and
1227 group to be matched; either will do.
1229 @item -perm /g+w,o+w
1232 @item -perm /g=w,o=w
1236 Match files that are writable by both their owner and their
1239 @item -perm -444 -perm /222 ! -perm /111
1240 Match files that are readable for everybody, have at least one
1241 write bit set (i.e., somebody can write to them), but that cannot be
1242 executed/searched by anybody. Note that in some shells the @samp{!} must be
1245 @item -perm -a+r -perm /a+w ! -perm /a+x
1249 @item -perm -g+w,o+w
1254 If you specify @samp{-perm /000} or @samp{-perm /mode} where the
1255 symbolic mode @samp{mode} has no bits set, the test matches all files.
1256 Versions of GNU @code{find} prior to 4.3.3 matched no files in this
1262 @deffn Test -context pattern
1263 True if file's SELinux context matches the pattern @var{pattern}.
1264 The pattern uses shell glob matching.
1266 This predicate is supported only on @code{find} versions compiled with
1267 SELinux support and only when SELinux is enabled.
1273 To search for files based on their contents, you can use the
1274 @code{grep} program. For example, to find out which C source files in
1275 the current directory contain the string @samp{thing}, you can do:
1278 grep -l thing *.[ch]
1281 If you also want to search for the string in files in subdirectories,
1282 you can combine @code{grep} with @code{find} and @code{xargs}, like
1286 find . -name '*.[ch]' | xargs grep -l thing
1289 The @samp{-l} option causes @code{grep} to print only the names of
1290 files that contain the string, rather than the lines that contain it.
1291 The string argument (@samp{thing}) is actually a regular expression,
1292 so it can contain metacharacters. This method can be refined a little
1293 by using the @samp{-r} option to make @code{xargs} not run @code{grep}
1294 if @code{find} produces no output, and using the @code{find} action
1295 @samp{-print0} and the @code{xargs} option @samp{-0} to avoid
1296 misinterpreting files whose names contain spaces:
1299 find . -name '*.[ch]' -print0 | xargs -r -0 grep -l thing
1302 For a fuller treatment of finding files whose contents match a
1303 pattern, see the manual page for @code{grep}.
1306 @section Directories
1308 Here is how to control which directories @code{find} searches, and how
1309 it searches them. These two options allow you to process a horizontal
1310 slice of a directory tree.
1312 @deffn Option -maxdepth levels
1313 Descend at most @var{levels} (a non-negative integer) levels of
1314 directories below the command line arguments. @samp{-maxdepth 0}
1315 means only apply the tests and actions to the command line arguments.
1318 @deffn Option -mindepth levels
1319 Do not apply any tests or actions at levels less than @var{levels} (a
1320 non-negative integer). @samp{-mindepth 1} means process all files
1321 except the command line arguments.
1324 @deffn Option -depth
1325 Process each directory's contents before the directory itself. Doing
1326 this is a good idea when producing lists of files to archive with
1327 @code{cpio} or @code{tar}. If a directory does not have write
1328 permission for its owner, its contents can still be restored from the
1329 archive since the directory's permissions are restored after its
1334 This is a deprecated synonym for @samp{-depth}, for compatibility with
1335 Mac OS X, FreeBSD and OpenBSD. The @samp{-depth} option is a POSIX
1336 feature, so it is better to use that.
1339 @deffn Action -prune
1340 If the file is a directory, do not descend into it. The result is
1341 true. For example, to skip the directory @file{src/emacs} and all
1342 files and directories under it, and print the names of the other files
1346 find . -wholename './src/emacs' -prune -o -print
1349 The above command will not print @file{./src/emacs} among its list of
1350 results. This however is not due to the effect of the @samp{-prune}
1351 action (which only prevents further descent, it doesn't make sure we
1352 ignore that item). Instead, this effect is due to the use of
1353 @samp{-o}. Since the left hand side of the ``or'' condition has
1354 succeeded for @file{./src/emacs}, it is not necessary to evaluate the
1355 right-hand-side (@samp{-print}) at all for this particular file. If
1356 you wanted to print that directory name you could use either an extra
1357 @samp{-print} action:
1360 find . -wholename './src/emacs' -prune -print -o -print
1363 or use the comma operator:
1366 find . -wholename './src/emacs' -prune , -print
1369 If the @samp{-depth} option is in effect, the subdirectories will have
1370 already been visited in any case. Hence @samp{-prune} has no effect
1373 Because @samp{-delete} implies @samp{-depth}, using @samp{-prune} in
1374 combination with @samp{-delete} may well result in the deletion of
1375 more files than you intended.
1380 Exit immediately (with return value zero if no errors have occurred).
1381 This is different to @samp{-prune} because @samp{-prune} only applies
1382 to the contents of pruned directories, while @samp{-quit} simply makes
1383 @code{find} stop immediately. No child processes will be left
1384 running, but no more files specified on the command line will be
1385 processed. For example, @code{find /tmp/foo /tmp/bar -print -quit}
1386 will print only @samp{/tmp/foo}. Any command lines which have been
1387 built by @samp{-exec ... \+} or @samp{-execdir ... \+} are invoked
1388 before the program is exited.
1391 @deffn Option -noleaf
1392 Do not optimize by assuming that directories contain 2 fewer
1393 subdirectories than their hard link count. This option is needed when
1394 searching filesystems that do not follow the Unix directory-link
1395 convention, such as CD-ROM or MS-DOS filesystems or AFS volume mount
1396 points. Each directory on a normal Unix filesystem has at least 2
1397 hard links: its name and its @file{.} entry. Additionally, its
1398 subdirectories (if any) each have a @file{..} entry linked to that
1399 directory. When @code{find} is examining a directory, after it has
1400 statted 2 fewer subdirectories than the directory's link count, it
1401 knows that the rest of the entries in the directory are
1402 non-directories (@dfn{leaf} files in the directory tree). If only the
1403 files' names need to be examined, there is no need to stat them; this
1404 gives a significant increase in search speed.
1407 @deffn Option -ignore_readdir_race
1408 If a file disappears after its name has been read from a directory but
1409 before @code{find} gets around to examining the file with @code{stat},
1410 don't issue an error message. If you don't specify this option, an
1411 error message will be issued. This option can be useful in system
1412 scripts (cron scripts, for example) that examine areas of the
1413 filesystem that change frequently (mail queues, temporary directories,
1414 and so forth), because this scenario is common for those sorts of
1415 directories. Completely silencing error messages from @code{find} is
1416 undesirable, so this option neatly solves the problem. There is no
1417 way to search one part of the filesystem with this option on and part
1418 of it with this option off, though. When this option is turned on and
1419 find discovers that one of the start-point files specified on the
1420 command line does not exist, no error message will be issued.
1424 @deffn Option -noignore_readdir_race
1425 This option reverses the effect of the @samp{-ignore_readdir_race}
1431 @section Filesystems
1433 A @dfn{filesystem} is a section of a disk, either on the local host or
1434 mounted from a remote host over a network. Searching network
1435 filesystems can be slow, so it is common to make @code{find} avoid
1438 There are two ways to avoid searching certain filesystems. One way is
1439 to tell @code{find} to only search one filesystem:
1442 @deffnx Option -mount
1443 Don't descend directories on other filesystems. These options are
1447 The other way is to check the type of filesystem each file is on, and
1448 not descend directories that are on undesirable filesystem types:
1450 @deffn Test -fstype type
1451 True if the file is on a filesystem of type @var{type}. The valid
1452 filesystem types vary among different versions of Unix; an incomplete
1453 list of filesystem types that are accepted on some version of Unix or
1456 ext2 ext3 proc sysfs ufs 4.2 4.3 nfs tmp mfs S51K S52K
1458 You can use @samp{-printf} with the @samp{%F} directive to see the
1459 types of your filesystems. The @samp{%D} directive shows the device
1460 number. @xref{Print File Information}. @samp{-fstype} is usually
1461 used with @samp{-prune} to avoid searching remote filesystems
1462 (@pxref{Directories}).
1465 @node Combining Primaries With Operators
1466 @section Combining Primaries With Operators
1468 Operators build a complex expression from tests and actions.
1469 The operators are, in order of decreasing precedence:
1472 @item @asis{( @var{expr} )}
1474 Force precedence. True if @var{expr} is true.
1476 @item @asis{! @var{expr}}
1477 @itemx @asis{-not @var{expr}}
1480 True if @var{expr} is false. In some shells, it is necessary to
1481 protect the @samp{!} from shell interpretation by quoting it.
1483 @item @asis{@var{expr1 expr2}}
1484 @itemx @asis{@var{expr1} -a @var{expr2}}
1485 @itemx @asis{@var{expr1} -and @var{expr2}}
1488 And; @var{expr2} is not evaluated if @var{expr1} is false.
1490 @item @asis{@var{expr1} -o @var{expr2}}
1491 @itemx @asis{@var{expr1} -or @var{expr2}}
1494 Or; @var{expr2} is not evaluated if @var{expr1} is true.
1496 @item @asis{@var{expr1} , @var{expr2}}
1498 List; both @var{expr1} and @var{expr2} are always evaluated. True if
1499 @var{expr2} is true. The value of @var{expr1} is discarded. This
1500 operator lets you do multiple independent operations on one traversal,
1501 without depending on whether other operations succeeded. The two
1502 operations @var{expr1} and @var{expr2} are not always fully
1503 independent, since @var{expr1} might have side effects like touching
1504 or deleting files, or it might use @samp{-prune} which would also
1508 @code{find} searches the directory tree rooted at each file name by
1509 evaluating the expression from left to right, according to the rules
1510 of precedence, until the outcome is known (the left hand side is false
1511 for @samp{-and}, true for @samp{-or}), at which point @code{find}
1512 moves on to the next file name.
1514 There are two other tests that can be useful in complex expressions:
1527 There are several ways you can print information about the files that
1528 match the criteria you gave in the @code{find} expression. You can
1529 print the information either to the standard output or to a file that
1530 you name. You can also execute commands that have the file names as
1531 arguments. You can use those commands as further filters to select
1536 * Print File Information::
1542 @node Print File Name
1543 @section Print File Name
1545 @deffn Action -print
1546 True; print the entire file name on the standard output, followed by a
1547 newline. If there is the faintest possibility that one of the files
1548 for which you are searching might contain a newline, you should use
1549 @samp{-print0} instead.
1552 @deffn Action -fprint file
1553 True; print the entire file name into file @var{file}, followed by a
1554 newline. If @var{file} does not exist when @code{find} is run, it is
1555 created; if it does exist, it is truncated to 0 bytes. The named
1556 output file is always created, even if no output is sent to it. The
1557 file names @file{/dev/stdout} and @file{/dev/stderr} are handled
1558 specially; they refer to the standard output and standard error
1559 output, respectively.
1561 If there is the faintest possibility that one of the files for which
1562 you are searching might contain a newline, you should use
1563 @samp{-fprint0} instead.
1567 @c @deffn Option -show-control-chars how
1568 @c This option affects how some of @code{find}'s actions treat
1569 @c unprintable characters in file names. If @samp{how} is
1570 @c @samp{literal}, any subsequent actions (i.e., actions further on in the
1571 @c command line) print file names as-is.
1573 @c If this option is not specified, it currently defaults to @samp{safe}.
1574 @c If @samp{how} is @samp{safe}, C-like backslash escapes are used to
1575 @c indicate the non-printable characters for @samp{-ls} and @samp{-fls}.
1576 @c On the other hand, @samp{-print}, @samp{-fprint}, @samp{-fprintf} and
1577 @c @code{-printf} all quote unprintable characters if the data is going
1578 @c to a tty, and otherwise the data is emitted literally.
1582 @c Escaped if @samp{how} is @samp{safe}
1584 @c Escaped if @samp{how} is @samp{safe}
1586 @c Always quoted if stdout is a tty,
1587 @c @samp{-show-control-chars} is ignored
1589 @c Always literal, never escaped
1591 @c Always quoted if the destination is a tty;
1592 @c @samp{-show-control-chars} is ignored
1594 @c Always literal, never escaped
1596 @c If the destination is a tty, the @samp{%f},
1597 @c @samp{%F}, @samp{%h}, @samp{%l}, @samp{%p},
1598 @c and @samp{%P} directives produce quoted
1599 @c strings if stdout is a tty and are treated
1600 @c literally otherwise.
1602 @c As for @code{-fprintf}.
1607 @node Print File Information
1608 @section Print File Information
1611 True; list the current file in @samp{ls -dils} format on the standard
1612 output. The output looks like this:
1615 204744 17 -rw-r--r-- 1 djm staff 17337 Nov 2 1992 ./lwall-quotes
1622 The inode number of the file. @xref{Hard Links}, for how to find
1623 files based on their inode number.
1626 the number of blocks in the file. The block counts are of 1K blocks,
1627 unless the environment variable @code{POSIXLY_CORRECT} is set, in
1628 which case 512-byte blocks are used. @xref{Size}, for how to find
1629 files based on their size.
1632 The file's type and file mode bits. The type is shown as a dash for a
1633 regular file; for other file types, a letter like for @samp{-type} is
1634 used (@pxref{Type}). The file mode bits are read, write, and execute/search for
1635 the file's owner, its group, and other users, respectively; a dash
1636 means the permission is not granted. @xref{File Permissions}, for
1637 more details about file permissions. @xref{Mode Bits}, for how to
1638 find files based on their file mode bits.
1641 The number of hard links to the file.
1644 The user who owns the file.
1650 The file's size in bytes.
1653 The date the file was last modified.
1656 The file's name. @samp{-ls} quotes non-printable characters in the
1657 file names using C-like backslash escapes. This may change soon, as
1658 the treatment of unprintable characters is harmonised for @samp{-ls},
1659 @samp{-fls}, @samp{-print}, @samp{-fprint}, @samp{-printf} and
1664 @deffn Action -fls file
1665 True; like @samp{-ls} but write to @var{file} like @samp{-fprint}
1666 (@pxref{Print File Name}). The named output file is always created,
1667 even if no output is sent to it.
1670 @deffn Action -printf format
1671 True; print @var{format} on the standard output, interpreting @samp{\}
1672 escapes and @samp{%} directives (more details in the following
1675 Field widths and precisions can be specified as with the @code{printf} C
1676 function. Format flags (like @samp{#} for example) may not work as you
1677 expect because many of the fields, even numeric ones, are printed with
1678 %s. Numeric flags which are affected in this way include @samp{G},
1679 @samp{U}, @samp{b}, @samp{D}, @samp{k} and @samp{n}. This difference in
1680 behaviour means though that the format flag @samp{-} will work; it
1681 forces left-alignment of the field. Unlike @samp{-print},
1682 @samp{-printf} does not add a newline at the end of the string. If you
1683 want a newline at the end of the string, add a @samp{\n}.
1685 As an example, an approximate equivalent of @samp{-ls} with
1686 null-terminated filenames can be achieved with this @code{-printf}
1690 find -printf "%i %4k %M %3n %-8u %-8g %8s %T+ %p\n->%l\0" | cat
1693 A practical reason for doing this would be to get literal filenames in
1694 the output, instead of @samp{-ls}'s backslash-escaped names. (Using
1695 @code{cat} here prevents this happening for the @samp{%p} format
1696 specifier; @pxref{Unusual Characters in File Names}). This format also
1697 outputs a uniform timestamp format.
1699 As for symlinks, the format above outputs the symlink target on a second
1700 line, following @samp{\n->}. There is nothing following the arrow for
1701 non-symlinks. Another approach, for complete consistency, would be to
1702 @code{-fprintf} the symlinks into a separate file, so they too can be
1706 @deffn Action -fprintf file format
1707 True; like @samp{-printf} but write to @var{file} like @samp{-fprint}
1708 (@pxref{Print File Name}). The output file is always created, even if
1709 no output is ever sent to it.
1714 * Format Directives::
1716 * Formatting Flags::
1722 The escapes that @samp{-printf} and @samp{-fprintf} recognise are:
1730 Stop printing from this format immediately and flush the output.
1742 A literal backslash (@samp{\}).
1746 The character whose ASCII code is NNN (octal).
1749 A @samp{\} character followed by any other character is treated as an
1750 ordinary character, so they both are printed, and a warning message is
1751 printed to the standard error output (because it was probably a typo).
1753 @node Format Directives
1754 @subsection Format Directives
1756 @samp{-printf} and @samp{-fprintf} support the following format
1757 directives to print information about the file being processed. The C
1758 @code{printf} function, field width and precision specifiers are
1759 supported, as applied to string (%s) types. That is, you can specify
1760 "minimum field width"."maximum field width" for each directive.
1761 Format flags (like @samp{#} for example) may not work as you expect
1762 because many of the fields, even numeric ones, are printed with %s.
1763 The format flag @samp{-} does work; it forces left-alignment of the
1766 @samp{%%} is a literal percent sign. @xref{Reserved and Unknown
1767 Directives}, for a description of how format directives not mentioned
1770 A @samp{%} at the end of the format argument causes undefined
1771 behaviour since there is no following character. In some locales, it
1772 may hide your door keys, while in others it may remove the final page
1773 from the novel you are reading.
1777 * Ownership Directives::
1779 * Location Directives::
1781 * Other Directives::
1782 * Reserved and Unknown Directives::
1785 @node Name Directives
1786 @subsubsection Name Directives
1791 File's name (not the absolute path name, but the name of the file as
1792 it was encountered by @code{find} - that is, as a relative path from
1793 one of the starting points).
1795 File's name with any leading directories removed (only the last
1799 Leading directories of file's name (all but the last element and the
1800 slash before it). If the file's name contains no slashes (for example
1801 because it was named on the command line and is in the current working
1802 directory), then ``%h'' expands to ``.''. This prevents ``%h/%f''
1803 expanding to ``/foo'', which would be surprising and probably not
1807 File's name with the name of the command line argument under which
1808 it was found removed from the beginning.
1811 Command line argument under which file was found.
1815 @node Ownership Directives
1816 @subsubsection Ownership Directives
1821 File's group name, or numeric group ID if the group has no name.
1824 @c TODO: Needs to support # flag and 0 flag
1825 File's numeric group ID.
1828 File's user name, or numeric user ID if the user has no name.
1831 @c TODO: Needs to support # flag
1832 File's numeric user ID.
1834 @c full support, including # and 0.
1835 File's mode bits (in octal). If you always want to have a leading
1836 zero on the number, use the '#' format flag, for example '%#m'.
1838 The file mode bit numbers used are the traditional Unix
1839 numbers, which will be as expected on most systems, but if your
1840 system's file mode bit layout differs from the traditional Unix
1841 semantics, you will see a difference between the mode as printed by
1842 @samp{%m} and the mode as it appears in @code{struct stat}.
1845 File's type and mode bits (in symbolic form, as for @code{ls}). This
1846 directive is supported in findutils 4.2.5 and later.
1849 @node Size Directives
1850 @subsubsection Size Directives
1854 The amount of disk space used for this file in 1K blocks. Since disk
1855 space is allocated in multiples of the filesystem block size this is
1856 usually greater than %s/1024, but it can also be smaller if the file
1857 is a sparse file (that is, it has ``holes'').
1859 The amount of disk space used for this file in 512-byte blocks. Since
1860 disk space is allocated in multiples of the filesystem block size this
1861 is usually greater than %s/512, but it can also be smaller if the
1862 file is a sparse file (that is, it has ``holes'').
1864 File's size in bytes.
1866 File's sparseness. This is calculated as @code{(BLOCKSIZE*st_blocks /
1867 st_size)}. The exact value you will get for an ordinary file of a
1868 certain length is system-dependent. However, normally sparse files
1869 will have values less than 1.0, and files which use indirect blocks
1870 and have few holes may have a value which is greater than 1.0. The
1871 value used for BLOCKSIZE is system-dependent, but is usually 512
1872 bytes. If the file size is zero, the value printed is undefined. On
1873 systems which lack support for st_blocks, a file's sparseness is
1877 @node Location Directives
1878 @subsubsection Location Directives
1882 File's depth in the directory tree (depth below a file named on the
1883 command line, not depth below the root directory). Files named on the
1884 command line have a depth of 0. Subdirectories immediately below them
1885 have a depth of 1, and so on.
1887 The device number on which the file exists (the @code{st_dev} field of
1888 @code{struct stat}), in decimal.
1890 Type of the filesystem the file is on; this value can be used for
1891 @samp{-fstype} (@pxref{Directories}).
1893 Object of symbolic link (empty string if file is not a symbolic link).
1895 File's inode number (in decimal).
1897 Number of hard links to file.
1899 Type of the file as used with @samp{-type}. If the file is a symbolic
1900 link, @samp{l} will be printed.
1902 Type of the file as used with @samp{-type}. If the file is a symbolic
1903 link, it is dereferenced. If the file is a broken symbolic link,
1904 @samp{N} is printed.
1908 @node Time Directives
1909 @subsubsection Time Directives
1911 Some of these directives use the C @code{ctime} function. Its output
1912 depends on the current locale, but it typically looks like
1915 Wed Nov 2 00:42:36 1994
1920 File's last access time in the format returned by the C @code{ctime}
1923 File's last access time in the format specified by @var{k}
1924 (@pxref{Time Formats}).
1926 File's last status change time in the format returned by the C
1927 @code{ctime} function.
1929 File's last status change time in the format specified by @var{k}
1930 (@pxref{Time Formats}).
1932 File's last modification time in the format returned by the C
1933 @code{ctime} function.
1935 File's last modification time in the format specified by @var{k}
1936 (@pxref{Time Formats}).
1939 @node Other Directives
1940 @subsubsection Other Directives
1944 File's SELinux context, or empty string if the file has no SELinux context.
1947 @node Reserved and Unknown Directives
1948 @subsubsection Reserved and Unknown Directives
1950 The @samp{%(}, @samp{%@{} and @samp{%[} format directives, with or
1951 without field with and precision specifications, are reserved for
1952 future use. Don't use them and don't rely on current experiment to
1953 predict future behaviour. To print @samp{(}, simply use @samp{(}
1954 rather than @samp{%(}. Likewise for @samp{@{} and @samp{[}.
1956 Similarly, a @samp{%} character followed by any other unrecognised
1957 character (i.e., not a known directive or @code{printf} field width
1958 and precision specifier), is discarded (but the unrecognised character
1959 is printed), and a warning message is printed to the standard error
1960 output (because it was probably a typo). Don't rely on this
1961 behaviour, because other directives may be added in the future.
1965 @subsection Time Formats
1967 Below are the formats for the directives @samp{%A}, @samp{%C}, and
1968 @samp{%T}, which print the file's timestamps. Some of these formats
1969 might not be available on all systems, due to differences in the C
1970 @code{strftime} function between systems.
1975 * Combined Time Formats::
1978 @node Time Components
1979 @subsubsection Time Components
1981 The following format directives print single components of the time.
1995 time zone (e.g., EDT), or nothing if no time zone is determinable
1999 second (00..61). There is a fractional part.
2001 seconds since Jan. 1, 1970, 00:00 GMT, with fractional part.
2004 The fractional part of the seconds field is of indeterminate length
2005 and precision. That is, the length of the fractional part of the
2006 seconds field will in general vary between findutils releases and
2007 between systems. This means that it is unwise to assume that field
2008 has any specific length. The length of this field is not usually a
2009 guide to the precision of timestamps in the underlying file system.
2013 @node Date Components
2014 @subsubsection Date Components
2016 The following format directives print single components of the date.
2020 locale's abbreviated weekday name (Sun..Sat)
2022 locale's full weekday name, variable length (Sunday..Saturday)
2025 locale's abbreviated month name (Jan..Dec)
2027 locale's full month name, variable length (January..December)
2031 day of month (01..31)
2035 day of year (001..366)
2037 week number of year with Sunday as first day of week (00..53)
2039 week number of year with Monday as first day of week (00..53)
2043 last two digits of year (00..99)
2046 @node Combined Time Formats
2047 @subsubsection Combined Time Formats
2049 The following format directives print combinations of time and date
2054 time, 12-hour (hh:mm:ss [AP]M)
2056 time, 24-hour (hh:mm:ss)
2058 locale's time representation (H:M:S)
2060 locale's date and time in ctime format (Sat Nov 04 12:02:33 EST
2061 1989). This format does not include any fractional part in the
2066 locale's date representation (mm/dd/yy)
2068 Date and time, separated by '+', for example
2069 `2004-04-28+22:22:05.0000000000'.
2070 The time is given in the current timezone (which may be affected by
2071 setting the TZ environment variable). This is a GNU extension. The
2072 seconds field includes a fractional part.
2075 @node Formatting Flags
2076 @subsection Formatting Flags
2078 The @samp{%m} and @samp{%d} directives support the @samp{#}, @samp{0}
2079 and @samp{+} flags, but the other directives do not, even if they
2080 print numbers. Numeric directives that do not support these flags
2090 All fields support the format flag @samp{-}, which makes fields
2091 left-aligned. That is, if the field width is greater than the actual
2092 contents of the field, the requisite number of spaces are printed
2093 after the field content instead of before it.
2096 @section Run Commands
2098 You can use the list of file names created by @code{find} or
2099 @code{locate} as arguments to other commands. In this way you can
2100 perform arbitrary actions on the files.
2109 @subsection Single File
2111 Here is how to run a command on one file at a time.
2113 @deffn Action -execdir command ;
2114 Execute @var{command}; true if @var{command} returns zero. @code{find}
2115 takes all arguments after @samp{-execdir} to be part of the command until
2116 an argument consisting of @samp{;} is reached. It replaces the string
2117 @samp{@{@}} by the current file name being processed everywhere it
2118 occurs in the command. Both of these constructions need to be escaped
2119 (with a @samp{\}) or quoted to protect them from expansion by the
2120 shell. The command is executed in the directory which @code{find}
2121 was searching at the time the action was executed (that is, @{@} will
2122 expand to a file in the local directory).
2124 For example, to compare each C header file in or below the current
2125 directory with the file @file{/tmp/master}:
2128 find . -name '*.h' -execdir diff -u '@{@}' /tmp/master ';'
2132 If you use @samp{-execdir}, you must ensure that the @samp{$PATH}
2133 variable contains only absolute directory names. Having an empty
2134 element in @samp{$PATH} or explicitly including @samp{.} (or any other
2135 non-absolute name) is insecure. GNU find will refuse to run if you
2136 use @samp{-execdir} and it thinks your @samp{$PATH} setting is
2137 insecure. For example:
2140 @item /bin:/usr/bin:
2141 Insecure; empty path element (at the end)
2142 @item :/bin:/usr/bin:/usr/local/bin
2143 Insecure; empty path element (at the start)
2144 @item /bin:/usr/bin::/usr/local/bin
2145 Insecure; empty path element (two colons in a row)
2146 @item /bin:/usr/bin:.:/usr/local/bin
2147 Insecure; @samp{.} is a path element (@file{.} is not an absolute file name)
2148 @item /bin:/usr/bin:sbin:/usr/local/bin
2149 Insecure; @samp{sbin} is not an absolute file name
2150 @item /bin:/usr/bin:/sbin:/usr/local/bin
2151 Secure (if you control the contents of those directories and any access to them)
2154 Another similar option, @samp{-exec} is supported, but is less secure.
2155 @xref{Security Considerations}, for a discussion of the security
2156 problems surrounding @samp{-exec}.
2159 @deffn Action -exec command ;
2160 This insecure variant of the @samp{-execdir} action is specified by
2161 POSIX. Like @samp{-execdir command ;} it is true if zero is
2162 returned by @var{command}. The main difference is that the command is
2163 executed in the directory from which @code{find} was invoked, meaning
2164 that @samp{@{@}} is expanded to a relative path starting with the name
2165 of one of the starting directories, rather than just the basename of
2168 While some implementations of @code{find} replace the @samp{@{@}} only
2169 where it appears on its own in an argument, GNU @code{find} replaces
2170 @samp{@{@}} wherever it appears.
2174 @node Multiple Files
2175 @subsection Multiple Files
2177 Sometimes you need to process files one at a time. But usually this
2178 is not necessary, and, it is faster to run a command on as many files
2179 as possible at a time, rather than once per file. Doing this saves on
2180 the time it takes to start up the command each time.
2182 The @samp{-execdir} and @samp{-exec} actions have variants that build
2183 command lines containing as many matched files as possible.
2185 @deffn Action -execdir command @{@} +
2186 This works as for @samp{-execdir command ;}, except that the result is
2187 always true, and the @samp{@{@}} at the end of the command is expanded
2188 to a list of names of matching files. This expansion is done in such
2189 a way as to avoid exceeding the maximum command line length available
2190 on the system. Only one @samp{@{@}} is allowed within the command,
2191 and it must appear at the end, immediately before the @samp{+}. A
2192 @samp{+} appearing in any position other than immediately after
2193 @samp{@{@}} is not considered to be special (that is, it does not
2194 terminate the command).
2198 @deffn Action -exec command @{@} +
2199 This insecure variant of the @samp{-execdir} action is specified by
2200 POSIX. The main difference is that the command is executed in the
2201 directory from which @code{find} was invoked, meaning that @samp{@{@}}
2202 is expanded to a relative path starting with the name of one of the
2203 starting directories, rather than just the basename of the matched
2204 file. The result is always true.
2207 Before @code{find} exits, any partially-built command lines are
2208 executed. This happens even if the exit was caused by the
2209 @samp{-quit} action. However, some types of error (for example not
2210 being able to invoke @code{stat()} on the current directory) can cause
2211 an immediate fatal exit. In this situation, any partially-built
2212 command lines will not be invoked (this prevents possible infinite
2215 At first sight, it looks like the list of filenames to be processed
2216 can only be at the end of the command line, and that this might be a
2217 problem for some commands (@code{cp} and @code{rsync} for example).
2219 However, there is a slightly obscure but powerful workaround for this
2220 problem which takes advantage of the behaviour of @code{sh -c}:
2223 find startpoint -tests @dots{} -exec sh -c 'scp "$@@" remote:/dest' sh @{@} +
2226 In the example above, the filenames we want to work on need to occur
2227 on the @code{scp} command line before the name of the destination. We
2228 use the shell to invoke the command @code{scp "$@@" remote:/dest} and
2229 the shell expands @code{"$@@"} to the list of filenames we want to
2232 Another, but less secure, way to run a command on more than one file
2233 at once, is to use the @code{xargs} command, which is invoked like
2237 xargs @r{[}@var{option}@dots{}@r{]} @r{[}@var{command} @r{[}@var{initial-arguments}@r{]}@r{]}
2240 @code{xargs} normally reads arguments from the standard input. These
2241 arguments are delimited by blanks (which can be protected with double
2242 or single quotes or a backslash) or newlines. It executes the
2243 @var{command} (the default is @file{echo}) one or more times with any
2244 @var{initial-arguments} followed by arguments read from standard
2245 input. Blank lines on the standard input are ignored. If the
2246 @samp{-L} option is in use, trailing blanks indicate that @code{xargs}
2247 should consider the following line to be part of this one.
2249 Instead of blank-delimited names, it is safer to use @samp{find
2250 -print0} or @samp{find -fprint0} and process the output by giving the
2251 @samp{-0} or @samp{--null} option to GNU @code{xargs}, GNU @code{tar},
2252 GNU @code{cpio}, or @code{perl}. The @code{locate} command also has a
2253 @samp{-0} or @samp{--null} option which does the same thing.
2255 You can use shell command substitution (backquotes) to process a list
2256 of arguments, like this:
2259 grep -l sprintf `find $HOME -name '*.c' -print`
2262 However, that method produces an error if the length of the @samp{.c}
2263 file names exceeds the operating system's command line length limit.
2264 @code{xargs} avoids that problem by running the command as many times
2265 as necessary without exceeding the limit:
2268 find $HOME -name '*.c' -print | xargs grep -l sprintf
2271 However, if the command needs to have its standard input be a terminal
2272 (@code{less}, for example), you have to use the shell command
2273 substitution method or use the @samp{--arg-file} option of
2276 The @code{xargs} command will process all its input, building command
2277 lines and executing them, unless one of the commands exits with a
2278 status of 255 (this will cause xargs to issue an error message and
2279 stop) or it reads a line contains the end of file string specified
2280 with the @samp{--eof} option.
2283 * Unsafe File Name Handling::
2284 * Safe File Name Handling::
2285 * Unusual Characters in File Names::
2286 * Limiting Command Size::
2287 * Controlling Parallelism::
2288 * Interspersing File Names::
2291 @node Unsafe File Name Handling
2292 @subsubsection Unsafe File Name Handling
2294 Because file names can contain quotes, backslashes, blank characters,
2295 and even newlines, it is not safe to process them using @code{xargs}
2296 in its default mode of operation. But since most files' names do not
2297 contain blanks, this problem occurs only infrequently. If you are
2298 only searching through files that you know have safe names, then you
2299 need not be concerned about it.
2301 Error messages issued by @code{find} and @code{locate} quote unusual
2302 characters in file names in order to prevent unwanted changes in the
2306 @c This example is adapted from:
2307 @c From: pfalstad@stone.Princeton.EDU (Paul John Falstad)
2308 @c Newsgroups: comp.unix.shell
2309 @c Subject: Re: Beware xargs security holes
2310 @c Date: 16 Oct 90 19:12:06 GMT
2312 In many applications, if @code{xargs} botches processing a file
2313 because its name contains special characters, some data might be lost.
2314 The importance of this problem depends on the importance of the data
2315 and whether anyone notices the loss soon enough to correct it.
2316 However, here is an extreme example of the problems that using
2317 blank-delimited names can cause. If the following command is run
2318 daily from @code{cron}, then any user can remove any file on the
2322 find / -name '#*' -atime +7 -print | xargs rm
2325 For example, you could do something like this:
2333 and then @code{cron} would delete @file{/vmunix}, if it ran
2334 @code{xargs} with @file{/} as its current directory.
2336 To delete other files, for example @file{/u/joeuser/.plan}, you could
2344 eg$ mkdir u u/joeuser u/joeuser/.plan'
2346 eg$ echo > u/joeuser/.plan'
2349 eg$ find . -name '#*' -print | xargs echo
2350 ./# ./# /u/joeuser/.plan /#foo
2353 @node Safe File Name Handling
2354 @subsubsection Safe File Name Handling
2356 Here is how to make @code{find} output file names so that they can be
2357 used by other programs without being mangled or misinterpreted. You
2358 can process file names generated this way by giving the @samp{-0} or
2359 @samp{--null} option to GNU @code{xargs}, GNU @code{tar}, GNU
2360 @code{cpio}, or @code{perl}.
2362 @deffn Action -print0
2363 True; print the entire file name on the standard output, followed by a
2367 @deffn Action -fprint0 file
2368 True; like @samp{-print0} but write to @var{file} like @samp{-fprint}
2369 (@pxref{Print File Name}). The output file is always created.
2372 As of findutils version 4.2.4, the @code{locate} program also has a
2373 @samp{--null} option which does the same thing. For similarity with
2374 @code{xargs}, the short form of the option @samp{-0} can also be used.
2376 If you want to be able to handle file names safely but need to run
2377 commands which want to be connected to a terminal on their input, you
2378 can use the @samp{--arg-file} option to @code{xargs} like this:
2381 find / -name xyzzy -print0 > list
2382 xargs --null --arg-file=list munge
2385 The example above runs the @code{munge} program on all the files named
2386 @file{xyzzy} that we can find, but @code{munge}'s input will still be
2387 the terminal (or whatever the shell was using as standard input). If
2388 your shell has the ``process substitution'' feature @samp{<(...)}, you
2389 can do this in just one step:
2392 xargs --null --arg-file=<(find / -name xyzzy -print0) munge
2395 @node Unusual Characters in File Names
2396 @subsubsection Unusual Characters in File Names
2397 As discussed above, you often need to be careful about how the names
2398 of files are handled by @code{find} and other programs. If the output
2399 of @code{find} is not going to another program but instead is being
2400 shown on a terminal, this can still be a problem. For example, some
2401 character sequences can reprogram the function keys on some terminals.
2402 @xref{Security Considerations}, for a discussion of other security
2403 problems relating to @code{find}.
2405 Unusual characters are handled differently by various
2406 actions, as described below.
2411 Always print the exact file name, unchanged, even if the output is
2412 going to a terminal.
2415 Always print the exact file name, unchanged. This will probably
2416 change in a future release.
2419 Unusual characters are always escaped. White space, backslash, and
2420 double quote characters are printed using C-style escaping (for
2421 example @samp{\f}, @samp{\"}). Other unusual characters are printed
2422 using an octal escape. Other printable characters (for @samp{-ls} and
2423 @samp{-fls} these are the characters between octal 041 and 0176) are
2427 If the output is not going to a terminal, it is printed as-is.
2428 Otherwise, the result depends on which directive is in use:
2431 @item %D, %F, %H, %Y, %y
2432 These expand to values which are not under control of files' owners,
2433 and so are printed as-is.
2434 @item %a, %b, %c, %d, %g, %G, %i, %k, %m, %M, %n, %s, %t, %u, %U
2435 These have values which are under the control of files' owners but
2436 which cannot be used to send arbitrary data to the terminal, and so
2437 these are printed as-is.
2438 @item %f, %h, %l, %p, %P
2439 The output of these directives is quoted if the output is going to a
2440 terminal. The setting of the @code{LC_CTYPE} environment
2441 variable is used to determine which characters need to be quoted.
2443 This quoting is performed in the same way as for GNU @code{ls}. This
2444 is not the same quoting mechanism as the one used for @samp{-ls} and
2445 @samp{fls}. If you are able to decide what format to use for the
2446 output of @code{find} then it is normally better to use @samp{\0} as a
2447 terminator than to use newline, as file names can contain white space
2448 and newline characters.
2452 Quoting is handled in the same way as for the @samp{%p} directive of
2453 @samp{-printf} and @samp{-fprintf}. If you are using @code{find} in a
2454 script or in a situation where the matched files might have arbitrary
2455 names, you should consider using @samp{-print0} instead of
2460 The @code{locate} program quotes and escapes unusual characters in
2461 file names in the same way as @code{find}'s @samp{-print} action.
2463 The behaviours described above may change soon, as the treatment of
2464 unprintable characters is harmonised for @samp{-ls}, @samp{-fls},
2465 @samp{-print}, @samp{-fprint}, @samp{-printf} and @samp{-fprintf}.
2467 @node Limiting Command Size
2468 @subsubsection Limiting Command Size
2470 @code{xargs} gives you control over how many arguments it passes to
2471 the command each time it executes it. By default, it uses up to
2472 @code{ARG_MAX} - 2k, or 128k, whichever is smaller, characters per
2473 command. It uses as many lines and arguments as fit within that
2474 limit. The following options modify those values.
2477 @item --no-run-if-empty
2479 If the standard input does not contain any nonblanks, do not run the
2480 command. By default, the command is run once even if there is no
2481 input. This option is a GNU extension.
2483 @item --max-lines@r{[}=@var{max-lines}@r{]}
2484 @itemx -L @var{max-lines}
2485 @itemx -l@r{[}@var{max-lines}@r{]}
2486 Use at most @var{max-lines} nonblank input lines per command line;
2487 @var{max-lines} defaults to 1 if omitted; omitting the argument is not
2488 allowed in the case of the @samp{-L} option. Trailing blanks cause an
2489 input line to be logically continued on the next input line, for the
2490 purpose of counting the lines. Implies @samp{-x}. The preferred name
2491 for this option is @samp{-L} as this is specified by POSIX.
2493 @item --max-args=@var{max-args}
2494 @itemx -n @var{max-args}
2495 Use at most @var{max-args} arguments per command line. Fewer than
2496 @var{max-args} arguments will be used if the size (see the @samp{-s}
2497 option) is exceeded, unless the @samp{-x} option is given, in which
2498 case @code{xargs} will exit.
2500 @item --max-chars=@var{max-chars}
2501 @itemx -s @var{max-chars}
2502 Use at most @var{max-chars} characters per command line, including the
2503 command initial arguments and the terminating nulls at the ends of the
2504 argument strings. If you specify a value for this option which is too
2505 large or small, a warning message is printed and the appropriate upper
2506 or lower limit is used instead. You can use @samp{--show-limits}
2507 option to understand the command-line limits applying to @code{xargs}
2508 and how this is affected by any other options. The POSIX limits shown
2509 when you do this have already been adjusted to take into account the
2510 size of your environment variables.
2512 The largest allowed value is system-dependent, and is calculated as
2513 the argument length limit for exec, less the size of your environment,
2514 less 2048 bytes of headroom. If this value is more than 128KiB,
2515 128Kib is used as the default value; otherwise, the default value is
2519 @node Controlling Parallelism
2520 @subsubsection Controlling Parallelism
2522 Normally, @code{xargs} runs one command at a time. This is called
2523 "serial" execution; the commands happen in a series, one after another.
2524 If you'd like @code{xargs} to do things in "parallel", you can ask it
2525 to do so, either when you invoke it, or later while it is running.
2526 Running several commands at one time can make the entire operation
2527 go more quickly, if the commands are independent, and if your system
2528 has enough resources to handle the load. When parallelism works in
2529 your application, @code{xargs} provides an easy way to get your work
2533 @item --max-procs=@var{max-procs}
2534 @itemx -P @var{max-procs}
2535 Run up to @var{max-procs} processes at a time; the default is 1. If
2536 @var{max-procs} is 0, @code{xargs} will run as many processes as
2537 possible at a time. Use the @samp{-n}, @samp{-s}, or @samp{-L} option
2538 with @samp{-P}; otherwise chances are that the command will be run
2542 For example, suppose you have a directory tree of large image files
2543 and a @code{makeallsizes} script that takes a single file name and
2544 creates various sized images from it (thumbnail-sized, web-page-sized,
2545 printer-sized, and the original large file). The script is doing enough
2546 work that it takes significant time to run, even on a single image.
2550 find originals -name '*.jpg' | xargs -1 makeallsizes
2553 This will run @code{makeallsizes @var{filename}} once for each @code{.jpg}
2554 file in the @code{originals} directory. However, if your system has
2555 two central processors, this script will only keep one of them busy.
2556 Instead, you could probably finish in about half the time by running:
2559 find originals -name '*.jpg' | xargs -1 -P 2 makeallsizes
2562 @code{xargs} will run the first two commands in parallel, and then
2563 whenever one of them terminates, it will start another one, until
2564 the entire job is done.
2566 The same idea can be generalized to as many processors as you have handy.
2567 It also generalizes to other resources besides processors. For example,
2568 if @code{xargs} is running commands that are waiting for a response from a
2569 distant network connection, running a few in parallel may reduce the
2570 overall latency by overlapping their waiting time.
2572 If you are running commands in parallel, you need to think about how
2573 they should arbitrate access to any resources that they share. For
2574 example, if more than one of them tries to print to stdout, the ouptut
2575 will be produced in an indeterminate order (and very likely mixed up)
2576 unless the processes collaborate in some way to prevent this. Using
2577 some kind of locking scheme is one way to prevent such problems. In
2578 general, using a locking scheme will help ensure correct output but
2579 reduce performance. If you don't want to tolerate the performance
2580 difference, simply arrange for each process to produce a separate output
2581 file (or otherwise use separate resources).
2583 @code{xargs} also allows you to ``turn up'' or ``turn down'' its parallelism
2584 in the middle of a run. Suppose you are keeping your four-processor
2585 system busy for hours, processing thousands of images using @code{-P 4}.
2586 Now, in the middle of the run, you or someone else wants you to reduce
2587 your load on the system, so that something else will run faster.
2588 If you interrupt @code{xargs}, your job will be half-done, and it
2589 may take significant manual work to resume it only for the remaining
2590 images. If you suspend @code{xargs} using your shell's job controls
2591 (e.g. @code{control-Z}), then it will get no work done while suspended.
2593 Find out the process ID of the @code{xargs} process, either from your
2594 shell or with the @code{ps} command. After you send it the signal
2595 @code{SIGUSR2}, @code{xargs} will run one fewer command in parallel.
2596 If you send it the signal @code{SIGUSR1}, it will run one more command
2597 in parallel. For example:
2600 shell$ xargs <allimages -1 -P 4 makeallsizes &
2602 ... at some later point ...
2603 shell$ kill -USR2 27643
2604 shell$ kill -USR2 %4
2607 The first @code{kill} command will cause @code{xargs} to wait for
2608 two commands to terminate before starting the next command (reducing
2609 the parallelism from 4 to 3). The second @code{kill} will reduce it from
2610 3 to 2. (@code{%4} works in some shells as a shorthand for the process
2611 ID of the background job labeled @code{[4]}.)
2613 Similarly, if you started a long @code{xargs} job without parallelism, you
2614 can easily switch it to start running two commands in parallel by sending
2615 it a @code{SIGUSR1}.
2617 @code{xargs} will never terminate any existing commands when you ask it
2618 to run fewer processes. It merely waits for the excess commands to
2619 finish. If you ask it to run more commands, it will start the next
2620 one immediately (if it has more work to do).
2622 If you send several identical signals quickly, the operating system
2623 does not guarantee that each of them will be delivered to @code{xargs}.
2624 This means that you can't rapidly increase or decrease the parallelism by
2625 more than one command at a time. You can avoid this problem by sending
2626 a signal, observing the result, then sending the next one; or merely by
2627 delaying for a few seconds between signals (unless your system is very
2630 Whether or not parallel execution will work well for you depends on
2631 the nature of the commmand you are running in parallel, on the
2632 configuration of the system on which you are running the command, and
2633 on the other work being done on the system at the time.
2635 @node Interspersing File Names
2636 @subsubsection Interspersing File Names
2638 @code{xargs} can insert the name of the file it is processing between
2639 arguments you give for the command. Unless you also give options to
2640 limit the command size (@pxref{Limiting Command Size}), this mode of
2641 operation is equivalent to @samp{find -exec} (@pxref{Single File}).
2644 @item --replace@r{[}=@var{replace-str}@r{]}
2645 @itemx -I @var{replace-str}
2646 @itemx -i @var{replace-str}
2647 Replace occurrences of @var{replace-str} in the initial arguments with
2648 names read from the input. Also, unquoted blanks do not terminate
2649 arguments; instead, the input is split at newlines only. For the
2650 @samp{-i} option, if @var{replace-str} is omitted for @samp{--replace}
2651 or @samp{-i}, it defaults to @samp{@{@}} (like for @samp{find -exec}).
2652 Implies @samp{-x} and @samp{-l 1}. @samp{-i} is deprecated in favour
2653 of @samp{-I}. As an example, to sort each file in the @file{bills}
2654 directory, leaving the output in that file name with @file{.sorted}
2655 appended, you could do:
2658 find bills -type f | xargs -I XX sort -o XX.sorted XX
2662 The equivalent command using @samp{find -execdir} is:
2665 find bills -type f -execdir sort -o '@{@}.sorted' '@{@}' ';'
2670 When you use the @samp{-I} option, each line read from the input is
2671 buffered internally. This means that there is an upper limit on the
2672 length of input line that @code{xargs} will accept when used with the
2673 @samp{-I} option. To work around this limitation, you can use the
2674 @samp{-s} option to increase the amount of buffer space that xargs
2675 uses, and you can also use an extra invocation of xargs to ensure that
2676 very long lines do not occur. For example:
2679 somecommand | xargs -s 50000 echo | xargs -I '@{@}' -s 100000 rm '@{@}'
2682 Here, the first invocation of @code{xargs} has no input line length
2683 limit because it doesn't use the @samp{-I} option. The second
2684 invocation of @code{xargs} does have such a limit, but we have ensured
2685 that it never encounters a line which is longer than it can
2688 This is not an ideal solution. Instead, the @samp{-I} option should
2689 not impose a line length limit (apart from any limit imposed by the
2690 operating system) and so one might consider this limitation to be a
2691 bug. A better solution would be to allow @code{xargs -I} to
2692 automatically move to a larger value for the @samp{-s} option when
2695 This sort of problem doesn't occur with the output of @code{find}
2696 because it emits just one filename per line.
2699 @subsection Querying
2701 To ask the user whether to execute a command on a single file, you can
2702 use the @code{find} primary @samp{-okdir} instead of @samp{-execdir},
2703 and the @code{find} primary @samp{-ok} instead of @samp{-exec}:
2705 @deffn Action -okdir command ;
2706 Like @samp{-execdir} (@pxref{Single File}), but ask the user first.
2707 If the user does not agree to run the command, just return false.
2708 Otherwise, run it, with standard input redirected from
2711 The response to the prompt is matched against a pair of regular
2712 expressions to determine if it is a yes or no response. These regular
2713 expressions are obtained from the system (@code{nl_langinfo} items
2714 YESEXPR and NOEXPR are used) if the @code{POSIXLY_CORRECT} environment
2715 variable is set and the system has such patterns available. Otherwise,
2716 @code{find}'s message translations are used. In either case, the
2717 @code{LC_MESSAGES} environment variable will determine the regular
2718 expressions used to determine if the answer is affirmative or negative.
2719 The interpretation of the regular expressions themselves will be
2720 affected by the environment variables @code{LC_CTYPE} (character
2721 classes) and @code{LC_COLLATE} (character ranges and equivalence
2725 @deffn Action -ok command ;
2726 This insecure variant of the @samp{-okdir} action is specified by
2727 POSIX. The main difference is that the command is executed in the
2728 directory from which @code{find} was invoked, meaning that @samp{@{@}}
2729 is expanded to a relative path starting with the name of one of the
2730 starting directories, rather than just the basename of the matched
2731 file. If the command is run, its standard input is redirected from
2735 When processing multiple files with a single command, to query the
2736 user you give @code{xargs} the following option. When using this
2737 option, you might find it useful to control the number of files
2738 processed per invocation of the command (@pxref{Limiting Command
2744 Prompt the user about whether to run each command line and read a line
2745 from the terminal. Only run the command line if the response starts
2746 with @samp{y} or @samp{Y}. Implies @samp{-t}.
2750 @section Delete Files
2752 @deffn Action -delete
2753 Delete files or directories; true if removal succeeded. If the
2754 removal failed, an error message is issued.
2756 The use of the @samp{-delete} action on the command line automatically
2757 turns on the @samp{-depth} option (@pxref{find Expressions}). This
2758 can be surprising if you were previously just testing with
2759 @samp{-print}, so it is usually best to remember to use @samp{-depth}
2762 If @samp{-delete} fails, @code{find}'s exit status will be nonzero
2763 (when it eventually exits).
2767 @section Adding Tests
2769 You can test for file attributes that none of the @code{find} builtin
2770 tests check. To do this, use @code{xargs} to run a program that
2771 filters a list of files printed by @code{find}. If possible, use
2772 @code{find} builtin tests to pare down the list, so the program run by
2773 @code{xargs} has less work to do. The tests builtin to @code{find}
2774 will likely run faster than tests that other programs perform.
2776 For reasons of efficiency it is often useful to limit the number of
2777 times an external program has to be run. For this reason, it is often
2778 a good idea to implement ``extended'' tests by using @code{xargs}.
2780 For example, here is a way to print the names of all of the unstripped
2781 binaries in the @file{/usr/local} directory tree. Builtin tests avoid
2782 running @code{file} on files that are not regular files or are not
2786 find /usr/local -type f -perm /a=x | xargs file |
2787 grep 'not stripped' | cut -d: -f1
2791 The @code{cut} program removes everything after the file name from the
2792 output of @code{file}.
2794 However, using @code{xargs} can present important security problems
2795 (@pxref{Security Considerations}). These can be avoided by using
2796 @samp{-execdir}. The @samp{-execdir} action is also a useful way of
2797 putting your own test in the middle of a set of other tests or actions
2798 for @code{find} (for example, you might want to use @samp{-prune}).
2800 @c Idea from Martin Weitzel.
2801 To place a special test somewhere in the middle of a @code{find}
2802 expression, you can use @samp{-execdir} (or, less securely,
2803 @samp{-exec}) to run a program that performs the test. Because
2804 @samp{-execdir} evaluates to the exit status of the executed program,
2805 you can use a program (which can be a shell script) that tests for a
2806 special attribute and make it exit with a true (zero) or false
2807 (non-zero) status. It is a good idea to place such a special test
2808 @emph{after} the builtin tests, because it starts a new process which
2809 could be avoided if a builtin test evaluates to false.
2811 Here is a shell script called @code{unstripped} that checks whether
2812 its argument is an unstripped binary file:
2816 file "$1" | grep -q "not stripped"
2820 This script relies on the shell exiting with the status of
2821 the last command in the pipeline, in this case @code{grep}. The
2822 @code{grep} command exits with a true status if it found any matches,
2823 false if not. Here is an example of using the script (assuming it is
2824 in your search path). It lists the stripped executables (and shell
2825 scripts) in the file @file{sbins} and the unstripped ones in
2829 find /usr/local -type f -perm /a=x \
2830 \( -execdir unstripped '@{@}' \; -fprint ubins -o -fprint sbins \)
2835 @chapter File Name Databases
2837 The file name databases used by @code{locate} contain lists of files
2838 that were in particular directory trees when the databases were last
2839 updated. The file name of the default database is determined when
2840 @code{locate} and @code{updatedb} are configured and installed. The
2841 frequency with which the databases are updated and the directories for
2842 which they contain entries depend on how often @code{updatedb} is run,
2843 and with which arguments.
2845 You can obtain some statistics about the databases by using
2846 @samp{locate --statistics}.
2849 * Database Locations::
2850 * Database Formats::
2851 * Newline Handling::
2855 @node Database Locations
2856 @section Database Locations
2858 There can be multiple file name databases. Users can select which
2859 databases @code{locate} searches using the @code{LOCATE_PATH}
2860 environment variable or a command line option. The system
2861 administrator can choose the file name of the default database, the
2862 frequency with which the databases are updated, and the directories
2863 for which they contain entries. File name databases are updated by
2864 running the @code{updatedb} program, typically nightly.
2866 In networked environments, it often makes sense to build a database at
2867 the root of each filesystem, containing the entries for that
2868 filesystem. @code{updatedb} is then run for each filesystem on the
2869 fileserver where that filesystem is on a local disk, to prevent
2870 thrashing the network.
2872 @xref{Invoking updatedb}, for the description of the options to
2873 @code{updatedb}. These options can be used to specify which
2874 directories are indexed by each database file.
2876 The default location for the locate database depends on how findutils
2877 is built, but the findutils installation accompanying this manual uses
2878 the default location @file{@value{LOCATE_DB}}.
2880 If no database exists at @file{@value{LOCATE_DB}} but the user did not
2881 specify where to look (by using @samp{-d} or setting
2882 @code{LOCATE_PATH}), then @code{locate} will also check for a
2883 ``secure'' database in @file{/var/lib/slocate/slocate.db}.
2885 @node Database Formats
2886 @section Database Formats
2888 The file name databases contain lists of files that were in particular
2889 directory trees when the databases were last updated. The file name
2890 database format changed starting with GNU @code{locate} version 4.0 to
2891 allow machines with different byte orderings to share the databases.
2893 GNU @code{locate} can read both the old and new database formats.
2894 However, old versions of @code{locate} (on other Unix systems, or GNU
2895 @code{locate} before version 4.0) produce incorrect results if run
2896 against a database in something other than the old format.
2898 Support for the old database format will eventually be discontinued,
2899 first in @code{updatedb} and later in @code{locate}.
2901 If you run @samp{locate --statistics}, the resulting summary indicates
2902 the type of each @code{locate} database. You select which database
2903 format @code{updatedb} will use with the @samp{--dbformat} option.
2907 * LOCATE02 Database Format::
2908 * Sample LOCATE02 Database::
2909 * slocate Database Format::
2910 * Old Database Format::
2913 @node LOCATE02 Database Format
2914 @subsection LOCATE02 Database Format
2916 @code{updatedb} runs a program called @code{frcode} to
2917 @dfn{front-compress} the list of file names, which reduces the
2918 database size by a factor of 4 to 5. Front-compression (also known as
2919 incremental encoding) works as follows.
2921 The database entries are a sorted list (case-insensitively, for users'
2922 convenience). Since the list is sorted, each entry is likely to share
2923 a prefix (initial string) with the previous entry. Each database
2924 entry begins with an offset-differential count byte, which is the
2925 additional number of characters of prefix of the preceding entry to
2926 use beyond the number that the preceding entry is using of its
2927 predecessor. (The counts can be negative.) Following the count is a
2928 null-terminated ASCII remainder -- the part of the name that follows
2931 If the offset-differential count is larger than can be stored in a
2932 byte (+/-127), the byte has the value 0x80 and the count follows in a
2933 2-byte word, with the high byte first (network byte order).
2935 Every database begins with a dummy entry for a file called
2936 @file{LOCATE02}, which @code{locate} checks for to ensure that the
2937 database file has the correct format; it ignores the entry in doing
2940 Databases cannot be concatenated together, even if the first (dummy)
2941 entry is trimmed from all but the first database. This is because the
2942 offset-differential count in the first entry of the second and
2943 following databases will be wrong.
2945 In the output of @samp{locate --statistics}, the new database format
2946 is referred to as @samp{LOCATE02}.
2948 @node Sample LOCATE02 Database
2949 @subsection Sample LOCATE02 Database
2951 Sample input to @code{frcode}:
2952 @c with nulls changed to newlines:
2956 /usr/src/cmd/aardvark.c
2957 /usr/src/cmd/armadillo.c
2961 Length of the longest prefix of the preceding entry to share:
2970 Output from @code{frcode}, with trailing nulls changed to newlines
2971 and count bytes made printable:
2981 (6 = 14 - 8, and -9 = 5 - 14)
2983 @node slocate Database Format
2984 @subsection slocate Database Format
2986 The @code{slocate} program uses a database format similar to, but not
2987 quite the same as, GNU @code{locate}. The first byte of the database
2988 specifies its @dfn{security level}. If the security level is 0,
2989 @code{slocate} will read, match and print filenames on the basis of
2990 the information in the database only. However, if the security level
2991 byte is 1, @code{slocate} omits entries from its output if the
2992 invoking user is unable to access them. The second byte of the
2993 database is zero. The second byte is immediately followed by the
2994 first database entry. The first entry in the database is not preceded
2995 by any differential count or dummy entry. Instead the differential
2996 count for the first item is assumed to be zero.
2998 Starting with the second entry (if any) in the database, data is
2999 interpreted as for the GNU LOCATE02 format.
3001 @node Old Database Format
3002 @subsection Old Database Format
3004 The old database format is used by Unix @code{locate} and @code{find}
3005 programs and earlier releases of the GNU ones. @code{updatedb}
3006 produces this format if given the @samp{--old-format} option.
3008 @code{updatedb} runs programs called @code{bigram} and @code{code} to
3009 produce old-format databases. The old format differs from the new one
3010 in the following ways. Instead of each entry starting with an
3011 offset-differential count byte and ending with a null, byte values
3012 from 0 through 28 indicate offset-differential counts from -14 through
3013 14. The byte value indicating that a long offset-differential count
3014 follows is 0x1e (30), not 0x80. The long counts are stored in host
3015 byte order, which is not necessarily network byte order, and host
3016 integer word size, which is usually 4 bytes. They also represent a
3017 count 14 less than their value. The database lines have no
3018 termination byte; the start of the next line is indicated by its first
3019 byte having a value <= 30.
3021 In addition, instead of starting with a dummy entry, the old database
3022 format starts with a 256 byte table containing the 128 most common
3023 bigrams in the file list. A bigram is a pair of adjacent bytes.
3024 Bytes in the database that have the high bit set are indexes (with the
3025 high bit cleared) into the bigram table. The bigram and
3026 offset-differential count coding makes these databases 20-25% smaller
3027 than the new format, but makes them not 8-bit clean. Any byte in a
3028 file name that is in the ranges used for the special codes is replaced
3029 in the database by a question mark, which not coincidentally is the
3030 shell wildcard to match a single character.
3032 The old format therefore cannot faithfully store entries with
3033 non-ASCII characters. It therefore should not be used in
3034 internationalised environments. That is, most installations should
3037 Because the long counts are stored by the @code{code} program as
3038 native-order machine words, the database format is not easily used in
3039 environments which differ in terms of byte order. If locate databases
3040 are to be shared between machines, the LOCATE02 database format should
3041 be used. This has other benefits as discussed above. However, the
3042 length of the filename currently being processed can normally be used
3043 to place reasonable limits on the long counts and so this information
3044 is used by locate to help it guess the byte ordering of the old format
3045 database. Unless it finds evidence to the contrary, @code{locate}
3046 will assume that the byte order of the database is the same as the
3047 native byte order of the machine running @code{locate}. The output of
3048 @samp{locate --statistics} also includes information about the byte
3049 order of old-format databases.
3051 The output of @samp{locate --statistics} will give an incorrect count
3052 of the number of file names containing newlines or high-bit characters
3053 for old-format databases.
3055 Old versions of GNU @code{locate} fail to correctly handle very long
3056 file names, possibly leading to security problems relating to a heap
3057 buffer overrun. @xref{Security Considerations for locate}, for a
3058 detailed explanation.
3060 @node Newline Handling
3061 @section Newline Handling
3063 Within the database, file names are terminated with a null character.
3064 This is the case for both the old and the new format.
3066 When the new database format is being used, the compression technique
3067 used to generate the database though relies on the ability to sort the
3068 list of files before they are presented to @code{frcode}.
3070 If the system's sort command allows its input list of files to be
3071 separated with null characters via the @samp{-z} option, this option
3072 is used and therefore @code{updatedb} and @code{locate} will both
3073 correctly handle file names containing newlines. If the @code{sort}
3074 command lacks support for this, the list of files is delimited with
3075 the newline character, meaning that parts of file names containing
3076 newlines will be incorrectly sorted. This can result in both
3077 incorrect matches and incorrect failures to match.
3079 On the other hand, if you are using the old database format, file
3080 names with embedded newlines are not correctly handled. There is no
3081 technical limitation which enforces this, it's just that the
3082 @code{bigram} program has not been updated to support lists of file
3083 names separated by nulls.
3085 So, if you are using the new database format (this is the default) and
3086 your system uses GNU @code{sort}, newlines will be correctly handled
3087 at all times. Otherwise, newlines may not be correctly handled.
3089 @node File Permissions
3090 @chapter File Permissions
3094 @include parse-datetime.texi
3097 @chapter Configuration
3099 The findutils source distribution includes a @code{configure} script
3100 which examines the system and generates files required to build
3101 findutils. See the files @file{README} and @file{INSTALL}.
3103 A number of options can be specified on the @code{configure} command
3104 line, and many of these are straightforward, adequately documented in
3105 the @code{--help} output, or not normally useful. Options which are
3106 useful or which are not obvious are explained here.
3109 * Leaf Optimisation:: Take advantage of Unix file system semantics.
3110 * d_type Optimisation:: Take advantage of file type information.
3111 * fts:: A non-recursive file system search.
3114 @node Leaf Optimisation
3115 @section Leaf Optimisation
3117 Files in Unix file systems have a link count which indicates how many
3118 names point to the same inode. Directories in Unix filssytems have a
3119 @file{..} entry which functions as a hard link to the parent directory
3120 and a @file{.} entry which functions as a link to the directory itself.
3121 The @file{..} entry of the root directory also points to the root.
3122 This means that @code{find} can deduce the number of subdirectories a
3123 directory has, simply by subtracting 2 from the directory's link
3124 count. This allows @file{find} the calls to @code{stat} which would
3125 otherwise be needed to discover which directory entries are
3128 File systems which don't have these semantics should simply return a
3129 value less than 2 in the @code{st_nlinks} member of @code{struct stat}
3130 in response to a successful call to @code{stat}.
3132 If you are building @code{find} for a system on which the value of
3133 @code{st_nlinks} is unreliable, you can specify
3134 @code{--disable-leaf-optimisation} to @code{configure} to prevent this
3135 assumption being made.
3137 @node d_type Optimisation
3138 @section d_type Optimisation
3140 When this feature is enabled, @code{find} takes advantage of the fact
3141 that on some systems @code{readdir} will return the type of a file in
3142 @code{struct dirent}.
3147 The findutils source distribution contains two different implementations of
3148 @code{find}. The older implementation descends the file system
3149 recursively, while the newer one uses @code{fts}. Both are normally
3152 If the option @code{--without-fts} was passed to @code{configure}, the
3153 recursive implementation is installed as @code{find} and the fts-based
3154 implementation is installed as @code{ftsfind}. Otherwise, the
3155 fts-based implementation is installed as @code{find} and the recursive
3156 implementation is installed as @code{oldfind}.
3163 Below are summaries of the command line syntax for the programs
3164 discussed in this manual.
3169 * Invoking updatedb::
3171 * Regular Expressions::
3172 * Environment Variables::
3176 @section Invoking @code{find}
3179 find @r{[-H] [-L] [-P] [-D @var{debugoptions}] [-O@var{level}]} @r{[}@var{file}@dots{}@r{]} @r{[}@var{expression}@r{]}
3182 @code{find} searches the directory tree rooted at each file name
3183 @var{file} by evaluating the @var{expression} on each file it finds in
3186 The command line may begin with the @samp{-H}, @samp{-L}, @samp{-P},
3187 @samp{-D} and @samp{-O} options. These are followed by a list of
3188 files or directories that should be searched. If no files to search
3189 are specified, the current directory (@file{.}) is used.
3191 This list of files to search is followed by a list of expressions
3192 describing the files we wish to search for. The first part of the
3193 expression is recognised by the fact that it begins with @samp{-}
3194 followed by some other letters (for example @samp{-print}), or is
3195 either @samp{(} or @samp{!}. Any arguments after it are the rest of
3198 If no expression is given, the expression @samp{-print} is used.
3200 The @code{find} command exits with status zero if all files matched
3201 are processed successfully, greater than zero if errors occur.
3203 The @code{find} program also recognises two options for administrative
3208 Print a summary of the command line usage and exit.
3210 Print the version number of @code{find} and exit.
3213 The @samp{-version} option is a synonym for @samp{--version}
3217 * Filesystem Traversal Options::
3218 * Warning Messages::
3219 * Optimisation Options::
3221 * Find Expressions::
3224 @node Filesystem Traversal Options
3225 @subsection Filesystem Traversal Options
3227 The options @samp{-H}, @samp{-L} or @samp{-P} may be specified at the
3228 start of the command line (if none of these is specified, @samp{-P} is
3229 assumed). If you specify more than one of these options, the last one
3230 specified takes effect (but note that the @samp{-follow} option is
3231 equivalent to @samp{-L}).
3235 Never follow symbolic links (this is the default), except in the case
3236 of the @samp{-xtype} predicate.
3238 Always follow symbolic links, except in the case of the @samp{-xtype}
3241 Follow symbolic links specified in the list of files to search, or
3242 which are otherwise specified on the command line.
3245 If @code{find} would follow a symbolic link, but cannot for any reason
3246 (for example, because it has insufficient permissions or the link is
3247 broken), it falls back on using the properties of the symbolic link
3248 itself. @ref{Symbolic Links} for a more complete description of how
3249 symbolic links are handled.
3251 @node Warning Messages
3252 @subsection Warning Messages
3254 If there is an error on the @code{find} command line, an error message
3255 is normally issued. However, there are some usages that are
3256 inadvisable but which @code{find} should still accept. Under these
3257 circumstances, @code{find} may issue a warning message.
3259 By default, warnings are enabled only if @code{find} is being run
3260 interactively (specifically, if the standard input is a terminal) and
3261 the @code{POSIXLY_CORRECT} environment variable is not set. Warning
3262 messages can be controlled explicitly by the use of options on the
3267 Issue warning messages where appropriate.
3269 Do not issue warning messages.
3272 These options take effect at the point on the command line where they
3273 are specified. Therefore it's not useful to specify @samp{-nowarn} at
3274 the end of the command line. The warning messages affected by the
3275 above options are triggered by:
3279 Use of the @samp{-d} option which is deprecated; please use
3280 @samp{-depth} instead, since the latter is POSIX-compliant.
3282 Use of the @samp{-ipath} option which is deprecated; please use
3283 @samp{-iwholename} instead.
3285 Specifying an option (for example @samp{-mindepth}) after a non-option
3286 (for example @samp{-type} or @samp{-print}) on the command line.
3288 Use of the @samp{-name} or @samp{-iname} option with a slash character
3289 in the pattern. Since the name predicates only compare against the
3290 basename of the visited files, the only file that can match a slash is
3291 the root directory itself.
3294 The default behaviour above is designed to work in that way so that
3295 existing shell scripts don't generate spurious errors, but people will
3296 be made aware of the problem.
3298 Some warning messages are issued for less common or more serious
3299 problems, and consequently cannot be turned off:
3303 Use of an unrecognised backslash escape sequence with @samp{-fprintf}
3305 Use of an unrecognised formatting directive with @samp{-fprintf}
3308 @node Optimisation Options
3309 @subsection Optimisation Options
3311 The @samp{-O@var{level}} option sets @code{find}'s optimisation level
3312 to @var{level}. The default optimisation level is 1.
3314 At certain optimisation levels, @code{find} reorders tests to speed up
3315 execution while preserving the overall effect; that is, predicates
3316 with side effects are not reordered relative to each other. The
3317 optimisations performed at each optimisation level are as follows.
3321 Currently equivalent to optimisation level 1.
3324 This is the default optimisation level and corresponds to the
3325 traditional behaviour. Expressions are reordered so that tests based
3326 only on the names of files (for example@samp{ -name} and
3327 @samp{-regex}) are performed first.
3330 Any @samp{-type} or @samp{-xtype} tests are performed after any tests
3331 based only on the names of files, but before any tests that require
3332 information from the inode. On many modern versions of Unix, file
3333 types are returned by @code{readdir()} and so these predicates are
3334 faster to evaluate than predicates which need to stat the file first.
3336 If you use the @samp{-fstype FOO} predicate and specify a filsystem
3337 type @samp{FOO} which is not known (that is, present in
3338 @file{/etc/mtab}) at the time @code{find} starts, that predicate is
3339 equivalent to @samp{-false}.
3343 At this optimisation level, the full cost-based query optimiser is
3344 enabled. The order of tests is modified so that cheap (i.e., fast)
3345 tests are performed first and more expensive ones are performed later,
3346 if necessary. Within each cost band, predicates are evaluated earlier
3347 or later according to whether they are likely to succeed or not. For
3348 @samp{-o}, predicates which are likely to succeed are evaluated
3349 earlier, and for @samp{-a}, predicates which are likely to fail are
3355 @subsection Debug Options
3357 The @samp{-D} option makes @code{find} produce diagnostic output.
3358 Much of the information is useful only for diagnosing problems, and so
3359 most people will not find this option helpful.
3361 The list of debug options should be comma separated. Compatibility of
3362 the debug options is not guaranteed between releases of findutils.
3363 For a complete list of valid debug options, see the output of
3364 @code{find -D help}. Valid debug options include:
3367 Explain the debugging options.
3369 Show the expression tree in its original and optimised form.
3371 Print messages as files are examined with the stat and lstat system
3372 calls. The find program tries to minimise such calls.
3374 Prints diagnostic information relating to the optimisation of the
3375 expression tree; see the @samp{-O} option.
3377 Prints a summary indicating how often each predicate succeeded or
3381 @node Find Expressions
3382 @subsection Find Expressions
3384 The final part of the @code{find} command line is a list of
3385 expressions. @xref{Primary Index}, for a summary of all of the tests,
3386 actions, and options that the expression can contain. If the
3387 expression is missing, @samp{-print} is assumed.
3389 @node Invoking locate
3390 @section Invoking @code{locate}
3393 locate @r{[}@var{option}@dots{}@r{]} @var{pattern}@dots{}
3396 For each @var{pattern} given @code{locate} searches one or more file
3397 name databases returning each match of @var{pattern}.
3399 For each @var{pattern} given @code{locate} searches one or more file
3400 name databases returning each match of @var{pattern}.
3405 Print only names which match all non-option arguments, not those
3406 matching one or more non-option arguments.
3410 The specified pattern is matched against just the last component of
3411 the name of a file in the @code{locate} database. This last
3412 component is also called the ``base name''. For example, the base
3413 name of @file{/tmp/mystuff/foo.old.c} is @file{foo.old.c}. If the
3414 pattern contains metacharacters, it must match the base name exactly.
3415 If not, it must match part of the base name.
3419 Instead of printing the matched file names, just print the total
3420 number of matches found, unless @samp{--print} (@samp{-p}) is also
3424 @item --database=@var{path}
3425 @itemx -d @var{path}
3426 Instead of searching the default @code{locate} database
3427 @file{@value{LOCATE_DB}}, @code{locate} searches the file
3428 name databases in @var{path}, which is a colon-separated list of
3429 database file names. You can also use the environment variable
3430 @code{LOCATE_PATH} to set the list of database files to search. The
3431 option overrides the environment variable if both are used. Empty
3432 elements in @var{path} (that is, a leading or trailing colon, or two
3433 colons in a row) are taken to stand for the default database.
3434 A database can be supplied on stdin, using @samp{-} as an element
3435 of @samp{path}. If more than one element of @samp{path} is @samp{-},
3436 later instances are ignored (but a warning message is printed).
3440 Only print out such names which currently exist (instead of such names
3441 which existed when the database was created). Note that this may slow
3442 down the program a lot, if there are many matches in the database.
3443 The way in which broken symbolic links are treated is affected by the
3444 @samp{-L}, @samp{-P} and @samp{-H} options. Please note that it is
3445 possible for the file to be deleted after @code{locate} has checked
3446 that it exists, but before you use it. This option is automatically
3447 turned on when reading an @code{slocate} database in secure mode
3448 (@pxref{slocate Database Format}).
3450 @item --non-existing
3452 Only print out such names which currently do not exist (instead of
3453 such names which existed when the database was created). Note that
3454 this may slow down the program a lot, if there are many matches in the
3455 database. The way in which broken symbolic links are treated is
3456 affected by the @samp{-L}, @samp{-P} and @samp{-H} options. Please
3457 note that @code{locate} checks that the file does not exist, but a
3458 file of the same name might be created after @code{locate}'s check but
3459 before you read @code{locate}'s output.
3463 If testing for the existence of files (with the @samp{-e} or @samp{-E}
3464 options), consider broken symbolic links to be non-existing. This is
3465 the default behaviour.
3470 If testing for the existence of files (with the @samp{-e} or @samp{-E}
3471 options), treat broken symbolic links as if they were existing files.
3472 The @samp{-H} form of this option is provided purely for similarity
3473 with @code{find}; the use of @samp{-P} is recommended over @samp{-H}.
3477 Ignore case distinctions in both the pattern and the file names.
3481 Limit the number of results printed to N. When used with the
3482 @samp{--count} option, the value printed will never be larger than
3484 @item --max-database-age=D
3485 Normally, @code{locate} will issue a warning message when it searches
3486 a database which is more than 8 days old. This option changes that
3487 value to something other than 8. The effect of specifying a negative
3491 Accepted but does nothing. The option is supported only to provide
3492 compatibility with BSD's @code{locate}.
3496 Results are separated with the ASCII NUL character rather than the
3497 newline character. To get the full benefit of this option,
3498 use the new @code{locate} database format (that is the default
3503 Print search results when they normally would not be due to
3504 use of @samp{--statistics} (@samp{-S}) or @samp{--count}
3509 The specified pattern is matched against the whole name of the file in
3510 the @code{locate} database. If the pattern contains metacharacters,
3511 it must match exactly. If not, it must match part of the whole file
3512 name. This is the default behaviour.
3516 Instead of using substring or shell glob matching, the pattern
3517 specified on the command line is understood to be a regular
3518 expression. GNU Emacs-style regular expressions are assumed unless
3519 the @samp{--regextype} option is also given. File names from the
3520 @code{locate} database are matched using the specified regular
3521 expression. If the @samp{-i} flag is also given, matching is
3522 case-insensitive. Matches are performed against the whole path name,
3523 and so by default a pathname will be matched if any part of it matches
3524 the specified regular expression. The regular expression may use
3525 @samp{^} or @samp{$} to anchor a match at the beginning or end of a
3529 This option changes the regular expression syntax and behaviour used
3530 by the @samp{--regex} option. @ref{Regular Expressions} for more
3531 information on the regular expression dialects understood by GNU
3536 Accepted but does nothing. The option is supported only to provide
3537 compatibility with BSD's @code{locate}.
3541 Print some summary information for each @code{locate} database. No
3542 search is performed unless non-option arguments are given.
3543 Although the BSD version of locate also has this option, the format of the
3544 output is different.
3547 Print a summary of the command line usage for @code{locate} and exit.
3550 Print the version number of @code{locate} and exit.
3553 @node Invoking updatedb
3554 @section Invoking @code{updatedb}
3557 updatedb @r{[}@var{option}@dots{}@r{]}
3560 @code{updatedb} creates and updates the database of file names used by
3561 @code{locate}. @code{updatedb} generates a list of files similar to
3562 the output of @code{find} and then uses utilities for optimizing the
3563 database for performance. @code{updatedb} is often run periodically
3564 as a @code{cron} job and configured with environment variables or
3565 command options. Typically, operating systems have a shell script
3566 that ``exports'' configurations for variable definitions and uses
3567 another shell script that ``sources'' the configuration file into the
3568 environment and then executes @code{updatedb} in the environment.
3571 @item --findoptions='@var{OPTION}@dots{}'
3572 Global options to pass on to @code{find}.
3573 The environment variable @code{FINDOPTIONS} also sets this value.
3576 @item --localpaths='@var{path}@dots{}'
3577 Non-network directories to put in the database.
3578 Default is @file{/}.
3580 @item --netpaths='@var{path}@dots{}'
3581 Network (NFS, AFS, RFS, etc.) directories to put in the database.
3582 The environment variable @code{NETPATHS} also sets this value.
3585 @item --prunepaths='@var{path}@dots{}'
3586 Directories to omit from the database, which would otherwise be
3587 included. The environment variable @code{PRUNEPATHS} also sets this
3588 value. Default is @file{/tmp /usr/tmp /var/tmp /afs}. The paths are
3589 used as regular expressions (with @code{find ... -regex}, so you need
3590 to specify these paths in the same way that @code{find} will encounter
3591 them. This means for example that the paths must not include trailing
3594 @item --prunefs='@var{path}@dots{}'
3595 Filesystems to omit from the database, which would otherwise be
3596 included. Note that files are pruned when a filesystem is reached;
3597 Any filesystem mounted under an undesired filesystem will be ignored.
3598 The environment variable @code{PRUNEFS} also sets this value. Default
3599 is @file{nfs NFS proc}.
3601 @item --output=@var{dbfile}
3602 The database file to build. The default is system-dependent, but
3603 when this document was formatted it was @file{@value{LOCATE_DB}}.
3605 @item --localuser=@var{user}
3606 The user to search the non-network directories as, using @code{su}.
3607 Default is to search the non-network directories as the current user.
3608 You can also use the environment variable @code{LOCALUSER} to set this user.
3610 @item --netuser=@var{user}
3611 The user to search network directories as, using @code{su}. Default
3612 @code{user} is @code{daemon}. You can also use the environment variable
3613 @code{NETUSER} to set this user.
3616 Generate a @code{locate} database in the old format, for compatibility
3617 with versions of @code{locate} other than GNU @code{locate}. Using
3618 this option means that @code{locate} will not be able to properly
3619 handle non-ASCII characters in file names (that is, file names
3620 containing characters which have the eighth bit set, such as many of
3621 the characters from the ISO-8859-1 character set). @xref{Database
3622 Formats}, for a detailed description of the supported database
3625 @item --dbformat=@var{FORMAT}
3626 Generate the locate database in format @code{FORMAT}. Supported
3627 database formats include @code{LOCATE02} (which is the default),
3628 @code{old} and @code{slocate}. The @code{old} format exists for
3629 compatibility with implementations of @code{locate} on other Unix
3630 systems. The @code{slocate} format exists for compatibility with
3631 @code{slocate}. @xref{Database Formats}, for a detailed description
3635 Print a summary of the command line usage and exit.
3637 Print the version number of @code{updatedb} and exit.
3640 @node Invoking xargs
3641 @section Invoking @code{xargs}
3644 xargs @r{[}@var{option}@dots{}@r{]} @r{[}@var{command} @r{[}@var{initial-arguments}@r{]}@r{]}
3647 @code{xargs} exits with the following status:
3653 if any invocation of the command exited with status 1-125
3655 if the command exited with status 255
3657 if the command is killed by a signal
3659 if the command cannot be run
3661 if the command is not found
3663 if some other error occurred.
3666 Exit codes greater than 128 are used by the shell to indicate that
3667 a program died due to a fatal signal.
3672 * Invoking the shell from xargs::
3676 @subsection xargs options
3679 @item --arg-file@r{=@var{inputfile}}
3680 @itemx -a @r{@var{inputfile}}
3681 Read names from the file @var{inputfile} instead of standard input.
3682 If you use this option, the standard input stream remains unchanged
3683 when commands are run. Otherwise, stdin is redirected from
3688 Input file names are terminated by a null character instead of by
3689 whitespace, and any quotes and backslash characters are not considered
3690 special (every character is taken literally). Disables the end of
3691 file string, which is treated like any other argument.
3693 @item --delimiter @var{delim}
3694 @itemx -d @var{delim}
3696 Input file names are terminated by the specified character @var{delim}
3697 instead of by whitespace, and any quotes and backslash characters are
3698 not considered special (every character is taken literally). Disables
3699 the logical end of file marker string, which is treated like any other
3702 The specified delimiter may be a single character, a C-style character
3703 escape such as @samp{\n}, or an octal or hexadecimal escape code.
3704 Octal and hexadecimal escape codes are understood as for the
3705 @code{printf} command. Multibyte characters are not supported.
3707 @item -E @var{eof-str}
3708 @itemx --eof@r{[}=@var{eof-str}@r{]}
3709 @itemx -e@r{[}@var{eof-str}@r{]}
3711 Set the logical end of file marker string to @var{eof-str}. If the
3712 logical end of file marker string occurs as a line of input, the rest of
3713 the input is ignored. If @var{eof-str} is omitted (@samp{-e}) or blank
3714 (either @samp{-e} or @samp{-E}), there is no logical end of file marker
3715 string. The @samp{-e} form of this option is deprecated in favour of
3716 the POSIX-compliant @samp{-E} option, which you should use instead. As
3717 of GNU @code{xargs} version 4.2.9, the default behaviour of @code{xargs}
3718 is not to have a logical end of file marker string. The POSIX standard
3719 (IEEE Std 1003.1, 2004 Edition) allows this.
3721 The logical end of file marker string is not treated specially if the
3722 @samp{-d} or the @samp{-0} options are in effect. That is, when either
3723 of these options are in effect, the whole input file will be read even
3724 if @samp{-E} was used.
3727 Print a summary of the options to @code{xargs} and exit.
3729 @item -I @var{replace-str}
3730 @itemx --replace@r{[}=@var{replace-str}@r{]}
3731 @itemx -i@r{[}@var{replace-str}@r{]}
3732 Replace occurrences of @var{replace-str} in the initial arguments with
3733 names read from standard input. Also, unquoted blanks do not
3734 terminate arguments; instead, the input is split at newlines only. If
3735 @var{replace-str} is omitted (omitting it is allowed only for
3736 @samp{-i}), it defaults to @samp{@{@}} (like for @samp{find -exec}).
3737 Implies @samp{-x} and @samp{-l 1}. The @samp{-i} option is deprecated
3738 in favour of the @samp{-I} option.
3740 @item -L @var{max-lines}
3741 @itemx --max-lines@r{[}=@var{max-lines}@r{]}
3742 @itemx -l@r{[}@var{max-lines}@r{]}
3743 Use at most @var{max-lines} non-blank input lines per command line.
3744 For @samp{-l}, @var{max-lines} defaults to 1 if omitted. For
3745 @samp{-L}, the argument is mandatory. Trailing blanks cause an input
3746 line to be logically continued on the next input line, for the purpose
3747 of counting the lines. Implies @samp{-x}. The @samp{-l} form of this
3748 option is deprecated in favour of the POSIX-compliant @samp{-L}
3751 @item --max-args=@var{max-args}
3752 @itemx -n @var{max-args}
3753 Use at most @var{max-args} arguments per command line. Fewer than
3754 @var{max-args} arguments will be used if the size (see the @samp{-s}
3755 option) is exceeded, unless the @samp{-x} option is given, in which
3756 case @code{xargs} will exit.
3760 Prompt the user about whether to run each command line and read a line
3761 from the terminal. Only run the command line if the response starts
3762 with @samp{y} or @samp{Y}. Implies @samp{-t}.
3764 @item --no-run-if-empty
3766 If the standard input is completely empty, do not run the
3767 command. By default, the command is run once even if there is no
3770 @item --max-chars=@var{max-chars}
3771 @itemx -s @var{max-chars}
3772 Use at most @var{max-chars} characters per command line, including the
3773 command, initial arguments and any terminating nulls at the ends of
3774 the argument strings.
3777 Display the limits on the command-line length which are imposed by the
3778 operating system, @code{xargs}' choice of buffer size and the
3779 @samp{-s} option. Pipe the input from @file{/dev/null} (and perhaps
3780 specify @samp{--no-run-if-empty}) if you don't want @code{xargs} to do
3785 Print the command line on the standard error output before executing
3789 Print the version number of @code{xargs} and exit.
3793 Exit if the size (see the @samp{-s} option) is exceeded.
3796 @item --max-procs=@var{max-procs}
3797 @itemx -P @var{max-procs}
3798 Run simultaneously up to @var{max-procs} processes at once; the default is 1. If
3799 @var{max-procs} is 0, @code{xargs} will run as many processes as
3800 possible simultaneously.
3802 @item --process-slot-var=@var{environment-variable-name}
3803 Set the environment variable @var{environment-variable-name} to a
3804 unique value in each running child process. Each value is a decimal
3805 integer. Values are reused once child processes exit. This can be
3806 used in a rudimentary load distribution scheme, for example.
3809 @node Invoking the shell from xargs
3810 @subsection Invoking the shell from xargs
3812 Normally, @code{xargs} will exec the command you specified directly,
3813 without invoking a shell. This is normally the behaviour one would
3814 want. It's somewhat more efficient and avoids problems with shell
3815 metacharacters, for example. However, sometimes it is necessary to
3816 manipulate the environment of a command before it is run, in a way
3817 that @code{xargs} does not directly support.
3819 Invoking a shell from @code{xargs} is a good way of performing such
3820 manipulations. However, some care must be taken to prevent problems,
3821 for example unwanted interpretation of shell metacharacters.
3823 This command moves a set of files into an archive directory:
3826 find /foo -maxdepth 1 -atime +366 -exec mv @{@} /archive \;
3829 However, this will only move one file at a time. We cannot in this
3830 case use @code{-exec ... +} because the matched file names are added
3831 at the end of the command line, while the destination directory would
3832 need to be specified last. We also can't use @code{xargs} in the
3833 obvious way for the same reason. One way of working around this
3834 problem is to make use of the special properties of GNU @code{mv}; it
3835 has a @code{-t} option that allows the target directory to be
3836 specified before the list of files to be moved. However, while this
3837 technique works for GNU @code{mv}, it doesn't solve the more general
3840 Here is a more general technique for solving this problem:
3843 find /foo -maxdepth 1 -atime +366 -print0 |
3844 xargs -r0 sh -c 'mv "$@@" /archive' move
3847 Here, a shell is being invoked. There are two shell instances to think
3848 about. The first is the shell which launches the @code{xargs} command
3849 (this might be the shell into which you are typing, for example). The
3850 second is the shell launched by @code{xargs} (in fact it will probably
3851 launch several, one after the other, depending on how many files need to
3852 be archived). We'll refer to this second shell as a subshell.
3854 Our example uses the @code{-c} option of @code{sh}. Its argument is a
3855 shell command to be executed by the subshell. Along with the rest of
3856 that command, the $@@ is enclosed by single quotes to make sure it is
3857 passed to the subshell without being expanded by the parent shell. It
3858 is also enclosed with double quotes so that the subshell will expand
3859 @code{$@@} correctly even if one of the file names contains a space or
3862 The subshell will use any non-option arguments as positional
3863 parameters (that is, in the expansion of @code{$@@}). Because
3864 @code{xargs} launches the @code{sh -c} subshell with a list of files,
3865 those files will end up as the expansion of @code{$@@}.
3867 You may also notice the @samp{move} at the end of the command line.
3868 This is used as the value of @code{$0} by the subshell. We include it
3869 because otherwise the name of the first file to be moved would be used
3870 instead. If that happened it would not be included in the subshell's
3871 expansion of @code{$@@}, and so it wouldn't actually get moved.
3874 Another reason to use the @code{sh -c} construct could be to
3875 perform redirection:
3878 find /usr/include -name '*.h' | xargs grep -wl mode_t |
3879 xargs -r sh -c 'exec emacs "$@@" < /dev/tty' Emacs
3882 Notice that we use the shell builtin @code{exec} here. That's simply
3883 because the subshell needs to do nothing once Emacs has been invoked.
3884 Therefore instead of keeping a @code{sh} process around for no reason,
3885 we just arrange for the subshell to exec Emacs, saving an extra
3888 Sometimes, though, it can be helpful to keep the shell process around:
3891 find /foo -maxdepth 1 -atime +366 -print0 |
3892 xargs -r0 sh -c 'mv "$@@" /archive || exit 255' move
3895 Here, the shell will exit with status 255 if any @code{mv} failed.
3896 This causes @code{xargs} to stop immediately.
3899 @node Regular Expressions
3900 @section Regular Expressions
3902 The @samp{-regex} and @samp{-iregex} tests of @code{find} allow
3903 matching by regular expression, as does the @samp{--regex} option of
3906 Your locale configuration affects how regular expressions are
3907 interpreted. @xref{Environment Variables}, for a description of how
3908 your locale setup affects the interpretation of regular expressions.
3910 There are also several different types of regular expression, and
3911 these are interpreted differently. Normally, the type of regular
3912 expression used by @code{find} and @code{locate} is the same as is
3913 used in GNU Emacs. Both programs provide an option which allows you
3914 to select an alternative regular expression syntax; for @code{find}
3915 this is the @samp{-regextype} option, and for @code{locate} this is
3916 the @samp{--regextype} option.
3918 These options take a single argument, which indicates the specific
3919 regular expression syntax and behaviour that should be used. This
3920 should be one of the following:
3922 @include regexprops.texi
3924 @node Environment Variables
3925 @section Environment Variables
3926 @c TODO: check the variable index still contains references to these
3929 Provides a default value for the internationalisation variables that
3933 If set to a non-empty string value, override the values of all the
3934 other internationalisation variables.
3937 The POSIX standard specifies that this variable affects the pattern
3938 matching to be used for the `\-name' option. GNU find uses the
3939 GNU version of the @code{fnmatch} library function.
3941 This variable also affects the interpretation of the response to
3942 @code{-ok}; while the @code{LC_MESSAGES} variable selects the actual
3943 pattern used to interpret the response to @code{-ok}, the interpretation
3944 of any bracket expressions in the pattern will be affected by the
3945 @code{LC_COLLATE} variable.
3948 This variable affects the treatment of character classes used in
3949 regular expression and with
3950 the @samp{-name} test, if the @code{fnmatch} function supports this.
3952 This variable also affects the interpretation of any character classes
3953 in the regular expressions used to interpret the response to the
3954 prompt issued by @code{-ok}. The @code{LC_CTYPE} environment variable will
3955 also affect which characters are considered to be unprintable when
3956 filenames are printed (@pxref{Unusual Characters in File Names}).
3959 Determines the locale to be used for internationalised messages,
3960 including the interpretation of the response to the prompt made by the
3964 Determines the location of the internationalisation message catalogues.
3967 Affects the directories which are searched to find the executables
3968 invoked by @samp{-exec}, @samp{-execdir} @samp{-ok} and @samp{-okdir}.
3969 If the @var{PATH} environment variable includes the current directory
3970 (by explicitly including @samp{.} or by having an empty element), and
3971 the find command line includes @samp{-execdir} or @samp{-okdir},
3972 @code{find} will refuse to run. @xref{Security Considerations}, for a
3973 more detailed discussion of security matters.
3975 @item POSIXLY_CORRECT
3976 Determines the block size used by @samp{-ls} and @samp{-fls}. If
3977 @code{POSIXLY_CORRECT} is set, blocks are units of 512 bytes. Otherwise
3978 they are units of 1024 bytes.
3980 Setting this variable also turns off warning messages (that is, implies
3981 @samp{-nowarn}) by default, because POSIX requires that apart from
3982 the output for @samp{-ok}, all messages printed on stderr are
3983 diagnostics and must result in a non-zero exit status.
3985 When @code{POSIXLY_CORRECT} is set, the response to the prompt made by the
3986 @code{-ok} action is interpreted according to the system's message
3987 catalogue, as opposed to according to @code{find}'s own message
3991 Affects the time zone used for some of the time-related format
3992 directives of @samp{-printf} and @samp{-fprintf}.
3998 @chapter Common Tasks
4000 The sections that follow contain some extended examples that both give
4001 a good idea of the power of these programs, and show you how to solve
4002 common real-world problems.
4005 * Viewing And Editing::
4008 * Strange File Names::
4009 * Fixing Permissions::
4010 * Classifying Files::
4013 @node Viewing And Editing
4014 @section Viewing And Editing
4016 To view a list of files that meet certain criteria, simply run your
4017 file viewing program with the file names as arguments. Shells
4018 substitute a command enclosed in backquotes with its output, so the
4019 whole command looks like this:
4022 less `find /usr/include -name '*.h' | xargs grep -l mode_t`
4026 You can edit those files by giving an editor name instead of a file
4030 emacs `find /usr/include -name '*.h' | xargs grep -l mode_t`
4033 Because there is a limit to the length of any individual command line,
4034 there is a limit to the number of files that can be handled in this way.
4035 We can get around this difficulty by using @code{xargs} like this:
4038 find /usr/include -name '*.h' | xargs grep -l mode_t > todo
4039 xargs --arg-file=todo emacs
4042 Here, @code{xargs} will run @code{emacs} as many times as necessary to
4043 visit all of the files listed in the file @file{todo}. Generating a
4044 temporary file is not always convenient, though. This command does
4045 much the same thing without needing one:
4048 find /usr/include -name '*.h' | xargs grep -l mode_t |
4049 xargs sh -c 'emacs "$@@" < /dev/tty' Emacs
4052 The example above illustrates a useful trick; Using @code{sh -c} you
4053 can invoke a shell command from @code{xargs}. The @code{$@@} in the
4054 command line is expanded by the shell to a list of arguments as
4055 provided by @code{xargs}. The single quotes in the command line
4056 protect the @code{$@@} against expansion by your interactive shell
4057 (which will normally have no arguments and thus expand @code{$@@} to
4058 nothing). The capitalised @samp{Emacs} on the command line is used as
4059 @code{$0} by the shell that @code{xargs} launches.
4064 You can pass a list of files produced by @code{find} to a file
4065 archiving program. GNU @code{tar} and @code{cpio} can both read lists
4066 of file names from the standard input -- either delimited by nulls (the
4067 safe way) or by blanks (the lazy, risky default way). To use
4068 null-delimited names, give them the @samp{--null} option. You can
4069 store a file archive in a file, write it on a tape, or send it over a
4070 network to extract on another machine.
4072 One common use of @code{find} to archive files is to send a list of
4073 the files in a directory tree to @code{cpio}. Use @samp{-depth} so if
4074 a directory does not have write permission for its owner, its contents
4075 can still be restored from the archive since the directory's
4076 permissions are restored after its contents. Here is an example of
4077 doing this using @code{cpio}; you could use a more complex @code{find}
4078 expression to archive only certain files.
4081 find . -depth -print0 |
4082 cpio --create --null --format=crc --file=/dev/nrst0
4085 You could restore that archive using this command:
4088 cpio --extract --null --make-dir --unconditional \
4089 --preserve --file=/dev/nrst0
4092 Here are the commands to do the same things using @code{tar}:
4095 find . -depth -print0 |
4096 tar --create --null --files-from=- --file=/dev/nrst0
4098 tar --extract --null --preserve-perm --same-owner \
4102 @c Idea from Rick Sladkey.
4103 Here is an example of copying a directory from one machine to another:
4106 find . -depth -print0 | cpio -0o -Hnewc |
4107 rsh @var{other-machine} "cd `pwd` && cpio -i0dum"
4111 @section Cleaning Up
4113 @c Idea from Jim Meyering.
4114 This section gives examples of removing unwanted files in various
4115 situations. Here is a command to remove the CVS backup files created
4116 when an update requires a merge:
4119 find . -name '.#*' -print0 | xargs -0r rm -f
4122 If your @code{find} command removes directories, you may find that
4123 you get a spurious error message when @code{find} tries to recurse
4124 into a directory that has now been removed. Using the @samp{-depth}
4125 option will normally resolve this problem.
4127 @c What does the following sentence mean? Why is -delete safer? --kasal
4128 @c The command above works, but the following is safer:
4130 It is also possible to use the @samp{-delete} action:
4133 find . -depth -name '.#*' -delete
4136 @c Idea from Franc,ois Pinard.
4137 You can run this command to clean out your clutter in @file{/tmp}.
4138 You might place it in the file your shell runs when you log out
4139 (@file{.bash_logout}, @file{.logout}, or @file{.zlogout}, depending on
4140 which shell you use).
4143 find /tmp -depth -user "$LOGNAME" -type f -delete
4146 @c Idea from Noah Friedman.
4147 To remove old Emacs backup and auto-save files, you can use a command
4148 like the following. It is especially important in this case to use
4149 null-terminated file names because Emacs packages like the VM mailer
4150 often create temporary file names with spaces in them, like
4151 @file{#reply to David J. MacKenzie<1>#}.
4154 find ~ \( -name '*~' -o -name '#*#' \) -print0 |
4155 xargs --no-run-if-empty --null rm -vf
4158 Removing old files from @file{/tmp} is commonly done from @code{cron}:
4160 @c Idea from Kaveh Ghazi.
4162 find /tmp /var/tmp -depth -not -type d -mtime +3 -delete
4163 find /tmp /var/tmp -depth -mindepth 1 -type d -empty -delete
4166 The second @code{find} command above cleans out empty directories
4167 depth-first (@samp{-delete} implies @samp{-depth} anyway), hoping that
4168 the parents become empty and can be removed too. It uses
4169 @samp{-mindepth} to avoid removing @file{/tmp} itself if it becomes
4173 Lastly, an example of a program that almost certainly does not do what
4176 @c inspired by Savannah bug #20865 (Bruno De Fraine)
4178 find dirname -delete -name quux
4181 If the user hoped to delete only files named @file{quux} they will get
4182 an unpleasant surprise; this command will attempt to delete everything
4183 at or below the starting point @file{dirname}. This is because
4184 @code{find} evaluates the items on the command line as an expression.
4185 The @code{find} program will normally execute an action if the
4186 preceding action succeeds. Here, there is no action or test before
4187 the @samp{-delete} so it will always be executed. The @samp{-name
4188 quux} test will be performed for files we successfully deleted, but
4189 that test has no effect since @samp{-delete} also disables the default
4190 @samp{-print} operation. So the above example will probably delete a
4191 lot of files the user didn't want to delete.
4193 This command is also likely to do something you did not intend:
4195 find dirname -path dirname/foo -prune -o -delete
4198 Because @samp{-delete} turns on @samp{-depth}, the @samp{-prune}
4199 action has no effect and files in @file{dirname/foo} will be deleted
4203 @node Strange File Names
4204 @section Strange File Names
4207 @c From: tmatimar@isgtec.com (Ted Timar)
4208 @c Newsgroups: comp.unix.questions,comp.unix.shell,comp.answers,news.answers
4209 @c Subject: Unix - Frequently Asked Questions (2/7) [Frequent posting]
4210 @c Subject: How do I remove a file with funny characters in the filename ?
4211 @c Date: Thu Mar 18 17:16:55 EST 1993
4212 @code{find} can help you remove or rename a file with strange
4213 characters in its name. People are sometimes stymied by files whose
4214 names contain characters such as spaces, tabs, control characters, or
4215 characters with the high bit set. The simplest way to remove such
4219 rm -i @var{some*pattern*that*matches*the*problem*file}
4222 @code{rm} asks you whether to remove each file matching the given
4223 pattern. If you are using an old shell, this approach might not work
4224 if the file name contains a character with the high bit set; the shell
4225 may strip it off. A more reliable way is:
4228 find . -maxdepth 1 @var{tests} -okdir rm '@{@}' \;
4232 where @var{tests} uniquely identify the file. The @samp{-maxdepth 1}
4233 option prevents @code{find} from wasting time searching for the file
4234 in any subdirectories; if there are no subdirectories, you may omit
4235 it. A good way to uniquely identify the problem file is to figure out
4236 its inode number; use
4242 Suppose you have a file whose name contains control characters, and
4243 you have found that its inode number is 12345. This command prompts
4244 you for whether to remove it:
4247 find . -maxdepth 1 -inum 12345 -okdir rm -f '@{@}' \;
4250 If you don't want to be asked, perhaps because the file name may
4251 contain a strange character sequence that will mess up your screen
4252 when printed, then use @samp{-execdir} instead of @samp{-okdir}.
4254 If you want to rename the file instead, you can use @code{mv} instead
4258 find . -maxdepth 1 -inum 12345 -okdir mv '@{@}' @var{new-file-name} \;
4261 @node Fixing Permissions
4262 @section Fixing Permissions
4264 Suppose you want to make sure that everyone can write to the
4265 directories in a certain directory tree. Here is a way to find
4266 directories lacking either user or group write permission (or both),
4267 and fix their permissions:
4270 find . -type d -not -perm -ug=w | xargs chmod ug+w
4274 You could also reverse the operations, if you want to make sure that
4275 directories do @emph{not} have world write permission.
4277 @node Classifying Files
4278 @section Classifying Files
4281 @c From: martin@mwtech.UUCP (Martin Weitzel)
4282 @c Newsgroups: comp.unix.wizards,comp.unix.questions
4283 @c Subject: Advanced usage of 'find' (Re: Unix security automating script)
4284 @c Date: 22 Mar 90 15:05:19 GMT
4285 If you want to classify a set of files into several groups based on
4286 different criteria, you can use the comma operator to perform multiple
4287 independent tests on the files. Here is an example:
4290 find / -type d \( -perm -o=w -fprint allwrite , \
4291 -perm -o=x -fprint allexec \)
4293 echo "Directories that can be written to by everyone:"
4296 echo "Directories with search permissions for everyone:"
4300 @code{find} has only to make one scan through the directory tree
4301 (which is one of the most time consuming parts of its work).
4303 @node Worked Examples
4304 @chapter Worked Examples
4306 The tools in the findutils package, and in particular @code{find},
4307 have a large number of options. This means that quite often,
4308 there is more than one way to do things. Some of the options
4309 and facilities only exist for compatibility with other tools, and
4310 findutils provides improved ways of doing things.
4312 This chapter describes a number of useful tasks that are commonly
4313 performed, and compares the different ways of achieving them.
4317 * Copying A Subset of Files::
4318 * Updating A Timestamp File::
4319 * Finding the Shallowest Instance::
4322 @node Deleting Files
4323 @section Deleting Files
4325 One of the most common tasks that @code{find} is used for is locating
4326 files that can be deleted. This might include:
4330 Files last modified more than 3 years ago which haven't been accessed
4331 for at least 2 years
4333 Files belonging to a certain user
4335 Temporary files which are no longer required
4338 This example concentrates on the actual deletion task rather than on
4339 sophisticated ways of locating the files that need to be deleted.
4340 We'll assume that the files we want to delete are old files underneath
4341 @file{/var/tmp/stuff}.
4343 @subsection The Traditional Way
4345 The traditional way to delete files in @file{/var/tmp/stuff} that have
4346 not been modified in over 90 days would have been:
4349 find /var/tmp/stuff -mtime +90 -exec /bin/rm @{@} \;
4352 The above command uses @samp{-exec} to run the @code{/bin/rm} command
4353 to remove each file. This approach works and in fact would have
4354 worked in Version 7 Unix in 1979. However, there are a number of
4355 problems with this approach.
4358 The most obvious problem with the approach above is that it causes
4359 @code{find} to fork every time it finds a file that needs to delete,
4360 and the child process then has to use the @code{exec} system call to
4361 launch @code{/bin/rm}. All this is quite inefficient. If we are
4362 going to use @code{/bin/rm} to do this job, it is better to make it
4363 delete more than one file at a time.
4365 The most obvious way of doing this is to use the shell's command
4369 /bin/rm `find /var/tmp/stuff -mtime +90 -print`
4371 or you could use the more modern form
4373 /bin/rm $(find /var/tmp/stuff -mtime +90 -print)
4376 The commands above are much more efficient than the first attempt.
4377 However, there is a problem with them. The shell has a maximum
4378 command length which is imposed by the operating system (the actual
4379 limit varies between systems). This means that while the command
4380 expansion technique will usually work, it will suddenly fail when
4381 there are lots of files to delete. Since the task is to delete
4382 unwanted files, this is precisely the time we don't want things to go
4385 @subsection Making Use of @code{xargs}
4387 So, is there a way to be more efficient in the use of @code{fork()}
4388 and @code{exec()} without running up against this limit?
4389 Yes, we can be almost optimally efficient by making use
4390 of the @code{xargs} command. The @code{xargs} command reads arguments
4391 from its standard input and builds them into command lines. We can
4395 find /var/tmp/stuff -mtime +90 -print | xargs /bin/rm
4398 For example if the files found by @code{find} are
4399 @file{/var/tmp/stuff/A},
4400 @file{/var/tmp/stuff/B} and
4401 @file{/var/tmp/stuff/C} then @code{xargs} might issue the commands
4404 /bin/rm /var/tmp/stuff/A /var/tmp/stuff/B
4405 /bin/rm /var/tmp/stuff/C
4408 The above assumes that @code{xargs} has a very small maximum command
4409 line length. The real limit is much larger but the idea is that
4410 @code{xargs} will run @code{/bin/rm} as many times as necessary to get
4411 the job done, given the limits on command line length.
4413 This usage of @code{xargs} is pretty efficient, and the @code{xargs}
4414 command is widely implemented (all modern versions of Unix offer it).
4415 So far then, the news is all good. However, there is bad news too.
4417 @subsection Unusual characters in filenames
4419 Unix-like systems allow any characters to appear in file names with
4420 the exception of the ASCII NUL character and the slash.
4421 Slashes can occur in path names (as the directory separator) but
4422 not in the names of actual directory entries. This means that the
4423 list of files that @code{xargs} reads could in fact contain white space
4424 characters -- spaces, tabs and newline characters. Since by default,
4425 @code{xargs} assumes that the list of files it is reading uses white
4426 space as an argument separator, it cannot correctly handle the case
4427 where a filename actually includes white space. This makes the
4428 default behaviour of @code{xargs} almost useless for handling
4431 To solve this problem, GNU findutils introduced the @samp{-print0}
4432 action for @code{find}. This uses the ASCII NUL character to separate
4433 the entries in the file list that it produces. This is the ideal
4434 choice of separator since it is the only character that cannot appear
4435 within a path name. The @samp{-0} option to @code{xargs} makes it
4436 assume that arguments are separated with ASCII NUL instead of white
4437 space. It also turns off another misfeature in the default behaviour
4438 of @code{xargs}, which is that it pays attention to quote characters
4439 in its input. Some versions of @code{xargs} also terminate when they
4440 see a lone @samp{_} in the input, but GNU @code{find} no longer does
4441 that (since it has become an optional behaviour in the Unix standard).
4443 So, putting @code{find -print0} together with @code{xargs -0} we get
4447 find /var/tmp/stuff -mtime +90 -print0 | xargs -0 /bin/rm
4450 The result is an efficient way of proceeding that
4451 correctly handles all the possible characters that could appear in the
4452 list of files to delete. This is good news. However, there is, as
4453 I'm sure you're expecting, also more bad news. The problem is that
4454 this is not a portable construct; although other versions of Unix
4455 (notably BSD-derived ones) support @samp{-print0}, it's not
4456 universal. So, is there a more universal mechanism?
4458 @subsection Going back to @code{-exec}
4460 There is indeed a more universal mechanism, which is a slight
4461 modification to the @samp{-exec} action. The normal @samp{-exec}
4462 action assumes that the command to run is terminated with a semicolon
4463 (the semicolon normally has to be quoted in order to protect it from
4464 interpretation as the shell command separator). The SVR4 edition of
4465 Unix introduced a slight variation, which involves terminating the
4466 command with @samp{+} instead:
4469 find /var/tmp/stuff -mtime +90 -exec /bin/rm @{@} \+
4472 The above use of @samp{-exec} causes @code{find} to build up a long
4473 command line and then issue it. This can be less efficient than some
4474 uses of @code{xargs}; for example @code{xargs} allows new command
4475 lines to be built up while the previous command is still executing, and
4476 allows you to specify a number of commands to run in parallel.
4477 However, the @code{find @dots{} -exec @dots{} +} construct has the advantage
4478 of wide portability. GNU findutils did not support @samp{-exec @dots{} +}
4479 until version 4.2.12; one of the reasons for this is that it already
4480 had the @samp{-print0} action in any case.
4483 @subsection A more secure version of @code{-exec}
4485 The command above seems to be efficient and portable. However,
4486 within it lurks a security problem. The problem is shared with
4487 all the commands we've tried in this worked example so far, too. The
4488 security problem is a race condition; that is, if it is possible for
4489 somebody to manipulate the filesystem that you are searching while you
4490 are searching it, it is possible for them to persuade your @code{find}
4491 command to cause the deletion of a file that you can delete but they
4494 The problem occurs because the @samp{-exec} action is defined by the
4495 POSIX standard to invoke its command with the same working directory
4496 as @code{find} had when it was started. This means that the arguments
4497 which replace the @{@} include a relative path from @code{find}'s
4498 starting point down the file that needs to be deleted. For example,
4501 find /var/tmp/stuff -mtime +90 -exec /bin/rm @{@} \+
4504 might actually issue the command:
4507 /bin/rm /var/tmp/stuff/A /var/tmp/stuff/B /var/tmp/stuff/passwd
4510 Notice the file @file{/var/tmp/stuff/passwd}. Likewise, the command:
4513 cd /var/tmp && find stuff -mtime +90 -exec /bin/rm @{@} \+
4516 might actually issue the command:
4519 /bin/rm stuff/A stuff/B stuff/passwd
4522 If an attacker can rename @file{stuff} to something else (making use
4523 of their write permissions in @file{/var/tmp}) they can replace it
4524 with a symbolic link to @file{/etc}. That means that the
4525 @code{/bin/rm} command will be invoked on @file{/etc/passwd}. If you
4526 are running your @code{find} command as root, the attacker has just managed
4527 to delete a vital file. All they needed to do to achieve this was
4528 replace a subdirectory with a symbolic link at the vital moment.
4530 There is however, a simple solution to the problem. This is an action
4531 which works a lot like @code{-exec} but doesn't need to traverse a
4532 chain of directories to reach the file that it needs to work on. This
4533 is the @samp{-execdir} action, which was introduced by the BSD family
4534 of operating systems. The command,
4537 find /var/tmp/stuff -mtime +90 -execdir /bin/rm @{@} \+
4540 might delete a set of files by performing these actions:
4544 Change directory to /var/tmp/stuff/foo
4546 Invoke @code{/bin/rm ./file1 ./file2 ./file3}
4548 Change directory to /var/tmp/stuff/bar
4550 Invoke @code{/bin/rm ./file99 ./file100 ./file101}
4553 This is a much more secure method. We are no longer exposed to a race
4554 condition. For many typical uses of @code{find}, this is the best
4555 strategy. It's reasonably efficient, but the length of the command
4556 line is limited not just by the operating system limits, but also by
4557 how many files we actually need to delete from each directory.
4559 Is it possible to do any better? In the case of general file
4560 processing, no. However, in the specific case of deleting files it is
4561 indeed possible to do better.
4563 @subsection Using the @code{-delete} action
4565 The most efficient and secure method of solving this problem is to use
4566 the @samp{-delete} action:
4569 find /var/tmp/stuff -mtime +90 -delete
4572 This alternative is more efficient than any of the @samp{-exec} or
4573 @samp{-execdir} actions, since it entirely avoids the overhead of
4574 forking a new process and using @code{exec} to run @code{/bin/rm}. It
4575 is also normally more efficient than @code{xargs} for the same
4576 reason. The file deletion is performed from the directory containing
4577 the entry to be deleted, so the @samp{-delete} action has the same
4578 security advantages as the @samp{-execdir} action has.
4580 The @samp{-delete} action was introduced by the BSD family of
4583 @subsection Improving things still further
4585 Is it possible to improve things still further? Not without either
4586 modifying the system library to the operating system or having more specific
4587 knowledge of the layout of the filesystem and disk I/O subsystem, or
4590 The @code{find} command traverses the filesystem, reading
4591 directories. It then issues a separate system call for each file to
4592 be deleted. If we could modify the operating system, there are
4593 potential gains that could be made:
4597 We could have a system call to which we pass more than one filename
4600 Alternatively, we could pass in a list of inode numbers (on GNU/Linux
4601 systems, @code{readdir()} also returns the inode number of each
4602 directory entry) to be deleted.
4605 The above possibilities sound interesting, but from the kernel's point
4606 of view it is difficult to enforce standard Unix access controls for
4607 such processing by inode number. Such a facility would probably
4608 need to be restricted to the superuser.
4610 Another way of improving performance would be to increase the
4611 parallelism of the process. For example if the directory hierarchy we
4612 are searching is actually spread across a number of disks, we might
4613 somehow be able to arrange for @code{find} to process each disk in
4614 parallel. In practice GNU @code{find} doesn't have such an intimate
4615 understanding of the system's filesystem layout and disk I/O
4618 However, since the system administrator can have such an understanding
4619 they can take advantage of it like so:
4622 find /var/tmp/stuff1 -mtime +90 -delete &
4623 find /var/tmp/stuff2 -mtime +90 -delete &
4624 find /var/tmp/stuff3 -mtime +90 -delete &
4625 find /var/tmp/stuff4 -mtime +90 -delete &
4629 In the example above, four separate instances of @code{find} are used
4630 to search four subdirectories in parallel. The @code{wait} command
4631 simply waits for all of these to complete. Whether this approach is
4632 more or less efficient than a single instance of @code{find} depends
4633 on a number of things:
4637 Are the directories being searched in parallel actually on separate
4638 disks? If not, this parallel search might just result in a lot of
4639 disk head movement and so the speed might even be slower.
4641 Other activity - are other programs also doing things on those disks?
4645 @subsection Conclusion
4647 The fastest and most secure way to delete files with the help of
4648 @code{find} is to use @samp{-delete}. Using @code{xargs -0 -P N} can
4649 also make effective use of the disk, but it is not as secure.
4651 In the case where we're doing things other than deleting files, the
4652 most secure alternative is @samp{-execdir @dots{} +}, but this is not as
4653 portable as the insecure action @samp{-exec @dots{} +}.
4655 The @samp{-delete} action is not completely portable, but the only
4656 other possibility which is as secure (@samp{-execdir}) is no more
4657 portable. The most efficient portable alternative is @samp{-exec
4658 @dots{}+}, but this is insecure and isn't supported by versions of GNU
4659 findutils prior to 4.2.12.
4661 @node Copying A Subset of Files
4662 @section Copying A Subset of Files
4664 Suppose you want to copy some files from @file{/source-dir} to
4665 @file{/dest-dir}, but there are a small number of files in
4666 @file{/source-dir} you don't want to copy.
4668 One option of course is @code{cp /source-dir /dest-dir} followed by
4669 deletion of the unwanted material under @file{/dest-dir}. But often
4670 that can be inconvenient, because for example we would have copied a
4671 large amount of extraneous material, or because @file{/dest-dir} is
4672 too small. Naturally there are many other possible reasons why this
4673 strategy may be unsuitable.
4675 So we need to have some way of identifying which files we want to
4676 copy, and we need to have a way of copying that file list. The second
4677 part of this condition is met by @code{cpio -p}. Of course, we can
4678 identify the files we wish to copy by using @code{find}. Here is a
4679 command that solves our problem:
4683 find . -name '.snapshot' -prune -o \( \! -name '*~' -print0 \) |
4684 cpio -pmd0 /dest-dir
4687 The first part of the @code{find} command here identifies files or
4688 directories named @file{.snapshot} and tells @code{find} not to
4689 recurse into them (since they do not need to be copied). The
4690 combination @code{-name '.snapshot' -prune} yields false for anything
4691 that didn't get pruned, but it is exactly those files we want to
4692 copy. Therefore we need to use an OR (@samp{-o}) condition to
4693 introduce the rest of our expression. The remainder of the expression
4694 simply arranges for the name of any file not ending in @samp{~} to be
4697 Using @code{-print0} ensures that white space characters in file names
4698 do not pose a problem. The @code{cpio} command does the actual work
4699 of copying files. The program as a whole fails if the @code{cpio}
4700 program returns nonzero. If the @code{find} command returns non-zero
4701 on the other hand, the Unix shell will not diagnose a problem (since
4702 @code{find} is not the last command in the pipeline).
4705 @node Updating A Timestamp File
4706 @section Updating A Timestamp File
4708 Suppose we have a directory full of files which is maintained with a
4709 set of automated tools; perhaps one set of tools updates them and
4710 another set of tools uses the result. In this situation, it might be
4711 useful for the second set of tools to know if the files have recently
4712 been changed. It might be useful, for example, to have a 'timestamp'
4713 file which gives the timestamp on the newest file in the collection.
4715 We can use @code{find} to achieve this, but there are several
4716 different ways to do it.
4718 @subsection Updating the Timestamp The Wrong Way
4720 The obvious but wrong answer is just to use @samp{-newer}:
4723 find subdir -newer timestamp -exec touch -r @{@} timestamp \;
4726 This does the right sort of thing but has a bug. Suppose that two
4727 files in the subdirectory have been updated, and that these are called
4728 @file{file1} and @file{file2}. The command above will update
4729 @file{timestamp} with the modification time of @file{file1} or that of
4730 @file{file2}, but we don't know which one. Since the timestamps on
4731 @file{file1} and @file{file2} will in general be different, this could
4732 well be the wrong value.
4734 One solution to this problem is to modify @code{find} to recheck the
4735 modification time of @file{timestamp} every time a file is to be
4736 compared against it, but that will reduce the performance of
4739 @subsection Using the test utility to compare timestamps
4741 The @code{test} command can be used to compare timestamps:
4744 find subdir -exec test @{@} -nt timestamp \; -exec touch -r @{@} timestamp \;
4747 This will ensure that any changes made to the modification time of
4748 @file{timestamp} that take place during the execution of @code{find}
4749 are taken into account. This resolves our earlier problem, but
4750 unfortunately this runs much more slowly.
4752 @subsection A combined approach
4754 We can of course still use @samp{-newer} to cut down on the number of
4755 calls to @code{test}:
4758 find subdir -newer timestamp -and \
4759 -exec test @{@} -nt timestamp \; -and \
4760 -exec touch -r @{@} timestamp \;
4763 Here, the @samp{-newer} test excludes all the files which are
4764 definitely older than the timestamp, but all the files which are newer
4765 than the old value of the timestamp are compared against the current
4768 This is indeed faster in general, but the speed difference will depend
4769 on how many updated files there are.
4771 @subsection Using @code{-printf} and @code{sort} to compare timestamps
4773 It is possible to use the @samp{-printf} action to abandon the use of
4774 @code{test} entirely:
4777 newest=$(find subdir -newer timestamp -printf "%A@:%p\n" |
4781 touch -r "$@{newest:-timestamp@}" timestamp
4784 The command above works by generating a list of the timestamps and
4785 names of all the files which are newer than the timestamp. The
4786 @code{sort}, @code{tail} and @code{cut} commands simply pull out the
4787 name of the file with the largest timestamp value (that is, the latest
4788 file). The @code{touch} command is then used to update the timestamp,
4790 The @code{"$@{newest:-timestamp@}"} expression simply expands to the
4791 value of @code{$newest} if that variable is set, but to
4792 @file{timestamp} otherwise. This ensures that an argument is always
4793 given to the @samp{-r} option of the @code{touch} command.
4795 This approach seems quite efficient, but unfortunately it has a
4796 problem. Many operating systems now keep file modification time
4797 information at a granularity which is finer than one second.
4798 Findutils version 4.3.3 and later will print a fractional part with
4799 %A@@, but older versions will not.
4802 @subsection Solving the problem with @code{make}
4804 Another tool which often works with timestamps is @code{make}. We can
4805 use @code{find} to generate a @file{Makefile} file on the fly and then
4806 use @code{make} to update the timestamps:
4813 -printf "timestamp:: %p\n\ttouch -r %p timestamp\n\n" > "$makefile"
4818 Unfortunately although the solution above is quite elegant, it fails
4819 to cope with white space within file names, and adjusting it to do so
4820 would require a rather complex shell script.
4823 @subsection Coping with odd filenames too
4825 We can fix both of these problems (looping and problems with white
4826 space), and do things more efficiently too. The following command
4827 works with newlines and doesn't need to sort the list of filenames.
4830 find subdir -newer timestamp -printf "%A@@:%p\0" |
4832 xargs --no-run-if-empty --null -i \
4833 find @{@} -maxdepth 0 -newer timestamp -exec touch -r @{@} timestamp \;
4836 The first @code{find} command generates a list of files which are
4837 newer than the original timestamp file, and prints a list of them with
4838 their timestamps. The @file{newest.pl} script simply filters out all
4839 the filenames which have timestamps which are older than whatever the
4846 my $latest_stamp = undef;
4848 my ($stamp, $name) = split(/:/);
4849 if (!defined($latest_stamp) || ($tstamp > $latest_stamp)) {
4850 $latest_stamp = $stamp;
4853 if ($tstamp >= $latest_stamp) {
4854 push @newest, $name;
4857 print join("\0", @newest);
4861 This prints a list of zero or more files, all of which are newer than
4862 the original timestamp file, and which have the same timestamp as each
4863 other, to the nearest second. The second @code{find} command takes
4864 each resulting file one at a time, and if that is newer than the
4865 timestamp file, the timestamp is updated.
4867 @node Finding the Shallowest Instance
4868 @section Finding the Shallowest Instance
4870 Suppose you maintain local copies of sources from various projects,
4871 each with their own choice of directory organisation and source code
4872 management (SCM) tool. You need to periodically synchronize each
4873 project with its upstream tree. As the number local repositories
4874 grows, so does the work involved in maintaining synchronization. SCM
4875 utilities typically create some sort of administrative directory: .svn
4876 for Subversion, CVS for CVS, and so on. These directories can be used
4877 as a key to search for the bases of the project source trees. Suppose
4878 we have the following directory structure:
4882 repo/gnu/project2/.svn
4883 repo/gnu/project3/.svn
4884 repo/gnu/project3/src/.svn
4885 repo/gnu/project3/doc/.svn
4889 One would expect to update each of the @file{projectX} directories,
4890 but not their subdirectories (src, doc, etc.). To locate the project
4891 roots, we would need to find the least deeply nested directories
4892 containing an SCM-related subdirectory. The following command
4893 discovers those roots efficiently. It is efficient because it avoids
4894 searching subdirectories inside projects whose SCM directory we
4899 -exec test -d @{@}/.svn \; -or \
4900 -exec test -d @{@}/.git \; -or \
4901 -exec test -d @{@}/CVS \; -print -prune
4904 In this example, @command{test} is used to tell if we are currently
4905 examining a directory which appears to the a project's root directory
4906 (because it has an SCM subdirectory). When we find a project root,
4907 there is no need to search inside it, and @code{-prune} makes sure
4908 that we descend no further.
4910 For large, complex trees like the Linux kernel, this will prevent
4911 searching a large portion of the structure, saving a good deal of
4915 @node Security Considerations
4916 @chapter Security Considerations
4918 Security considerations are important if you are using @code{find} or
4919 @code{xargs} to search for or process files that don't belong to you
4920 or which other people have control. Security considerations
4921 relating to @code{locate} may also apply if you have files which you
4922 do not want others to see.
4924 The most severe forms of security problems affecting
4925 @code{find} and related programs are when third parties bring
4926 about a situation allowing them to do something
4927 they would normally not be able to accomplish. This is called @emph{privilege
4928 elevation}. This might include deleting files they would not normally
4929 be able to delete. It is common for the operating system to periodically
4930 invoke @code{find} for self-maintenance purposes. These invocations of
4931 @code{find} are particularly problematic from a security point of view
4932 as these are often invoked by the superuser and search the entire
4933 filesystem hierarchy. Generally, the severity of any associated problem depends
4934 on what the system is going to do with the files found by @code{find}.
4937 * Levels of Risk:: What is your level of exposure to security problems?
4938 * Security Considerations for find:: Security problems with find
4939 * Security Considerations for xargs:: Security problems with xargs
4940 * Security Considerations for locate:: Security problems with locate
4941 * Security Summary:: That was all very complex, what does it boil down to?
4942 * Further Reading on Security::
4946 @node Levels of Risk
4947 @section Levels of Risk
4949 There are some security risks inherent in the use of @code{find},
4950 @code{xargs} and (to a lesser extent) @code{locate}. The severity of
4951 these risks depends on what sort of system you are using:
4955 Multi-user systems where you do not control (or trust) the other
4956 users, and on which you execute @code{find}, including areas where
4957 those other users can manipulate the filesystem (for example beneath
4958 @file{/home} or @file{/tmp}).
4961 Systems where the actions of other users can create file names chosen
4962 by them, but to which they don't have access while @code{find} is
4963 being run. This access might include leaving programs running (shell
4964 background jobs, @code{at} or @code{cron} tasks, for example). On
4965 these sorts of systems, carefully written commands (avoiding use of
4966 @samp{-print} for example) should not expose you to a high degree of
4967 risk. Most systems fall into this category.
4970 Systems to which untrusted parties do not have access, cannot create
4971 file names of their own choice (even remotely) and which contain no
4972 security flaws which might enable an untrusted third party to gain
4973 access. Most systems do not fall into this category because there are
4974 many ways in which external parties can affect the names of files that
4975 are created on your system. The system on which I am writing this for
4976 example automatically downloads software updates from the Internet;
4977 the names of the files in which these updates exist are chosen by
4978 third parties@footnote{Of course, I trust these parties to a large
4979 extent anyway, because I install software provided by them; I choose
4980 to trust them in this way, and that's a deliberate choice}.
4983 In the discussion above, ``risk'' denotes the likelihood that someone
4984 can cause @code{find}, @code{xargs}, @code{locate} or some other
4985 program which is controlled by them to do something you did not
4986 intend. The levels of risk suggested do not take any account of the
4987 consequences of this sort of event. That is, if you operate a ``low
4988 risk'' type system, but the consequences of a security problem are
4989 disastrous, then you should still give serious thought to all the
4990 possible security problems, many of which of course will not be
4991 discussed here -- this section of the manual is intended to be
4992 informative but not comprehensive or exhaustive.
4994 If you are responsible for the operation of a system where the
4995 consequences of a security problem could be very important, you should
4999 @item Define a security policy which defines who is allowed to do what
5001 @item Seek competent advice on how to enforce your policy, detect
5002 breaches of that policy, and take account of any potential problems
5003 that might fall outside the scope of your policy.
5007 @node Security Considerations for find
5008 @section Security Considerations for @code{find}
5011 Some of the actions @code{find} might take have a direct effect;
5012 these include @code{-exec} and @code{-delete}. However, it is also
5013 common to use @code{-print} explicitly or implicitly, and so if
5014 @code{find} produces the wrong list of file names, that can also be a
5015 security problem; consider the case for example where @code{find} is
5016 producing a list of files to be deleted.
5018 We normally assume that the @code{find} command line expresses the
5019 file selection criteria and actions that the user had in mind -- that
5020 is, the command line is ``trusted'' data.
5022 From a security analysis point of view, the output of @code{find}
5023 should be correct; that is, the output should contain only the names
5024 of those files which meet the user's criteria specified on the command
5025 line. This applies for the @code{-exec} and @code{-delete} actions;
5026 one can consider these to be part of the output.
5028 On the other hand, the contents of the filesystem can be manipulated
5029 by other people, and hence we regard this as ``untrusted'' data. This
5030 implies that the @code{find} command line is a filter which converts
5031 the untrusted contents of the filesystem into a correct list of output
5034 The filesystem will in general change while @code{find} is searching
5035 it; in fact, most of the potential security problems with @code{find}
5036 relate to this issue in some way.
5038 @dfn{Race conditions} are a general class of security problem where the
5039 relative ordering of actions taken by @code{find} (for example) and
5040 something else are critically important in getting the correct and expected result@footnote{This is more or less the
5041 definition of the term ``race condition''} .
5043 For @code{find}, an attacker might move or rename files or directories in
5044 the hope that an action might be taken against a file which was not
5045 normally intended to be affected. Alternatively, this sort of attack
5046 might be intended to persuade @code{find} to search part of the
5047 filesystem which would not normally be included in the search
5048 (defeating the @code{-prune} action for example).
5051 * Problems with -exec and filenames::
5052 * Changing the Current Working Directory::
5053 * Race Conditions with -exec::
5054 * Race Conditions with -print and -print0::
5057 @node Problems with -exec and filenames
5058 @subsection Problems with @code{-exec} and filenames
5060 It is safe in many cases to use the @samp{-execdir} action with any
5061 file name. Because @samp{-execdir} prefixes the arguments it passes
5062 to programs with @samp{./}, you will not accidentally pass an argument
5063 which is interpreted as an option. For example the file @file{-f}
5064 would be passed to @code{rm} as @file{./-f}, which is harmless.
5066 However, your degree of safety does depend on the nature of the
5067 program you are running. For example constructs such as these two commands
5071 find -exec sh -c "something @{@}" \;
5072 find -execdir sh -c "something @{@}" \;
5075 are very dangerous. The reason for this is that the @samp{@{@}} is
5076 expanded to a filename which might contain a semicolon or other
5077 characters special to the shell. If for example someone creates the
5078 file @file{/tmp/foo; rm -rf $HOME} then the two commands above could
5079 delete someone's home directory.
5081 So for this reason do not run any command which will pass untrusted
5082 data (such as the names of files) to commands which interpret
5083 arguments as commands to be further interpreted (for example
5086 In the case of the shell, there is a clever workaround for this
5091 find -exec sh -c 'something "$@@"' sh @{@} \;
5092 find -execdir sh -c 'something "$@@"' sh @{@}\;
5095 This approach is not guaranteed to avoid every problem, but it is much
5096 safer than substituting data of an attacker's choice into the text of
5099 @node Changing the Current Working Directory
5100 @subsection Changing the Current Working Directory
5102 As @code{find} searches the filesystem, it finds subdirectories and
5103 then searches within them by changing its working directory. First,
5104 @code{find} reaches and recognises a subdirectory. It then decides if that
5105 subdirectory meets the criteria for being searched; that is, any
5106 @samp{-xdev} or @samp{-prune} expressions are taken into account. The
5107 @code{find} program will then change working directory and proceed to
5108 search the directory.
5110 A race condition attack might take the form that once the checks
5111 relevant to @samp{-xdev} and @samp{-prune} have been done, an attacker
5112 might rename the directory that was being considered, and put in its
5113 place a symbolic link that actually points somewhere else.
5115 The idea behind this attack is to fool @code{find} into going into the
5116 wrong directory. This would leave @code{find} with a working
5117 directory chosen by an attacker, bypassing any protection apparently
5118 provided by @samp{-xdev} and @samp{-prune}, and any protection
5119 provided by being able to @emph{not} list particular directories on
5120 the @code{find} command line. This form of attack is particularly
5121 problematic if the attacker can predict when the @code{find} command
5122 will be run, as is the case with @code{cron} tasks for example.
5124 GNU @code{find} has specific safeguards to prevent this general class
5125 of problem. The exact form of these safeguards depends on the
5126 properties of your system.
5129 * O_NOFOLLOW:: Safely changing directory using @code{fchdir}.
5130 * Systems without O_NOFOLLOW:: Checking for symbolic links after @code{chdir}.
5134 @subsubsection @code{O_NOFOLLOW}
5136 If your system supports the @code{O_NOFOLLOW} flag @footnote{GNU/Linux
5137 (kernel version 2.1.126 and later) and FreeBSD (3.0-CURRENT and later)
5138 support this} to the @code{open(2)} system call, @code{find} uses it
5139 to safely change directories. The target directory is first opened
5140 and then @code{find} changes working directory with the
5141 @code{fchdir()} system call. This ensures that symbolic links are not
5142 followed, preventing the sort of race condition attack in which use
5143 is made of symbolic links.
5145 If for any reason this approach does not work, @code{find} will fall
5146 back on the method which is normally used if @code{O_NOFOLLOW} is not
5149 You can tell if your system supports @code{O_NOFOLLOW} by running
5155 This will tell you the version number and which features are enabled.
5156 For example, if I run this on my system now, this gives:
5158 find (GNU findutils) 4.5.11-git
5159 Copyright (C) 2012 Free Software Foundation, Inc.
5160 License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>.
5161 This is free software: you are free to change and redistribute it.
5162 There is NO WARRANTY, to the extent permitted by law.
5164 Written by Eric B. Decker, James Youngman, and Kevin Dalley.
5165 Features enabled: D_TYPE O_NOFOLLOW(enabled) LEAF_OPTIMISATION FTS(FTS_CWDFD) CBO(level=2)
5168 Here, you can see that I am running a version of @code{find} which was
5169 built from the development (git) code prior to the release of
5170 findutils-4.5.12, and that several features including @code{O_NOFOLLOW} are
5171 present. @code{O_NOFOLLOW} is qualified with ``enabled''. This simply means
5172 that the current system seems to support @code{O_NOFOLLOW}. This check is
5173 needed because it is possible to build @code{find} on a system that
5174 defines @code{O_NOFOLLOW} and then run it on a system that ignores the
5175 @code{O_NOFOLLOW} flag. We try to detect such cases at startup by checking
5176 the operating system and version number; when this happens you will
5177 see @samp{O_NOFOLLOW(disabled)} instead.
5179 @node Systems without O_NOFOLLOW
5180 @subsubsection Systems without @code{O_NOFOLLOW}
5182 The strategy for preventing this type of problem on systems that lack
5183 support for the @code{O_NOFOLLOW} flag is more complex. Each time
5184 @code{find} changes directory, it examines the directory it is about
5185 to move to, issues the @code{chdir()} system call, and then checks
5186 that it has ended up in the subdirectory it expected. If all is as
5187 expected, processing continues as normal. However, there are two main
5188 reasons why the directory might change: the use of an automounter and
5189 the someone removing the old directory and replacing it with something
5190 else while @code{find} is trying to descend into it.
5192 Where a filesystem ``automounter'' is in use it can be the case that
5193 the use of the @code{chdir()} system call can itself cause a new
5194 filesystem to be mounted at that point. On systems that do not
5195 support @code{O_NOFOLLOW}, this will cause @code{find}'s security check to
5198 However, this does not normally represent a security problem, since
5199 the automounter configuration is normally set up by the system
5200 administrator. Therefore, if the @code{chdir()} sanity check fails,
5201 @code{find} will make one more attempt@footnote{This may not be the
5202 case for the fts-based executable}. If that succeeds, execution
5203 carries on as normal. This is the usual case for automounters.
5205 Where an attacker is trying to exploit a race condition, the problem
5206 may not have gone away on the second attempt. If this is the case,
5207 @code{find} will issue a warning message and then ignore that
5208 subdirectory. When this happens, actions such as @samp{-exec} or
5209 @samp{-print} may already have taken place for the problematic
5210 subdirectory. This is because @code{find} applies tests and actions
5211 to directories before searching within them (unless @samp{-depth} was
5214 Because of the nature of the directory-change operation and security
5215 check, in the worst case the only things that @code{find} would have
5216 done with the directory are to move into it and back out to the
5217 original parent. No operations would have been performed within that
5220 @node Race Conditions with -exec
5221 @subsection Race Conditions with @code{-exec}
5223 The @samp{-exec} action causes another program to be run. It passes
5224 to the program the name of the file which is being considered at the
5225 time. The invoked program will typically then perform some action
5226 on that file. Once again, there is a race condition which can be
5227 exploited here. We shall take as a specific example the command
5230 find /tmp -path /tmp/umsp/passwd -exec /bin/rm
5233 In this simple example, we are identifying just one file to be deleted
5234 and invoking @code{/bin/rm} to delete it. A problem exists because
5235 there is a time gap between the point where @code{find} decides that
5236 it needs to process the @samp{-exec} action and the point where the
5237 @code{/bin/rm} command actually issues the @code{unlink()} system
5238 call to delete the file from the filesystem. Within this time period, an attacker can rename the
5239 @file{/tmp/umsp} directory, replacing it with a symbolic link to
5240 @file{/etc}. There is no way for @code{/bin/rm} to determine that it
5241 is working on the same file that @code{find} had in mind. Once the
5242 symbolic link is in place, the attacker has persuaded @code{find} to
5243 cause the deletion of the @file{/etc/passwd} file, which is not the
5244 effect intended by the command which was actually invoked.
5246 One possible defence against this type of attack is to modify the
5247 behaviour of @samp{-exec} so that the @code{/bin/rm} command is run
5248 with the argument @file{./passwd} and a suitable choice of working
5249 directory. This would allow the normal sanity check that @code{find}
5250 performs to protect against this form of attack too. Unfortunately,
5251 this strategy cannot be used as the POSIX standard specifies that the
5252 current working directory for commands invoked with @samp{-exec} must
5253 be the same as the current working directory from which @code{find}
5254 was invoked. This means that the @samp{-exec} action is inherently
5255 insecure and can't be fixed.
5257 GNU @code{find} implements a more secure variant of the @samp{-exec}
5258 action, @samp{-execdir}. The @samp{-execdir} action
5259 ensures that it is not necessary to dereference subdirectories to
5260 process target files. The current directory used to invoke programs
5261 is the same as the directory in which the file to be processed exists
5262 (@file{/tmp/umsp} in our example, and only the basename of the file to
5263 be processed is passed to the invoked command, with a @samp{./}
5264 prepended (giving @file{./passwd} in our example).
5266 The @samp{-execdir} action refuses to do anything if the current
5267 directory is included in the @var{$PATH} environment variable. This
5268 is necessary because @samp{-execdir} runs programs in the same
5269 directory in which it finds files -- in general, such a directory
5270 might be writable by untrusted users. For similar reasons,
5271 @samp{-execdir} does not allow @samp{@{@}} to appear in the name of
5272 the command to be run.
5274 @node Race Conditions with -print and -print0
5275 @subsection Race Conditions with @code{-print} and @code{-print0}
5277 The @samp{-print} and @samp{-print0} actions can be used to produce a
5278 list of files matching some criteria, which can then be used with some
5279 other command, perhaps with @code{xargs}. Unfortunately, this means
5280 that there is an unavoidable time gap between @code{find} deciding
5281 that one or more files meet its criteria and the relevant command
5282 being executed. For this reason, the @samp{-print} and @samp{-print0}
5283 actions are just as insecure as @samp{-exec}.
5285 In fact, since the construction
5288 find @dots{} -print | xargs @enddots{}
5291 does not cope correctly with newlines or other ``white space'' in
5292 file names, and copes poorly with file names containing quotes, the
5293 @samp{-print} action is less secure even than @samp{-print0}.
5296 @comment node-name, next, previous, up
5297 @comment @node Security Considerations for xargs
5298 @node Security Considerations for xargs
5299 @section Security Considerations for @code{xargs}
5301 The description of the race conditions affecting the @samp{-print}
5302 action of @code{find} shows that @code{xargs} cannot be secure if it
5303 is possible for an attacker to modify a filesystem after @code{find}
5304 has started but before @code{xargs} has completed all its actions.
5306 However, there are other security issues that exist even if it is not
5307 possible for an attacker to have access to the filesystem in real
5308 time. Firstly, if it is possible for an attacker to create files with
5309 names of their choice on the filesystem, then @code{xargs} is
5310 insecure unless the @samp{-0} option is used. If a file with the name
5311 @file{/home/someuser/foo/bar\n/etc/passwd} exists (assume that
5312 @samp{\n} stands for a newline character), then @code{find @dots{} -print}
5313 can be persuaded to print three separate lines:
5316 /home/someuser/foo/bar
5321 If it finds a blank line in the input, @code{xargs} will ignore it.
5322 Therefore, if some action is to be taken on the basis of this list of
5323 files, the @file{/etc/passwd} file would be included even if this was
5324 not the intent of the person running find. There are circumstances in
5325 which an attacker can use this to their advantage. The same
5326 consideration applies to file names containing ordinary spaces rather
5327 than newlines, except that of course the list of file names will no
5328 longer contain an ``extra'' newline.
5330 This problem is an unavoidable consequence of the default behaviour of
5331 the @code{xargs} command, which is specified by the POSIX standard.
5332 The only ways to avoid this problem are either to avoid all use of
5333 @code{xargs} in favour for example of @samp{find -exec} or (where
5334 available) @samp{find -execdir}, or to use the @samp{-0} option, which
5335 ensures that @code{xargs} considers file names to be separated by
5336 ASCII NUL characters rather than whitespace. However, useful as this
5337 option is, the POSIX standard does not make it mandatory.
5339 POSIX also specifies that @code{xargs} interprets quoting and trailing
5340 whitespace specially in filenames, too. This means that using
5341 @code{find ... -print | xargs ...} can cause the commands run by
5342 @code{xargs} to receive a list of file names which is not the same as
5343 the list printed by @code{find}. The interpretation of quotes and
5344 trailing whitespace is turned off by the @samp{-0} argument to
5345 @code{xargs}, which is another reason to use that option.
5347 @comment node-name, next, previous, up
5348 @node Security Considerations for locate
5349 @section Security Considerations for @code{locate}
5351 @subsection Race Conditions
5352 It is fairly unusual for the output of @code{locate} to be fed into
5353 another command. However, if this were to be done, this would raise
5354 the same set of security issues as the use of @samp{find @dots{} -print}.
5355 Although the problems relating to whitespace in file names can be
5356 resolved by using @code{locate}'s @samp{-0} option, this still leaves
5357 the race condition problems associated with @samp{find @dots{} -print0}.
5358 There is no way to avoid these problems in the case of @code{locate}.
5360 @subsection Long File Name Bugs with Old-Format Databases
5361 Old versions of @code{locate} have a bug in the way that old-format
5362 databases are read. This bug affects the following versions of
5366 @item All releases prior to 4.2.31
5367 @item All 4.3.x releases prior to 4.3.7
5370 The affected versions of @code{locate} read file names into a
5371 fixed-length 1026 byte buffer, allocated on the heap. This buffer is
5372 not extended if file names are too long to fit into the buffer. No
5373 range checking on the length of the filename is performed. This could
5374 in theory lead to a privilege escalation attack. Findutils versions
5375 4.3.0 to 4.3.6 are also affected.
5377 On systems using the old database format and affected versions of
5378 @code{locate}, carefully-chosen long file names could in theory allow
5379 malicious users to run code of their choice as any user invoking
5382 If remote users can choose the names of files stored on your system,
5383 and these files are indexed by @code{updatedb}, this may be a remote
5384 security vulnerability. Findutils version 4.2.31 and findutils
5385 version 4.3.7 include fixes for this problem. The @code{updatedb},
5386 @code{bigram} and @code{code} programs do no appear to be affected.
5388 If you are also using GNU coreutils, you can use the following command
5389 to determine the length of the longest file name on a given system:
5392 find / -print0 | tr -c '\0' 'x' | tr '\0' '\n' | wc -L
5395 Although this problem is significant, the old database format is not
5396 the default, and use of the old database format is not common. Most
5397 installations and most users will not be affected by this problem.
5401 @node Security Summary
5404 Where untrusted parties can create files on the system, or affect the
5405 names of files that are created, all uses for @code{find},
5406 @code{locate} and @code{xargs} have known security problems except the
5410 @item Informational use only
5411 Uses where the programs are used to prepare lists of file names upon
5412 which no further action will ever be taken.
5414 @item @samp{-delete}
5415 Use of the @samp{-delete} action with @code{find} to delete files
5416 which meet specified criteria
5418 @item @samp{-execdir}
5419 Use of the @samp{-execdir} action with @code{find} where the
5420 @env{PATH} environment variable contains directories which contain
5421 only trusted programs.
5425 @node Further Reading on Security
5426 @section Further Reading on Security
5428 While there are a number of books on computer security, there are also
5429 useful articles on the web that touch on the issues described above:
5432 @item http://goo.gl/DAvh
5433 @c https://www.securecoding.cert.org/confluence/display/seccode/MSC09-C.+Character+Encoding+-+Use+Subset+of+ASCII+for+Safety
5434 This article describes some of the unfortunate effects of allowing
5435 free choice of file names.
5436 @item http://cwe.mitre.org/data/definitions/78.html
5437 Describes OS Command Injection
5438 @item https://cwe.mitre.org/data/definitions/73.html
5439 Describes problems arising from allowing remote computers to send
5440 requests which specify file names of their choice
5441 @item http://cwe.mitre.org/data/definitions/116.html
5442 Describes problems relating to encoding file names and escaping
5443 characters. This article is relevant to findutils because for command
5444 lines processed via the shell, the encoding and escaping rules are
5445 already set by the shell. For example command lines like @code{find
5446 ... -print | some-shell-script} require specific care.
5447 @item http://xkcd.com/327/
5448 A humorous and pithy summary of the broader problem.
5451 @comment node-name, next, previous, up
5452 @node Error Messages
5453 @chapter Error Messages
5455 This section describes some of the error messages sometimes made by
5456 @code{find}, @code{xargs}, or @code{locate}, explains them and in some
5457 cases provides advice as to what you should do about this.
5459 This manual is written in English. The GNU findutils software
5460 features translations of error messages for many languages. For this
5461 reason the error messages produced by the programs are made to be as
5462 self-explanatory as possible. This approach avoids leaving people to
5463 figure out which test an English-language error message corresponds
5464 to. Error messages which are self-explanatory will not normally be
5465 mentioned in this document. For those messages mentioned in this
5466 document, only the English-language version of the message will be
5470 * Error Messages From find::
5471 * Error Messages From xargs::
5472 * Error Messages From locate::
5473 * Error Messages From updatedb::
5476 @node Error Messages From find
5477 @section Error Messages From @code{find}
5479 Most error messages produced by find are self-explanatory. Error
5480 messages sometimes include a filename. When this happens, the
5481 filename is quoted in order to prevent any unusual characters in the
5482 filename making unwanted changes in the state of the terminal.
5485 @item invalid predicate `-foo'
5486 This means that the @code{find} command line included something that
5487 started with a dash or other special character. The @code{find}
5488 program tried to interpret this as a test, action or option, but
5489 didn't recognise it. If it was intended to be a test, check what was
5490 specified against the documentation. If, on the other hand, the
5491 string is the name of a file which has been expanded from a wildcard
5492 (for example because you have a @samp{*} on the command line),
5493 consider using @samp{./*} or just @samp{.} instead.
5495 @item unexpected extra predicate
5496 This usually happens if you have an extra bracket on the command line
5497 (for example @samp{find . -print \)}).
5499 @item Warning: filesystem /path/foo has recently been mounted
5500 @itemx Warning: filesystem /path/foo has recently been unmounted
5501 These messages might appear when @code{find} moves into a directory
5502 and finds that the device number and inode are different from what it
5503 expected them to be. If the directory @code{find} has moved into is
5504 on a network filesystem (NFS), it will not issue this message, because
5505 @code{automount} frequently mounts new filesystems on directories as
5506 you move into them (that is how it knows you want to use the
5507 filesystem). So, if you do see this message, be wary --
5508 @code{automount} may not have been responsible. Consider the
5509 possibility that someone else is manipulating the filesystem while
5510 @code{find} is running. Some people might do this in order to mislead
5511 @code{find} or persuade it to look at one set of files when it thought
5512 it was looking at another set.
5514 @item /path/foo changed during execution of find (old device number 12345, new device number 6789, filesystem type is <whatever>) [ref XXX]
5515 This message is issued when @code{find} moves into a directory and ends up
5516 somewhere it didn't expect to be. This happens in one of two
5517 circumstances. Firstly, this happens when @code{automount} intervenes
5518 on a system where @code{find} doesn't know how to determine what
5519 the current set of mounted filesystems is.
5521 Secondly, this can happen when the device number of a directory
5522 appears to change during a change of current directory, but
5523 @code{find} is moving up the filesystem hierarchy rather than down into it.
5524 In order to prevent @code{find} wandering off into some unexpected
5525 part of the filesystem, we stop it at this point.
5527 @item Don't know how to use getmntent() to read `/etc/mtab'. This is a bug.
5528 This message is issued when a problem similar to the above occurs on a
5529 system where @code{find} doesn't know how to figure out the current
5530 list of mount points. Ask for help on @email{bug-findutils@@gnu.org}.
5532 @item /path/foo/bar changed during execution of find (old inode number 12345, new inode number 67893, filesystem type is <whatever>) [ref XXX]"),
5533 This message is issued when @code{find} moves into a directory and
5534 discovers that the inode number of that directory
5535 is different from the inode number that it obtained when it examined the
5536 directory previously. This usually means that while
5537 @code{find} was deep in a directory hierarchy doing a
5538 time consuming operation, somebody has moved one of the parent directories to
5539 another location in the same filesystem. This may or may not have been done
5540 maliciously. In any case, @code{find} stops at this point
5541 to avoid traversing parts of the filesystem that it wasn't
5542 intended to. You can use @code{ls -li} or @code{find /path -inum
5543 12345 -o -inum 67893} to find out more about what has happened.
5545 @item sanity check of the fnmatch() library function failed.
5546 Please submit a bug report. You may well be asked questions about
5547 your system, and if you compiled the @code{findutils} code yourself,
5548 you should keep your copy of the build tree around. The likely
5549 explanation is that your system has a buggy implementation of
5550 @code{fnmatch} that looks enough like the GNU version to fool
5551 @code{configure}, but which doesn't work properly.
5554 This normally happens if you use the @code{-exec} action or
5555 something similar (@code{-ok} and so forth) but the system has run out
5556 of free process slots. This is either because the system is very busy
5557 and the system has reached its maximum process limit, or because you
5558 have a resource limit in place and you've reached it. Check the
5559 system for runaway processes (with @code{ps}, if possible). Some process
5560 slots are normally reserved for use by @samp{root}.
5562 @item some-program terminated by signal 99
5563 Some program which was launched with @code{-exec} or similar was killed
5564 with a fatal signal. This is just an advisory message.
5568 @node Error Messages From xargs
5569 @section Error Messages From @code{xargs}
5572 @item environment is too large for exec
5573 This message means that you have so many environment variables set (or
5574 such large values for them) that there is no room within the
5575 system-imposed limits on program command line argument length to
5576 invoke any program. This is an unlikely situation and is more likely
5577 result of an attempt to test the limits of @code{xargs}, or break it.
5578 Please try unsetting some environment variables, or exiting the
5579 current shell. You can also use @samp{xargs --show-limits} to
5580 understand the relevant sizes.
5582 @item argument list too long
5583 You are using the @samp{-I} option and @code{xargs} doesn't have
5584 enough space to build a command line because it has read a really
5585 large item and it doesn't fit. You may be able to work around this
5586 problem with the @samp{-s} option, but the default size is pretty
5587 large. This is a rare situation and is more likely an attempt to test
5588 the limits of @code{xargs}, or break it. Otherwise, you will need to
5589 try to shorten the problematic argument or not use @code{xargs}.
5591 @item argument line too long
5592 You are using the @samp{-L} or @samp{-l} option and one of the input
5593 lines is too long. You may be able to work around this problem with
5594 the @samp{-s} option, but the default size is pretty large. If you
5595 can modify the your @code{xargs} command not to use @samp{-L} or
5596 @samp{-l}, that will be more likely to result in success.
5599 See the description of the similar message for @code{find}.
5601 @item <program>: exited with status 255; aborting
5602 When a command run by @code{xargs} exits with status 255, @code{xargs}
5603 is supposed to stop. If this is not what you intended, wrap the
5604 program you are trying to invoke in a shell script which doesn't
5607 @item <program>: terminated by signal 99
5608 See the description of the similar message for @code{find}.
5610 @item cannot set SIGUSR1 signal handler
5611 @code{xargs} is having trouble preparing for you to be able to send it
5612 signals to increase or decrease the parallelism of its processing.
5613 If you don't plan to send it those signals, this warning can be ignored
5614 (though if you're a programmer, you may want to help us figure out
5615 why @code{xargs} is confused by your operating system).
5618 @node Error Messages From locate
5619 @section Error Messages From @code{locate}
5622 @item warning: database @file{@value{LOCATE_DB}} is more than 8 days old
5623 The @code{locate} program relies on a database which is periodically
5624 built by the @code{updatedb} program. That hasn't happened in a long
5625 time. To fix this problem, run @code{updatedb} manually. This can
5626 often happen on systems that are generally not left on, so the
5627 periodic ``cron'' task which normally does this doesn't get a chance
5630 @item locate database @file{@value{LOCATE_DB}} is corrupt or invalid
5631 This should not happen. Re-run @code{updatedb}. If that works, but
5632 @code{locate} still produces this error, run @code{locate --version}
5633 and @code{updatedb --version}. These should produce the same output.
5634 If not, you are using a mixed toolset; check your @samp{$PATH}
5635 environment variable and your shell aliases (if you have any). If
5636 both programs claim to be GNU versions, this is a bug; all versions of
5637 these programs should interoperate without problem. Ask for help on
5638 @email{bug-findutils@@gnu.org}.
5642 @node Error Messages From updatedb
5643 @section Error Messages From @code{updatedb}
5645 The @code{updatedb} program (and the programs it invokes) do issue
5646 error messages, but none seem to be candidates for guidance. If
5647 you are having a problem understanding one of these, ask for help on
5648 @email{bug-findutils@@gnu.org}.
5650 @node GNU Free Documentation License
5651 @appendix GNU Free Documentation License
5655 @unnumbered @code{find} Primary Index
5657 This is a list of all of the primaries (tests, actions, and options)
5658 that make up @code{find} expressions for selecting files. @xref{find
5659 Expressions}, for more information on expressions.
5665 @comment texi related words used by Emacs' spell checker ispell.el
5667 @comment LocalWords: texinfo setfilename settitle setchapternewpage
5668 @comment LocalWords: iftex finalout ifinfo DIR titlepage vskip pt
5669 @comment LocalWords: filll dir samp dfn noindent xref pxref
5670 @comment LocalWords: var deffn texi deffnx itemx emph asis
5671 @comment LocalWords: findex smallexample subsubsection cindex
5672 @comment LocalWords: dircategory direntry itemize
5674 @comment other words used by Emacs' spell checker ispell.el
5675 @comment LocalWords: README fred updatedb xargs Plett Rendell akefile
5676 @comment LocalWords: args grep Filesystems fo foo fOo wildcards iname
5677 @comment LocalWords: ipath regex iregex expr fubar regexps
5678 @comment LocalWords: metacharacters macs sr sc inode lname ilname
5679 @comment LocalWords: sysdep noleaf ls inum xdev filesystems usr atime
5680 @comment LocalWords: ctime mtime amin cmin mmin al daystart Sladkey rm
5681 @comment LocalWords: anewer cnewer bckw rf xtype uname gname uid gid
5682 @comment LocalWords: nouser nogroup chown chgrp perm ch maxdepth
5683 @comment LocalWords: mindepth cpio src CD AFS statted stat fstype ufs
5684 @comment LocalWords: nfs tmp mfs printf fprint dils rw djm Nov lwall
5685 @comment LocalWords: POSIXLY fls fprintf strftime locale's EDT GMT AP
5686 @comment LocalWords: EST diff perl backquotes sprintf Falstad Oct cron
5687 @comment LocalWords: eg vmunix mkdir afs allexec allwrite ARG bigram
5688 @comment LocalWords: bigrams cd chmod comp crc CVS dbfile eof
5689 @comment LocalWords: fileserver filesystem fn frcode Ghazi Hnewc iXX
5690 @comment LocalWords: joeuser Kaveh localpaths localuser LOGNAME
5691 @comment LocalWords: Meyering mv netpaths netuser nonblank nonblanks
5692 @comment LocalWords: ois ok Pinard printindex proc procs prunefs
5693 @comment LocalWords: prunepaths pwd RFS rmadillo rmdir rsh sbins str
5694 @comment LocalWords: su Timar ubins ug unstripped vf VM Weitzel
5695 @comment LocalWords: wildcard zlogout basename execdir wholename iwholename
5696 @comment LocalWords: timestamp timestamps Solaris FreeBSD OpenBSD POSIX