1 \input texinfo @c -*-texinfo-*-
4 @settitle Finding Files
5 @c For double-sided printing, uncomment:
6 @c @setchapternewpage odd
17 * Finding files: (find). Operating on files matching certain criteria.
22 This file documents the GNU utilities for finding files that match
23 certain criteria and performing various operations on them.
25 Copyright (C) 1994,1996,1998,2000,2001,2003,2004 Free Software Foundation, Inc.
27 Permission is granted to make and distribute verbatim copies of
28 this manual provided the copyright notice and this permission notice
29 are preserved on all copies.
32 Permission is granted to process this file through TeX and print the
33 results, provided the printed document carries copying permission
34 notice identical to this one except for the removal of this paragraph
35 (this paragraph not being relevant to the printed manual).
38 Permission is granted to copy and distribute modified versions of this
39 manual under the conditions for verbatim copying, provided that the entire
40 resulting derived work is distributed under the terms of a permission
41 notice identical to this one.
43 Permission is granted to copy and distribute translations of this manual
44 into another language, under the above conditions for modified versions,
45 except that this permission notice may be stated in a translation approved
51 @subtitle Edition @value{EDITION}, for GNU @code{find} version @value{VERSION}
52 @subtitle @value{UPDATED}
53 @author by David MacKenzie
56 @vskip 0pt plus 1filll
57 Copyright @copyright{} 1994,1996,1998,2000,2001,2003,2004 Free Software Foundation, Inc.
59 Permission is granted to make and distribute verbatim copies of
60 this manual provided the copyright notice and this permission notice
61 are preserved on all copies.
63 Permission is granted to copy and distribute modified versions of this
64 manual under the conditions for verbatim copying, provided that the entire
65 resulting derived work is distributed under the terms of a permission
66 notice identical to this one.
68 Permission is granted to copy and distribute translations of this manual
69 into another language, under the above conditions for modified versions,
70 except that this permission notice may be stated in a translation approved
74 @node Top, Introduction, , (dir)
75 @comment node-name, next, previous, up
78 This file documents the GNU utilities for finding files that match
79 certain criteria and performing various actions on them.
80 This is edition @value{EDITION}, for @code{find} version @value{VERSION}.
83 @c The master menu, created with texinfo-master-menu, goes here.
86 * Introduction:: Summary of the tasks this manual describes.
87 * Finding Files:: Finding files that match certain criteria.
88 * Actions:: Doing things to files you have found.
89 * Common Tasks:: Solutions to common real-world problems.
90 * Databases:: Maintaining file name databases.
91 * File Permissions:: How to control access to files.
92 * Reference:: Summary of how to invoke the programs.
93 * Security Considerations:: Security issues relating to findutils.
94 * Error Messages:: Explanations of some messages you might see.
95 * Primary Index:: The components of @code{find} expressions.
98 @node Introduction, Finding Files, Top, Top
101 This manual shows how to find files that meet criteria you specify, and
102 how to perform various actions on the files that you find. The
103 principal programs that you use to perform these tasks are @code{find},
104 @code{locate}, and @code{xargs}. Some of the examples in this manual
105 use capabilities specific to the GNU versions of those programs.
107 GNU @code{find} was originally written by Eric Decker, with enhancements
108 by David MacKenzie, Jay Plett, and Tim Wood. GNU @code{xargs} was
109 originally written by Mike Rendell, with enhancements by David
110 MacKenzie. GNU @code{locate} and its associated utilities were
111 originally written by James Woods, with enhancements by David MacKenzie.
112 The idea for @samp{find -print0} and @samp{xargs -0} came from Dan
113 Bernstein. The current maintainer of GNU findutils (and this manual) is
114 James Youngman. Many other people have contributed bug fixes, small
115 improvements, and helpful suggestions. Thanks!
117 Mail suggestions and bug reports for these programs to
118 @code{bug-findutils@@gnu.org}. Please include the version
119 number, which you can get by running @samp{find --version}.
130 For brevity, the word @dfn{file} in this manual means a regular file, a
131 directory, a symbolic link, or any other kind of node that has a
132 directory entry. A directory entry is also called a @dfn{file name}. A
133 file name may contain some, all, or none of the directories in a path
134 that leads to the file. These are all examples of what this manual
135 calls ``file names'':
142 /usr/local/include/termcap.h
145 A @dfn{directory tree} is a directory and the files it contains, all of
146 its subdirectories and the files they contain, etc. It can also be a
147 single non-directory file.
149 These programs enable you to find the files in one or more directory
154 have names that contain certain text or match a certain pattern;
156 are links to certain files;
158 were last used during a certain period of time;
160 are within a certain size range;
162 are of a certain type (regular file, directory, symbolic link, etc.);
164 are owned by a certain user or group;
166 have certain access permissions;
168 contain text that matches a certain pattern;
170 are within a certain depth in the directory tree;
172 or some combination of the above.
175 Once you have found the files you're looking for (or files that are
176 potentially the ones you're looking for), you can do more to them than
177 simply list their names. You can get any combination of the files'
178 attributes, or process the files in many ways, either individually or in
179 groups of various sizes. Actions that you might want to perform on the
180 files you have found include, but are not limited to:
190 change access permissions
195 This manual describes how to perform each of those tasks, and more.
200 The principal programs used for making lists of files that match given
201 criteria and running commands on them are @code{find}, @code{locate},
202 and @code{xargs}. An additional command, @code{updatedb}, is used by
203 system administrators to create databases for @code{locate} to use.
205 @code{find} searches for files in a directory hierarchy and prints
206 information about the files it found. It is run like this:
209 find @r{[}@var{file}@dots{}@r{]} @r{[}@var{expression}@r{]}
213 Here is a typical use of @code{find}. This example prints the names of
214 all files in the directory tree rooted in @file{/usr/src} whose name
215 ends with @samp{.c} and that are larger than 100 Kilobytes.
217 find /usr/src -name '*.c' -size +100k -print
220 @code{locate} searches special file name databases for file names that
221 match patterns. The system administrator runs the @code{updatedb}
222 program to create the databases. @code{locate} is run like this:
225 locate @r{[}@var{option}@dots{}@r{]} @var{pattern}@dots{}
229 This example prints the names of all files in the default file name
230 database whose name ends with @samp{Makefile} or @samp{makefile}. Which
231 file names are stored in the database depends on how the system
232 administrator ran @code{updatedb}.
234 locate '*[Mm]akefile'
237 The name @code{xargs}, pronounced EX-args, means ``combine arguments.''
238 @code{xargs} builds and executes command lines by gathering together
239 arguments it reads on the standard input. Most often, these arguments
240 are lists of file names generated by @code{find}. @code{xargs} is run
244 xargs @r{[}@var{option}@dots{}@r{]} @r{[}@var{command} @r{[}@var{initial-arguments}@r{]}@r{]}
248 The following command searches the files listed in the file
249 @file{file-list} and prints all of the lines in them that contain the
252 xargs grep typedef < file-list
255 @node find Expressions
256 @section @code{find} Expressions
258 The expression that @code{find} uses to select files consists of one or
259 more @dfn{primaries}, each of which is a separate command line argument
260 to @code{find}. @code{find} evaluates the expression each time it
261 processes a file. An expression can contain any of the following types
266 affect overall operation rather than the processing of a specific file;
268 return a true or false value, depending on the file's attributes;
270 have side effects and return a true or false value; and
272 connect the other arguments and affect when and whether they are
276 You can omit the operator between two primaries; it defaults to
277 @samp{-and}. @xref{Combining Primaries With Operators}, for ways to
278 connect primaries into more complex expressions. If the expression
279 contains no actions other than @samp{-prune}, @samp{-print} is performed
280 on all files for which the entire expression is true (@pxref{Print File
283 Options take effect immediately, rather than being evaluated for each
284 file when their place in the expression is reached. Therefore, for
285 clarity, it is best to place them at the beginning of the expression.
287 Many of the primaries take arguments, which immediately follow them in
288 the next command line argument to @code{find}. Some arguments are file
289 names, patterns, or other strings; others are numbers. Numeric
290 arguments can be specified as
294 for greater than @var{n},
296 for less than @var{n},
301 @node Finding Files, Actions, Introduction, Top
302 @chapter Finding Files
304 By default, @code{find} prints to the standard output the names of the
305 files that match the given criteria. @xref{Actions}, for how to get more
306 information about the matching files.
320 * Combining Primaries With Operators::
326 Here are ways to search for files whose name matches a certain pattern.
327 @xref{Shell Pattern Matching}, for a description of the @var{pattern}
328 arguments to these tests.
330 Each of these tests has a case-sensitive version and a case-insensitive
331 version, whose name begins with @samp{i}. In a case-insensitive
332 comparison, the patterns @samp{fo*} and @samp{F??} match the file names
333 @file{Foo}, @samp{FOO}, @samp{foo}, @samp{fOo}, etc.
336 * Base Name Patterns::
337 * Full Name Patterns::
338 * Fast Full Name Search::
339 * Shell Pattern Matching:: Wildcards used by these programs.
342 @node Base Name Patterns
343 @subsection Base Name Patterns
345 @deffn Test -name pattern
346 @deffnx Test -iname pattern
347 True if the base of the file name (the path with the leading directories
348 removed) matches shell pattern @var{pattern}. For @samp{-iname}, the
349 match is case-insensitive. To ignore a whole directory tree, use
350 @samp{-prune} (@pxref{Directories}). As an example, to find Texinfo
351 source files in @file{/usr/local/doc}:
354 find /usr/local/doc -name '*.texi'
358 Patterns for @samp{-name} and @samp{-iname} will match a filename with
359 a leading @samp{.}. For example the command @samp{find /tmp -name
360 \*bar} will match the file @file{/tmp/.foobar}.
363 @node Full Name Patterns
364 @subsection Full Name Patterns
366 @deffn Test -wholename pattern
367 @deffnx Test -iwholename pattern
368 True if the entire file name, starting with the command line argument
369 under which the file was found, matches shell pattern @var{pattern}.
370 For @samp{-iwholename}, the match is case-insensitive. To ignore a
371 whole directory tree, use @samp{-prune} rather than checking every
372 file in the tree (@pxref{Directories}). The ``entire file name'' as
373 used by find starts with the starting-point specified on the command
374 line, and is not converted to an absolute pathname, so for example
375 @code{cd /; find tmp -wholename /tmp} will never match anything.
378 @deffn Test -path pattern
379 @deffnx Test -ipath pattern
380 These tests are deprecated, but work as for @samp{-wholename} and @samp{-iwholename},
381 respectively. The @samp{-ipath} test is a GNU extension, but @samp{-path} is also
382 provided by HP-UX @code{find}.
385 @deffn Test -regex expr
386 @deffnx Test -iregex expr
387 True if the entire file name matches regular expression @var{expr}.
388 This is a match on the whole path, not a search. For example, to match
389 a file named @file{./fubar3}, you can use the regular expression
390 @samp{.*bar.} or @samp{.*b.*3}, but not @samp{f.*r3}. @xref{Regexps, ,
391 Syntax of Regular Expressions, emacs, The GNU Emacs Manual}, for a
392 description of the syntax of regular expressions. For @samp{-iregex},
393 the match is case-insensitive.
396 @node Fast Full Name Search
397 @subsection Fast Full Name Search
399 To search for files by name without having to actually scan the
400 directories on the disk (which can be slow), you can use the
401 @code{locate} program. For each shell pattern you give it,
402 @code{locate} searches one or more databases of file names and displays
403 the file names that contain the pattern. @xref{Shell Pattern Matching},
404 for details about shell patterns.
406 If a pattern is a plain string---it contains no
407 metacharacters---@code{locate} displays all file names in the database
408 that contain that string. If a pattern contains
409 metacharacters, @code{locate} only displays file names that match the
410 pattern exactly. As a result, patterns that contain metacharacters
411 should usually begin with a @samp{*}, and will most often end with one
412 as well. The exceptions are patterns that are intended to explicitly
413 match the beginning or end of a file name.
415 If you only want @code{locate} to match against the last component of
416 the filenames (the ``base name'' of the files) you can use the
417 @samp{--basename} option. The opposite behaviour is the default, but
418 can be selected explicitly by using the option @samp{--wholename}.
425 is almost equivalent to
427 find @var{directories} -name @var{pattern}
430 where @var{directories} are the directories for which the file name
431 databases contain information. The differences are that the
432 @code{locate} information might be out of date, and that @code{locate}
433 handles wildcards in the pattern slightly differently than @code{find}
434 (@pxref{Shell Pattern Matching}).
436 The file name databases contain lists of files that were on the system
437 when the databases were last updated. The system administrator can
438 choose the file name of the default database, the frequency with which
439 the databases are updated, and the directories for which they contain
442 Here is how to select which file name databases @code{locate} searches.
443 The default is system-dependent.
446 @item --database=@var{path}
448 Instead of searching the default file name database, search the file
449 name databases in @var{path}, which is a colon-separated list of
450 database file names. You can also use the environment variable
451 @code{LOCATE_PATH} to set the list of database files to search. The
452 option overrides the environment variable if both are used.
455 @node Shell Pattern Matching
456 @subsection Shell Pattern Matching
458 @code{find} and @code{locate} can compare file names, or parts of file
459 names, to shell patterns. A @dfn{shell pattern} is a string that may
460 contain the following special characters, which are known as
461 @dfn{wildcards} or @dfn{metacharacters}.
463 You must quote patterns that contain metacharacters to prevent the shell
464 from expanding them itself. Double and single quotes both work; so does
465 escaping with a backslash.
469 Matches any zero or more characters.
472 Matches any one character.
475 Matches exactly one character that is a member of the string
476 @var{string}. This is called a @dfn{character class}. As a shorthand,
477 @var{string} may contain ranges, which consist of two characters with a
478 dash between them. For example, the class @samp{[a-z0-9_]} matches a
479 lowercase letter, a number, or an underscore. You can negate a class by
480 placing a @samp{!} or @samp{^} immediately after the opening bracket.
481 Thus, @samp{[^A-Z@@]} matches any character except an uppercase letter
485 Removes the special meaning of the character that follows it. This
486 works even in character classes.
489 In the @code{find} tests that do shell pattern matching (@samp{-name},
490 @samp{-wholename}, etc.), wildcards in the pattern will match a @samp{.}
491 at the beginning of a file name. This is also the case for
492 @code{locate}. Thus, @samp{find -name '*macs'} will match a file
493 named @file{.emacs}, as will @samp{locate '*macs'}.
495 Slash characters have no special significance in the shell pattern
496 matching that @code{find} and @code{locate} do, unlike in the shell, in
497 which wildcards do not match them. Therefore, a pattern @samp{foo*bar}
498 can match a file name @samp{foo3/bar}, and a pattern @samp{./sr*sc} can
499 match a file name @samp{./src/misc}.
501 If you want to locate some files with the @samp{locate} command but
502 don't need to see the full list you can use the @samp{--limit} option
503 to see just a small number of results, or the @samp{--count} option to
504 display only the total number of matches.
509 There are two ways that files can be linked together. @dfn{Symbolic
510 links} are a special type of file whose contents are a portion of the
511 name of another file. @dfn{Hard links} are multiple directory entries
512 for one file; the file names all have the same index node (@dfn{inode})
521 @subsection Symbolic Links
523 Symbolic links are names that reference other files. GNU @code{find}
524 will handle symbolic links in one of two ways; firstly, it can
525 dereference the links for you - this means that if it comes across a
526 symbolic link, it examines the file that the link points to, in order
527 to see if it matches the criteria you have specified. Secondly, it
528 can check the link itself in case you might be looking for the actual
529 link. If the file that the symbolic link points to is also within the
530 directory hierarchy you are searching with the @code{find} command,
531 you may not see a great deal of difference between these two
534 By default, @code{find} examines symbolic links themselves when it
535 finds them (and, if it later comes across the linked-to file, it will
536 examine that, too). If you would prefer @code{find} to dereference
537 the links and examine the file that each link points to, specify the
538 @samp{-L} option to @code{find}. You can explicitly specify the
539 default behaviour by using the @samp{-P} option. The @samp{-H}
540 option is a half-way-between option which ensures that any symbolic
541 links listed on the command line are dereferenced, but other symbolic
544 Symbolic links are different to ``hard links'' in the sense that you
545 need permissions upon the linked-to file in order to be able to
546 dereference the link. This can mean that even if you specify the
547 @samp{-L} option, find may not be able to determine the properties of
548 the file that the link points to (because you don't have sufficient
549 permissions). In this situation, @samp{find} uses the properties of
550 the link itself. This also occurs if a symbolic link exists but
551 points to a file that is missing.
553 The options controlling the behaviour of @code{find} with respect to
554 links are as follows :-
558 @code{find} does not dereference symbolic links at all. This is the
559 default behaviour. This option must be specified before any of the
560 path names on the command line.
562 @code{find} does not dereference symbolic links (except in the case of
563 file names on the command line, which are dereferenced). If a
564 symbolic link cannot be dereferenced, the information for the symbolic
565 link itself is used. This option must be specified before any of the
566 path names on the command line.
568 @code{find} dereferences symbolic links where possible, and where this
569 is not possible it uses the properties of the symbolic link itself.
570 This option must be specified before any of the path names on the
571 command line. Use of this option also implies the same behaviour as
572 the @samp{-noleaf} option. If you later use the @samp{-H} or
573 @samp{-P} options, this does not turn off @samp{-noleaf}.
576 This option forms part of the ``expression'' and must be specified
577 after the path names, but it is otherwise equivalent to @samp{-L}.
580 The following differences in behavior occur when the @samp{-L} option
585 @code{find} follows symbolic links to directories when searching
588 @samp{-lname} and @samp{-ilname} always return false (unless they
589 happen to match broken symbolic links).
591 @samp{-type} reports the types of the files that symbolic links point
594 Implies @samp{-noleaf} (@pxref{Directories}).
597 If the @samp{-L} option or the @samp{-H} option is used,
598 the filenames used as arguments to @samp{-newer}, @samp{-anewer}, and
599 @samp{-cnewer} are dereferenced and the timestamp from the pointed-to
600 file is used instead (if possible -- otherwise the timestamp from the
601 symbolic link is used).
603 @deffn Test -lname pattern
604 @deffnx Test -ilname pattern
605 True if the file is a symbolic link whose contents match shell pattern
606 @var{pattern}. For @samp{-ilname}, the match is case-insensitive.
607 @xref{Shell Pattern Matching}, for details about the @var{pattern}
608 argument. If the @samp{-L} option is in effect, this test will always
609 fail for symbolic links unless they are broken. So, to list any
610 symbolic links to @file{sysdep.c} in the current directory and its
611 subdirectories, you can do:
614 find . -lname '*sysdep.c'
619 @subsection Hard Links
621 To find hard links, first get the inode number of the file whose links
622 you want to find. You can learn a file's inode number and the number of
623 links to it by running @samp{ls -i} or @samp{find -ls}. If the file has
624 more than one link, you can search for the other links by passing that
625 inode number to @samp{-inum}. Add the @samp{-xdev} option if you are
626 starting the search at a directory that has other filesystems mounted on
627 it, such as @file{/usr} on many systems. Doing this saves needless
628 searching, since hard links to a file must be on the same filesystem.
632 File has inode number @var{n}. The @samp{+} and @samp{-} qualifiers
633 also work, though these are rarely useful.
636 You can also search for files that have a certain number of links, with
637 @samp{-links}. Directories normally have at least two hard links; their
638 @file{.} entry is the second one. If they have subdirectories, each of
639 those also has a hard link called @file{..} to its parent directory.
642 File has @var{n} hard links.
645 @deffn Test -links +n
646 File has more than @var{n} hard links.
649 @deffn Test -links -n
650 File has fewer than @var{n} hard links.
656 Each file has three time stamps, which record the last time that certain
657 operations were performed on the file:
661 access (read the file's contents)
663 change the status (modify the file or its attributes)
665 modify (change the file's contents)
668 There is no timestamp that indicates when a file was @emph{created}.
670 You can search for files whose time stamps are within a certain age
671 range, or compare them to other time stamps.
675 * Comparing Timestamps::
679 @subsection Age Ranges
681 These tests are mainly useful with ranges (@samp{+@var{n}} and
685 @deffnx Test -ctime n
686 @deffnx Test -mtime n
687 True if the file was last accessed (or its status changed, or it was
688 modified) @var{n}*24 hours ago. The number of 24-hour periods since
689 the file's timestamp is always rounded down; therefore 0 means ``less
690 than 24 hours ago'', 1 means ``between 24 and 48 hours ago'', and so
697 True if the file was last accessed (or its status changed, or it was
698 modified) @var{n} minutes ago. These tests provide finer granularity of
699 measurement than @samp{-atime} et al., but rounding is done in a
700 similar way. For example, to list files in
701 @file{/u/bill} that were last read from 2 to 6 minutes ago:
704 find /u/bill -amin +2 -amin -6
708 @deffn Option -daystart
709 Measure times from the beginning of today rather than from 24 hours ago.
710 So, to list the regular files in your home directory that were modified
714 find ~ -daystart -type f -mtime 1
718 The @samp{-daystart} option is unlike most other options in that it
719 has an effect on the way that other tests are performed. The affected
720 tests are @samp{-amin}, @samp{-cmin}, @samp{-mmin}, @samp{-atime},
721 @samp{-ctime} and @samp{-mtime}.
723 @node Comparing Timestamps
724 @subsection Comparing Timestamps
726 As an alternative to comparing timestamps to the current time, you can
727 compare them to another file's timestamp. That file's timestamp could
728 be updated by another program when some event occurs. Or you could set
729 it to a particular fixed date using the @code{touch} command. For
730 example, to list files in @file{/usr} modified after February 1 of the
733 @c Idea from Rick Sladkey.
735 touch -t 02010000 /tmp/stamp$$
736 find /usr -newer /tmp/stamp$$
740 @deffn Test -anewer file
741 @deffnx Test -cnewer file
742 @deffnx Test -newer file
743 True if the file was last accessed (or its status changed, or it was
744 modified) more recently than @var{file} was modified. These tests are
745 affected by @samp{-follow} only if @samp{-follow} comes before them on
746 the command line. @xref{Symbolic Links}, for more information on
747 @samp{-follow}. As an example, to list any files modified since
748 @file{/bin/sh} was last modified:
751 find . -newer /bin/sh
756 True if the file was last accessed @var{n} days after its status was
757 last changed. Useful for finding files that are not being used, and
758 could perhaps be archived or removed to save disk space.
764 @deffn Test -size n@r{[}bckwMG@r{]}
765 True if the file uses @var{n} units of space, rounding up. The units
766 are 512-byte blocks by default, but they can be changed by adding a
767 one-character suffix to @var{n}:
771 512-byte blocks (never 1024)
775 kilobytes (1024 bytes)
784 The `b' suffix always considers blocks to be 512 bytes. This is not
785 affected by the setting (or non-setting) of the POSIXLY_CORRECT
786 environment variable. This behaviour is different to the behaviour of
787 the @samp{-ls} action). If you want to use 1024-byte units, use the
790 The number can be prefixed with a `+' or a `-'. A plus sign indicates
791 that the test should succeed if the file uses at least @var{n} units
792 of storage (this is the way I normally use this test) and a minus sign
793 indicates that the test should succeed if the file uses less than
794 @var{n} units of storage. There is no `=' prefix, because that's the
797 The size does not count indirect blocks, but it does count blocks in
798 sparse files that are not actually allocated. This handling of sparse
799 files differs from the output of the @samp{%k} and @samp{%b} format
800 specifiers for the @samp{-printf} predicate.
805 True if the file is empty and is either a regular file or a directory.
806 This might make it a good candidate for deletion. This test is useful
807 with @samp{-depth} (@pxref{Directories}) and @samp{-delete}
808 (@pxref{Single File}).
815 True if the file is of type @var{c}:
819 block (buffered) special
821 character (unbuffered) special
838 The same as @samp{-type} unless the file is a symbolic link. For
839 symbolic links: if @samp{-follow} has not been given, true if the file
840 is a link to a file of type @var{c}; if @samp{-follow} has been given,
841 true if @var{c} is @samp{l}. In other words, for symbolic links,
842 @samp{-xtype} checks the type of the file that @samp{-type} does not
843 check. @xref{Symbolic Links}, for more information on @samp{-follow}.
849 @deffn Test -user uname
850 @deffnx Test -group gname
851 True if the file is owned by user @var{uname} (belongs to group @var{gname}).
852 A numeric ID is allowed.
857 True if the file's numeric user ID (group ID) is @var{n}. These tests
858 support ranges (@samp{+@var{n}} and @samp{-@var{n}}), unlike
859 @samp{-user} and @samp{-group}.
863 @deffnx Test -nogroup
864 True if no user corresponds to the file's numeric user ID (no group
865 corresponds to the numeric group ID). These cases usually mean that the
866 files belonged to users who have since been removed from the system.
867 You probably should change the ownership of such files to an existing
868 user or group, using the @code{chown} or @code{chgrp} program.
874 @xref{File Permissions}, for information on how file permissions are
875 structured and how to specify them.
877 @deffn Test -perm mode
879 file's permissions are exactly @var{mode} (which can be numeric or symbolic).
880 Symbolic modes use mode 0 as a point of departure.
881 If @var{mode} starts with @samp{-}, true if
882 @emph{all} of the permissions set in @var{mode} are set for the file;
883 permissions not set in @var{mode} are ignored.
884 If @var{mode} starts with @samp{+}, true if
885 @emph{any} of the permissions set in @var{mode} are set for the file;
886 permissions not set in @var{mode} are ignored.
892 To search for files based on their contents, you can use the @code{grep}
893 program. For example, to find out which C source files in the current
894 directory contain the string @samp{thing}, you can do:
900 If you also want to search for the string in files in subdirectories,
901 you can combine @code{grep} with @code{find} and @code{xargs}, like
905 find . -name '*.[ch]' | xargs grep -l thing
908 The @samp{-l} option causes @code{grep} to print only the names of files
909 that contain the string, rather than the lines that contain it. The
910 string argument (@samp{thing}) is actually a regular expression, so it
911 can contain metacharacters. This method can be refined a little by
912 using the @samp{-r} option to make @code{xargs} not run @code{grep} if
913 @code{find} produces no output, and using the @code{find} action
914 @samp{-print0} and the @code{xargs} option @samp{-0} to avoid
915 misinterpreting files whose names contain spaces:
918 find . -name '*.[ch]' -print0 | xargs -r -0 grep -l thing
921 For a fuller treatment of finding files whose contents match a pattern,
922 see the manual page for @code{grep}.
927 Here is how to control which directories @code{find} searches, and how
928 it searches them. These two options allow you to process a horizontal
929 slice of a directory tree.
931 @deffn Option -maxdepth levels
932 Descend at most @var{levels} (a non-negative integer) levels of
933 directories below the command line arguments. @samp{-maxdepth 0} means
934 only apply the tests and actions to the command line arguments.
937 @deffn Option -mindepth levels
938 Do not apply any tests or actions at levels less than @var{levels} (a
939 non-negative integer). @samp{-mindepth 1} means process all files
940 except the command line arguments.
944 Process each directory's contents before the directory itself. Doing
945 this is a good idea when producing lists of files to archive with
946 @code{cpio} or @code{tar}. If a directory does not have write
947 permission for its owner, its contents can still be restored from the
948 archive since the directory's permissions are restored after its contents.
952 This is a deprecated synonym for @samp{-depth}, for compatibility with
953 Mac OS X, FreeBSD and OpenBSD. The @samp{-depth} option is a POSIX
954 feature, so it is better to use that.
958 If the file is a directory, do not descend into it. The result is
959 true. For example, to skip the directory @file{src/emacs} and all
960 files and directories under it, and print the names of the other files
964 find . -wholename './src/emacs' -prune -o -print
967 The above command will not print @file{./src/emacs} among its list of
968 results. This however is not due to the effect of the @samp{-prune}
969 action (which only prevents further descent, it doesn't make sure we
970 ignore that item). Instead, this effect is due to the use of
971 @samp{-o}. Since the left hand side of the ``or'' condition has
972 succeeded for @file{./src/emacs}, it is not necessary to evaluate the
973 right-hand-side (@samp{-print}) at all for this particular file. If
974 you wanted to print that directory name you could use either an extra
975 @samp{-print} action:
978 find . -wholename './src/emacs' -prune -print -o -print
981 or use the comma operator:
984 find . -wholename './src/emacs' -prune , -print
987 If the @samp{-depth} option is in effect, the subdirectories will have
988 already been visited in any case. Hence @samp{-prune} has no effect
994 Exit immediately with return value zero. No child processes will be
995 left running, but no more paths specified on the command line will be
996 processed. For example, @code{find /tmp/foo /tmp/bar -print -quit}
997 will print only @samp{/tmp/foo}.
1000 @deffn Option -noleaf
1001 Do not optimize by assuming that directories contain 2 fewer
1002 subdirectories than their hard link count. This option is needed when
1003 searching filesystems that do not follow the Unix directory-link
1004 convention, such as CD-ROM or MS-DOS filesystems or AFS volume mount
1005 points. Each directory on a normal Unix filesystem has at least 2 hard
1006 links: its name and its @file{.} entry. Additionally, its
1007 subdirectories (if any) each have a @file{..} entry linked to that
1008 directory. When @code{find} is examining a directory, after it has
1009 statted 2 fewer subdirectories than the directory's link count, it knows
1010 that the rest of the entries in the directory are non-directories
1011 (@dfn{leaf} files in the directory tree). If only the files' names need
1012 to be examined, there is no need to stat them; this gives a significant
1013 increase in search speed.
1016 @deffn Option -ignore_readdir_race
1017 If a file disappears after its name has been read from a directory but
1018 before @code{find} gets around to examining the file with @code{stat},
1019 don't issue an error message. If you don't specify this option, an
1020 error message will be issued. This option can be useful in system
1021 scripts (cron scripts, for example) that examine areas of the
1022 filesystem that change frequently (mail queues, temporary directories,
1023 and so forth), because this scenario is common for those sorts of
1024 directories. Completely silencing error messages from @code{find} is
1025 undesirable, so this option neatly solves the problem. There is no
1026 way to search one part of the filesystem with this option on and part
1027 of it with this option off, though.
1030 @deffn Option -noignore_readdir_race
1031 This option reverses the effect of the @samp{-ignore_readdir_race} option.
1036 @section Filesystems
1038 A @dfn{filesystem} is a section of a disk, either on the local host or
1039 mounted from a remote host over a network. Searching network
1040 filesystems can be slow, so it is common to make @code{find} avoid them.
1042 There are two ways to avoid searching certain filesystems. One way is
1043 to tell @code{find} to only search one filesystem:
1046 @deffnx Option -mount
1047 Don't descend directories on other filesystems. These options are synonyms.
1050 The other way is to check the type of filesystem each file is on, and
1051 not descend directories that are on undesirable filesystem types:
1053 @deffn Test -fstype type
1054 True if the file is on a filesystem of type @var{type}. The valid
1055 filesystem types vary among different versions of Unix; an incomplete
1056 list of filesystem types that are accepted on some version of Unix or
1059 ext2 ext3 proc sysfs ufs 4.2 4.3 nfs tmp mfs S51K S52K
1061 You can use @samp{-printf} with the @samp{%F} directive to see the types
1062 of your filesystems. The @samp{%D} directive shows the device number.
1063 @xref{Print File Information}. @samp{-fstype} is
1064 usually used with @samp{-prune} to avoid searching remote filesystems
1065 (@pxref{Directories}).
1068 @node Combining Primaries With Operators
1069 @section Combining Primaries With Operators
1071 Operators build a complex expression from tests and actions.
1072 The operators are, in order of decreasing precedence:
1075 @item @asis{( @var{expr} )}
1077 Force precedence. True if @var{expr} is true.
1079 @item @asis{! @var{expr}}
1080 @itemx @asis{-not @var{expr}}
1083 True if @var{expr} is false.
1085 @item @asis{@var{expr1 expr2}}
1086 @itemx @asis{@var{expr1} -a @var{expr2}}
1087 @itemx @asis{@var{expr1} -and @var{expr2}}
1090 And; @var{expr2} is not evaluated if @var{expr1} is false.
1092 @item @asis{@var{expr1} -o @var{expr2}}
1093 @itemx @asis{@var{expr1} -or @var{expr2}}
1096 Or; @var{expr2} is not evaluated if @var{expr1} is true.
1098 @item @asis{@var{expr1} , @var{expr2}}
1100 List; both @var{expr1} and @var{expr2} are always evaluated. True if
1101 @var{expr2} is true. The value of @var{expr1} is discarded. This
1102 operator lets you do multiple independent operations on one traversal,
1103 without depending on whether other operations succeeded. The two
1104 operations @var{expr1} and @var{expr2} are not always filly
1105 independent, since @var{expr1} might have side effects like touching
1106 or deleting files, or it might use @samp{-prune} which would also
1110 @code{find} searches the directory tree rooted at each file name by
1111 evaluating the expression from left to right, according to the rules of
1112 precedence, until the outcome is known (the left hand side is false for
1113 @samp{-and}, true for @samp{-or}), at which point @code{find} moves on
1114 to the next file name.
1116 There are two other tests that can be useful in complex expressions:
1126 @node Actions, Common Tasks, Finding Files, Top
1129 There are several ways you can print information about the files that
1130 match the criteria you gave in the @code{find} expression. You can
1131 print the information either to the standard output or to a file that
1132 you name. You can also execute commands that have the file names as
1133 arguments. You can use those commands as further filters to select files.
1137 * Print File Information::
1143 @node Print File Name
1144 @section Print File Name
1146 @deffn Action -print
1147 True; print the full file name on the standard output, followed by a
1151 @deffn Action -fprint file
1152 True; print the full file name into file @var{file}, followed by a
1153 newline. If @var{file} does not exist when @code{find} is run, it is
1154 created; if it does exist, it is truncated to 0 bytes. The file names
1155 @file{/dev/stdout} and @file{/dev/stderr} are handled specially; they
1156 refer to the standard output and standard error output, respectively.
1159 @node Print File Information
1160 @section Print File Information
1163 True; list the current file in @samp{ls -dils} format on the standard
1164 output. The output looks like this:
1167 204744 17 -rw-r--r-- 1 djm staff 17337 Nov 2 1992 ./lwall-quotes
1174 The inode number of the file. @xref{Hard Links}, for how to find files
1175 based on their inode number.
1178 the number of blocks in the file. The block counts are of 1K blocks,
1179 unless the environment variable @code{POSIXLY_CORRECT} is set, in which
1180 case 512-byte blocks are used. @xref{Size}, for how to find files based
1184 The file's type and permissions. The type is shown as a dash for a
1185 regular file; for other file types, a letter like for @samp{-type} is
1186 used (@pxref{Type}). The permissions are read, write, and execute for
1187 the file's owner, its group, and other users, respectively; a dash means
1188 the permission is not granted. @xref{File Permissions}, for more details
1189 about file permissions. @xref{Permissions}, for how to find files based
1190 on their permissions.
1193 The number of hard links to the file.
1196 The user who owns the file.
1202 The file's size in bytes.
1205 The date the file was last modified.
1208 The file's name. @samp{-ls} quotes non-printable characters in the file
1209 names using C-like backslash escapes.
1213 @deffn Action -fls file
1214 True; like @samp{-ls} but write to @var{file} like @samp{-fprint}
1215 (@pxref{Print File Name}).
1218 @deffn Action -printf format
1219 True; print @var{format} on the standard output, interpreting @samp{\}
1220 escapes and @samp{%} directives. Field widths and precisions can be
1221 specified as with the @code{printf} C function. Format flags (like
1222 @samp{#} for example) may not work as you expect because many of the
1223 fields, even numeric ones, are printed with %s. This means though
1224 that the format flag @samp{-} will work; it forces left-alignment of
1225 the field. Unlike @samp{-print}, @samp{-printf} does not add a
1226 newline at the end of the string. If you want a newline at the end of
1227 the string, add a @samp{\n}.
1230 @deffn Action -fprintf file format
1231 True; like @samp{-printf} but write to @var{file} like @samp{-fprint}
1232 (@pxref{Print File Name}).
1237 * Format Directives::
1244 The escapes that @samp{-printf} and @samp{-fprintf} recognize are:
1252 Stop printing from this format immediately and flush the output.
1264 A literal backslash (@samp{\}).
1266 The character whose ASCII code is NNN (octal).
1269 A @samp{\} character followed by any other character is treated as an
1270 ordinary character, so they both are printed, and a warning message is
1271 printed to the standard error output (because it was probably a typo).
1273 @node Format Directives
1274 @subsection Format Directives
1276 @samp{-printf} and @samp{-fprintf} support the following format
1277 directives to print information about the file being processed. The C
1278 @code{printf} function, field width and precision specifiers are
1279 supported, as applied to string (%s) types. That is, you can specify
1280 "minimum field width"."maximum field width" for each directive.
1281 Format flags (like @samp{#} for example) may not work as you expect
1282 because many of the fields, even numeric ones, are printed with %s.
1283 The format flag @samp{-} does work; it forces left-alignment of the
1286 @samp{%%} is a literal percent sign. A @samp{%} character followed by
1287 an unrecognised character (i.e. not a known directive or printf field
1288 width and precision specifier), is discarded (but the unrecognised character
1289 is printed), and a warning message is printed to the standard error output
1290 (because it was probably a typo).
1294 * Ownership Directives::
1296 * Location Directives::
1298 * Formatting Flags::
1301 @node Name Directives
1302 @subsubsection Name Directives
1307 File's name (not the absolute path name, but the name of the file as
1308 it was encountered by find - that is, as a relative path from one of
1309 the starting points).
1311 File's name with any leading directories removed (only the last element).
1314 Leading directories of file's name (all but the last element and the
1318 File's name with the name of the command line argument under which
1319 it was found removed from the beginning.
1322 Command line argument under which file was found.
1326 @node Ownership Directives
1327 @subsubsection Ownership Directives
1332 File's group name, or numeric group ID if the group has no name.
1335 @c TODO: Needs to support # flag and 0 flag
1336 File's numeric group ID.
1339 File's user name, or numeric user ID if the user has no name.
1342 @c TODO: Needs to support # flag
1343 File's numeric user ID.
1345 @c full support, including # and 0.
1346 File's permissions (in octal). If you always want to have a leading
1347 zero on the number, use the '#' format flag, for example '%#m'.
1350 @node Size Directives
1351 @subsubsection Size Directives
1355 Amount of disk space occupied by the file, measured in 1K blocks
1356 (rounded up). This can be less than the length of the file if
1357 it is a sparse file (that is, it has ``holes'').
1359 File's size in 512-byte blocks (rounded up). This also can be less
1360 than the length of the file, if the file is sparse.
1362 File's size in bytes.
1365 @node Location Directives
1366 @subsubsection Location Directives
1370 File's depth in the directory tree (depth below a file named on the
1371 command line, not depth below the root directory). Files named on the
1372 command line have a depth of 0. Subdirectories immediately below them
1373 have a depth of 1, and so on.
1375 The device number on which the file exists (the @code{st_dev} field of
1376 @code{struct stat}), in decimal.
1378 Type of the filesystem the file is on; this value can be used for
1379 @samp{-fstype} (@pxref{Directories}).
1381 Object of symbolic link (empty string if file is not a symbolic link).
1383 File's inode number (in decimal).
1385 Number of hard links to file.
1387 Type of the file as used with @samp{-type}. If the file is a symbolic
1388 link, @samp{l} will be printed.
1390 Type of the file as used with @samp{-type}. If the file is a symbolic
1391 link, it is dereferenced. If the file is a broken symbolic link,
1392 @samp{N} is printed.
1396 @node Time Directives
1397 @subsubsection Time Directives
1399 Some of these directives use the C @code{ctime} function. Its output
1400 depends on the current locale, but it typically looks like
1403 Wed Nov 2 00:42:36 1994
1408 File's last access time in the format returned by the C @code{ctime} function.
1410 File's last access time in the format specified by @var{k}
1411 (@pxref{Time Formats}).
1413 File's last status change time in the format returned by the C @code{ctime}
1416 File's last status change time in the format specified by @var{k}
1417 (@pxref{Time Formats}).
1419 File's last modification time in the format returned by the C @code{ctime}
1422 File's last modification time in the format specified by @var{k}
1423 (@pxref{Time Formats}).
1427 @subsection Time Formats
1429 Below are the formats for the directives @samp{%A}, @samp{%C}, and
1430 @samp{%T}, which print the file's timestamps. Some of these formats
1431 might not be available on all systems, due to differences in the C
1432 @code{strftime} function between systems.
1437 * Combined Time Formats::
1440 @node Time Components
1441 @subsubsection Time Components
1443 The following format directives print single components of the time.
1457 time zone (e.g., EDT), or nothing if no time zone is determinable
1463 seconds since Jan. 1, 1970, 00:00 GMT.
1466 @node Date Components
1467 @subsubsection Date Components
1469 The following format directives print single components of the date.
1473 locale's abbreviated weekday name (Sun..Sat)
1475 locale's full weekday name, variable length (Sunday..Saturday)
1478 locale's abbreviated month name (Jan..Dec)
1480 locale's full month name, variable length (January..December)
1484 day of month (01..31)
1488 day of year (001..366)
1490 week number of year with Sunday as first day of week (00..53)
1492 week number of year with Monday as first day of week (00..53)
1496 last two digits of year (00..99)
1499 @node Combined Time Formats
1500 @subsubsection Combined Time Formats
1502 The following format directives print combinations of time and date
1507 time, 12-hour (hh:mm:ss [AP]M)
1509 time, 24-hour (hh:mm:ss)
1511 locale's time representation (H:M:S)
1513 locale's date and time (Sat Nov 04 12:02:33 EST 1989)
1517 locale's date representation (mm/dd/yy)
1519 Date and time, separated by '+', for example `2004-04-28+22:22:05'.
1520 The time is given in the current timezone (which may be affected by
1521 setting the TZ environment variable). This is a GNU extension.
1524 @node Formatting Flags
1525 @subsubsection Formatting Flags
1527 The @samp{%m} and @samp{%d} directives support the @samp{#}, @samp{0}
1528 and @samp{+} flags, but the other directives do not, even if they
1529 print numbers. Numeric directives that do not support these flags
1539 All fields support the format flag @samp{-}, which makes fields
1540 left-aligned. That is, if the field width is greater than the actual
1541 contents of the field, the requisite number of spaces are printed
1542 after the field content instead of before it.
1545 @section Run Commands
1547 You can use the list of file names created by @code{find} or
1548 @code{locate} as arguments to other commands. In this way you can
1549 perform arbitrary actions on the files.
1558 @subsection Single File
1560 Here is how to run a command on one file at a time.
1562 @deffn Action -exec command ;
1563 Execute @var{command}; true if 0 status is returned. @code{find} takes
1564 all arguments after @samp{-exec} to be part of the command until an
1565 argument consisting of @samp{;} is reached. It replaces the string
1566 @samp{@{@}} by the current file name being processed everywhere it
1567 occurs in the command. Both of these constructions need to be escaped
1568 (with a @samp{\}) or quoted to protect them from expansion by the shell.
1569 The command is executed in the directory in which @code{find} was run.
1571 For example, to compare each C header file in the current directory with
1572 the file @file{/tmp/master}:
1575 find . -name '*.h' -exec diff -u '@{@}' /tmp/master ';'
1580 @deffn Action -exec command +
1581 This variant of @samp{-exec} not yet supported. Once it has been
1582 implemented as specified in the POSIX standard, a @samp{@{@}} will expand to
1583 a list of names of matching files. This expansion is done in such a
1584 way as to avoid exceeding the maximum command line length available on
1589 @node Multiple Files
1590 @subsection Multiple Files
1592 Sometimes you need to process files alone. But when you
1593 don't, it is faster to run a command on as many files as possible at a
1594 time, rather than once per file. Doing this saves on the time it takes
1595 to start up the command each time.
1597 To run a command on more than one file at once, use the @code{xargs}
1598 command, which is invoked like this:
1601 xargs @r{[}@var{option}@dots{}@r{]} @r{[}@var{command} @r{[}@var{initial-arguments}@r{]}@r{]}
1604 @code{xargs} normally reads arguments from the standard input. These
1605 arguments are delimited by blanks (which can be protected with double
1606 or single quotes or a backslash) or newlines. It executes the
1607 @var{command} (default is @file{/bin/echo}) one or more times with any
1608 @var{initial-arguments} followed by arguments read from standard
1609 input. Blank lines on the standard input are ignored.
1611 Instead of blank-delimited names, it is safer to use @samp{find -print0}
1612 or @samp{find -fprint0} and process the output by giving the @samp{-0}
1613 or @samp{--null} option to GNU @code{xargs}, GNU @code{tar}, GNU
1614 @code{cpio}, or @code{perl}. The @code{locate} command also has a
1615 @samp{-0} or @samp{--null} option which does the same thing.
1617 You can use shell command substitution (backquotes) to process a list of
1618 arguments, like this:
1621 grep -l sprintf `find $HOME -name '*.c' -print`
1624 However, that method produces an error if the length of the @samp{.c}
1625 file names exceeds the operating system's command-line length limit.
1626 @code{xargs} avoids that problem by running the command as many times as
1627 necessary without exceeding the limit:
1630 find $HOME -name '*.c' -print | xargs grep -l sprintf
1633 However, if the command needs to have its standard input be a terminal
1634 (@code{less}, for example), you have to use the shell command
1635 substitution method or use the @samp{--arg-file} option of
1638 The @code{xargs} command will process all its input, building command
1639 lines and executing them, unless one of the commands exits with a
1640 status of 255 (this will cause xargs to issue an error message and
1641 stop) or it reads a line contains the end of file string specified
1642 with the @samp{--eof} option.
1645 * Unsafe File Name Handling::
1646 * Safe File Name Handling::
1647 * Limiting Command Size::
1648 * Interspersing File Names::
1651 @node Unsafe File Name Handling
1652 @subsubsection Unsafe File Name Handling
1654 Because file names can contain quotes, backslashes, blank characters,
1655 and even newlines, it is not safe to process them using @code{xargs} in its
1656 default mode of operation. But since most files' names do not contain
1657 blanks, this problem occurs only infrequently. If you are only
1658 searching through files that you know have safe names, then you need not
1659 be concerned about it.
1661 @c This example is adapted from:
1662 @c From: pfalstad@stone.Princeton.EDU (Paul John Falstad)
1663 @c Newsgroups: comp.unix.shell
1664 @c Subject: Re: Beware xargs security holes
1665 @c Date: 16 Oct 90 19:12:06 GMT
1667 In many applications, if @code{xargs} botches processing a file because
1668 its name contains special characters, some data might be lost. The
1669 importance of this problem depends on the importance of the data and
1670 whether anyone notices the loss soon enough to correct it. However,
1671 here is an extreme example of the problems that using blank-delimited
1672 names can cause. If the following command is run daily from
1673 @code{cron}, then any user can remove any file on the system:
1676 find / -name '#*' -atime +7 -print | xargs rm
1679 For example, you could do something like this:
1687 and then @code{cron} would delete @file{/vmunix}, if it ran
1688 @code{xargs} with @file{/} as its current directory.
1690 To delete other files, for example @file{/u/joeuser/.plan}, you could do
1698 eg$ mkdir u u/joeuser u/joeuser/.plan'
1700 eg$ echo > u/joeuser/.plan'
1703 eg$ find . -name '#*' -print | xargs echo
1704 ./# ./# /u/joeuser/.plan /#foo
1707 @node Safe File Name Handling
1708 @subsubsection Safe File Name Handling
1710 Here is how to make @code{find} output file names so that they can be
1711 used by other programs without being mangled or misinterpreted. You can
1712 process file names generated this way by giving the @samp{-0} or
1713 @samp{--null} option to GNU @code{xargs}, GNU @code{tar}, GNU
1714 @code{cpio}, or @code{perl}.
1716 @deffn Action -print0
1717 True; print the full file name on the standard output, followed by a
1721 @deffn Action -fprint0 file
1722 True; like @samp{-print0} but write to @var{file} like @samp{-fprint}
1723 (@pxref{Print File Name}).
1726 As of findutils version 4.2.4, the @code{locate} program also has a
1727 @samp{--null} option which does the same thing. For similarity with
1728 @code{xargs}, the short form of the option @samp{-0} can also be used.
1730 If you want to be able to handle file names safely but need to run
1731 commands which want to be connected to a terminal on their input, you
1732 can use the @samp{--arg-file} option to @code{xargs} like this:
1735 find / -name xyzzy -print0 > list
1736 xargs --null --arg-file=list munge
1739 The example above runs the @code{munge} program on all the files named
1740 @file{xyzzy} that we can find, but @code{munge}'s input will still be
1741 the terminal (or whatever the shell was using as standard input). If
1742 your shell has the ``process substitution'' feature @samp{<(...)}, you
1743 can do this in just one step:
1746 xargs --null --arg-file=<(find / -name xyzzy -print0) munge
1749 @node Limiting Command Size
1750 @subsubsection Limiting Command Size
1752 @code{xargs} gives you control over how many arguments it passes to the
1753 command each time it executes it. By default, it uses up to
1754 @code{ARG_MAX} - 2k, or 128k, whichever is smaller, characters per
1755 command. It uses as many lines and arguments as fit within that limit.
1756 The following options modify those values.
1759 @item --no-run-if-empty
1761 If the standard input does not contain any nonblanks, do not run the
1762 command. By default, the command is run once even if there is no input.
1764 @item --max-lines@r{[}=@var{max-lines}@r{]}
1765 @itemx -l@r{[}@var{max-lines}@r{]}
1766 Use at most @var{max-lines} nonblank input lines per command line;
1767 @var{max-lines} defaults to 1 if omitted. Trailing blanks cause an
1768 input line to be logically continued on the next input line, for the
1769 purpose of counting the lines. Implies @samp{-x}.
1771 @item --max-args=@var{max-args}
1772 @itemx -n @var{max-args}
1773 Use at most @var{max-args} arguments per command line. Fewer than
1774 @var{max-args} arguments will be used if the size (see the @samp{-s}
1775 option) is exceeded, unless the @samp{-x} option is given, in which case
1776 @code{xargs} will exit.
1778 @item --max-chars=@var{max-chars}
1779 @itemx -s @var{max-chars}
1780 Use at most @var{max-chars} characters per command line, including the
1781 command and initial arguments and the terminating nulls at the ends of
1782 the argument strings. If you specify a value for this option which is
1783 too large or small, a warning message is printed and the appropriate
1784 upper or lower limit is used instead.
1786 @item --max-procs=@var{max-procs}
1787 @itemx -P @var{max-procs}
1788 Run up to @var{max-procs} processes at a time; the default is 1. If
1789 @var{max-procs} is 0, @code{xargs} will run as many processes as
1790 possible at a time. Use the @samp{-n}, @samp{-s}, or @samp{-l} option
1791 with @samp{-P}; otherwise chances are that the command will be run only
1795 @node Interspersing File Names
1796 @subsubsection Interspersing File Names
1798 @code{xargs} can insert the name of the file it is processing between
1799 arguments you give for the command. Unless you also give options to
1800 limit the command size (@pxref{Limiting Command Size}), this mode of
1801 operation is equivalent to @samp{find -exec} (@pxref{Single File}).
1804 @item --replace@r{[}=@var{replace-str}@r{]}
1805 @itemx -i@r{[}@var{replace-str}@r{]}
1806 Replace occurrences of @var{replace-str} in the initial arguments with
1807 names read from the input. Also, unquoted blanks do not
1808 terminate arguments; instead, the input is split at newlines only. If
1809 @var{replace-str} is omitted, it defaults to @samp{@{@}} (like for
1810 @samp{find -exec}). Implies @samp{-x} and @samp{-l 1}. As an
1811 example, to sort each file the @file{bills} directory, leaving the
1812 output in that file name with @file{.sorted} appended, you could do:
1815 find bills -type f | xargs -iXX sort -o XX.sorted XX
1819 The equivalent command using @samp{find -exec} is:
1822 find bills -type f -exec sort -o '@{@}.sorted' '@{@}' ';'
1827 @subsection Querying
1829 To ask the user whether to execute a command on a single file, you can
1830 use the @code{find} primary @samp{-ok} instead of @samp{-exec}:
1832 @deffn Action -ok command ;
1833 Like @samp{-exec} (@pxref{Single File}), but ask the user first (on
1834 the standard input); if the response does not start with @samp{y} or
1835 @samp{Y}, do not run the command, and return false.
1838 When processing multiple files with a single command, to query the user
1839 you give @code{xargs} the following option. When using this option, you
1840 might find it useful to control the number of files processed per
1841 invocation of the command (@pxref{Limiting Command Size}).
1846 Prompt the user about whether to run each command line and read a line
1847 from the terminal. Only run the command line if the response starts
1848 with @samp{y} or @samp{Y}. Implies @samp{-t}.
1852 @section Delete Files
1854 @deffn Action -delete
1855 Delete files or directories; true if removal succeeded. If the
1856 removal failed, an error message is issued.
1858 The use of the @samp{-delete} action on the command line automatically
1859 turns on the @samp{-depth} option (@pxref{find Expressions}).
1863 @section Adding Tests
1865 You can test for file attributes that none of the @code{find} builtin
1866 tests check. To do this, use @code{xargs} to run a program that filters
1867 a list of files printed by @code{find}. If possible, use @code{find}
1868 builtin tests to pare down the list, so the program run by @code{xargs}
1869 has less work to do. The tests builtin to @code{find} will likely run
1870 faster than tests that other programs perform.
1872 For example, here is a way to print the names of all of the unstripped
1873 binaries in the @file{/usr/local} directory tree. Builtin tests avoid
1874 running @code{file} on files that are not regular files or are not
1878 find /usr/local -type f -perm +a=x | xargs file |
1879 grep 'not stripped' | cut -d: -f1
1883 The @code{cut} program removes everything after the file name from the
1884 output of @code{file}.
1886 @c Idea from Martin Weitzel.
1887 If you want to place a special test somewhere in the middle of a
1888 @code{find} expression, you can use @samp{-exec} to run a program that
1889 performs the test. Because @samp{-exec} evaluates to the exit status of
1890 the executed program, you can write a program (which can be a shell
1891 script) that tests for a special attribute and make it exit with a true
1892 (zero) or false (non-zero) status. It is a good idea to place such a
1893 special test @emph{after} the builtin tests, because it starts a new
1894 process which could be avoided if a builtin test evaluates to false.
1895 Use this method only when @code{xargs} is not flexible enough, because
1896 starting one or more new processes to test each file is slower than
1897 using @code{xargs} to start one process that tests many files.
1899 Here is a shell script called @code{unstripped} that checks whether its
1900 argument is an unstripped binary file:
1904 file $1 | grep 'not stripped' > /dev/null
1907 This script relies on the fact that the shell exits with the status of
1908 the last program it executed, in this case @code{grep}. @code{grep}
1909 exits with a true status if it found any matches, false if not. Here is
1910 an example of using the script (assuming it is in your search path). It
1911 lists the stripped executables in the file @file{sbins} and the
1912 unstripped ones in @file{ubins}.
1915 find /usr/local -type f -perm +a=x \
1916 \( -exec unstripped '@{@}' \; -fprint ubins -o -fprint sbins \)
1919 @node Common Tasks, Databases, Actions, Top
1920 @chapter Common Tasks
1922 The sections that follow contain some extended examples that both give a
1923 good idea of the power of these programs, and show you how to solve
1924 common real-world problems.
1927 * Viewing And Editing::
1930 * Strange File Names::
1931 * Fixing Permissions::
1932 * Classifying Files::
1935 @node Viewing And Editing
1936 @section Viewing And Editing
1938 To view a list of files that meet certain criteria, simply run your file
1939 viewing program with the file names as arguments. Shells substitute a
1940 command enclosed in backquotes with its output, so the whole command
1944 less `find /usr/include -name '*.h' | xargs grep -l mode_t`
1948 You can edit those files by giving an editor name instead of a file
1952 emacs `find /usr/include -name '*.h' | xargs grep -l mode_t`
1955 Because there is a limit to the length of any individual command line,
1956 there is a limit to the number of files that can be handled in this
1957 way. We can get around this difficulty by using xargs like this:
1960 find /usr/include -name '*.h' | xargs grep -l mode_t > todo
1961 xargs --arg-file=todo emacs
1964 Here, @code{xargs} will run @code{emacs} as many times as necessary to
1965 visit all of the files listed in the file @file{todo}.
1970 You can pass a list of files produced by @code{find} to a file archiving
1971 program. GNU @code{tar} and @code{cpio} can both read lists of file
1972 names from the standard input---either delimited by nulls (the safe way)
1973 or by blanks (the lazy, risky default way). To use null-delimited
1974 names, give them the @samp{--null} option. You can store a file archive
1975 in a file, write it on a tape, or send it over a network to extract on
1978 One common use of @code{find} to archive files is to send a list of the
1979 files in a directory tree to @code{cpio}. Use @samp{-depth} so if a
1980 directory does not have write permission for its owner, its contents can
1981 still be restored from the archive since the directory's permissions are
1982 restored after its contents. Here is an example of doing this using
1983 @code{cpio}; you could use a more complex @code{find} expression to
1984 archive only certain files.
1987 find . -depth -print0 |
1988 cpio --create --null --format=crc --file=/dev/nrst0
1991 You could restore that archive using this command:
1994 cpio --extract --null --make-dir --unconditional \
1995 --preserve --file=/dev/nrst0
1998 Here are the commands to do the same things using @code{tar}:
2001 find . -depth -print0 |
2002 tar --create --null --files-from=- --file=/dev/nrst0
2004 tar --extract --null --preserve-perm --same-owner \
2008 @c Idea from Rick Sladkey.
2009 Here is an example of copying a directory from one machine to another:
2012 find . -depth -print0 | cpio -0o -Hnewc |
2013 rsh @var{other-machine} "cd `pwd` && cpio -i0dum"
2017 @section Cleaning Up
2019 @c Idea from Jim Meyering.
2020 This section gives examples of removing unwanted files in various situations.
2021 Here is a command to remove the CVS backup files created when an update
2025 find . -name '.#*' -print0 | xargs -0r rm -f
2028 The command above works, but the following is safer:
2031 find . -name '.#*' -depth -delete
2034 @c Idea from Franc,ois Pinard.
2035 You can run this command to clean out your clutter in @file{/tmp}. You
2036 might place it in the file your shell runs when you log out
2037 (@file{.bash_logout}, @file{.logout}, or @file{.zlogout}, depending on
2038 which shell you use).
2041 find /tmp -depth -user "$LOGNAME" -type f -delete
2044 If your @code{find} command removes directories, you may find that
2045 you get a spurious error message when @code{find} tries to recurse
2046 into a directory that has now been removed. Using the @samp{-depth}
2047 option will normally resolve this problem.
2049 @c Idea from Noah Friedman.
2050 To remove old Emacs backup and auto-save files, you can use a command
2051 like the following. It is especially important in this case to use
2052 null-terminated file names because Emacs packages like the VM mailer
2053 often create temporary file names with spaces in them, like @file{#reply
2054 to David J. MacKenzie<1>#}.
2057 find ~ \( -name '*~' -o -name '#*#' \) -print0 |
2058 xargs --no-run-if-empty --null rm -vf
2061 Removing old files from @file{/tmp} is commonly done from @code{cron}:
2063 @c Idea from Kaveh Ghazi.
2065 find /tmp /var/tmp -not -type d -mtime +3 -delete
2066 find /tmp /var/tmp -depth -mindepth 1 -type d -empty -delete
2069 The second @code{find} command above uses @samp{-depth} so it cleans out
2070 empty directories depth-first, hoping that the parents become empty and
2071 can be removed too. It uses @samp{-mindepth} to avoid removing
2072 @file{/tmp} itself if it becomes totally empty.
2074 @node Strange File Names
2075 @section Strange File Names
2078 @c From: tmatimar@isgtec.com (Ted Timar)
2079 @c Newsgroups: comp.unix.questions,comp.unix.shell,comp.answers,news.answers
2080 @c Subject: Unix - Frequently Asked Questions (2/7) [Frequent posting]
2081 @c Subject: How do I remove a file with funny characters in the filename ?
2082 @c Date: Thu Mar 18 17:16:55 EST 1993
2083 @code{find} can help you remove or rename a file with strange characters
2084 in its name. People are sometimes stymied by files whose names contain
2085 characters such as spaces, tabs, control characters, or characters with
2086 the high bit set. The simplest way to remove such files is:
2089 rm -i @var{some*pattern*that*matches*the*problem*file}
2092 @code{rm} asks you whether to remove each file matching the given
2093 pattern. If you are using an old shell, this approach might not work if
2094 the file name contains a character with the high bit set; the shell may
2095 strip it off. A more reliable way is:
2098 find . -maxdepth 1 @var{tests} -ok rm '@{@}' \;
2102 where @var{tests} uniquely identify the file. The @samp{-maxdepth 1}
2103 option prevents @code{find} from wasting time searching for the file in
2104 any subdirectories; if there are no subdirectories, you may omit it. A
2105 good way to uniquely identify the problem file is to figure out its
2112 Suppose you have a file whose name contains control characters, and you
2113 have found that its inode number is 12345. This command prompts you for
2114 whether to remove it:
2117 find . -maxdepth 1 -inum 12345 -ok rm -f '@{@}' \;
2120 If you don't want to be asked, perhaps because the file name may contain
2121 a strange character sequence that will mess up your screen when printed,
2122 then use @samp{-exec} instead of @samp{-ok}.
2124 If you want to rename the file instead, you can use @code{mv} instead of
2128 find . -maxdepth 1 -inum 12345 -ok mv '@{@}' @var{new-file-name} \;
2131 @node Fixing Permissions
2132 @section Fixing Permissions
2134 Suppose you want to make sure that everyone can write to the directories in a
2135 certain directory tree. Here is a way to find directories lacking either
2136 user or group write permission (or both), and fix their permissions:
2139 find . -type d -not -perm -ug=w | xargs chmod ug+w
2143 You could also reverse the operations, if you want to make sure that
2144 directories do @emph{not} have world write permission.
2146 @node Classifying Files
2147 @section Classifying Files
2150 @c From: martin@mwtech.UUCP (Martin Weitzel)
2151 @c Newsgroups: comp.unix.wizards,comp.unix.questions
2152 @c Subject: Advanced usage of 'find' (Re: Unix security automating script)
2153 @c Date: 22 Mar 90 15:05:19 GMT
2154 If you want to classify a set of files into several groups based on
2155 different criteria, you can use the comma operator to perform multiple
2156 independent tests on the files. Here is an example:
2159 find / -type d \( -perm -o=w -fprint allwrite , \
2160 -perm -o=x -fprint allexec \)
2162 echo "Directories that can be written to by everyone:"
2165 echo "Directories with search permissions for everyone:"
2169 @code{find} has only to make one scan through the directory tree (which
2170 is one of the most time consuming parts of its work).
2172 @node Databases, File Permissions, Common Tasks, Top
2173 @chapter File Name Databases
2175 The file name databases used by @code{locate} contain lists of files
2176 that were in particular directory trees when the databases were last
2177 updated. The file name of the default database is determined when
2178 @code{locate} and @code{updatedb} are configured and installed. The
2179 frequency with which the databases are updated and the directories for
2180 which they contain entries depend on how often @code{updatedb} is run,
2181 and with which arguments.
2183 You can obtain some statistics about the databases by using
2184 @samp{locate --statistics}.
2187 * Database Locations::
2188 * Database Formats::
2189 * Newline Handling::
2193 @node Database Locations
2194 @section Database Locations
2196 There can be multiple file name databases. Users can select which
2197 databases @code{locate} searches using the @code{LOCATE_PATH}
2198 environment variable or a command line option. The system
2199 administrator can choose the file name of the default database, the
2200 frequency with which the databases are updated, and the directories
2201 for which they contain entries. File name databases are updated by
2202 running the @code{updatedb} program, typically nightly.
2204 In networked environments, it often makes sense to build a database at
2205 the root of each filesystem, containing the entries for that filesystem.
2206 @code{updatedb} is then run for each filesystem on the fileserver where
2207 that filesystem is on a local disk, to prevent thrashing the network.
2209 @xref{Invoking updatedb},
2210 for the description of the options to @code{updatedb}, which specify
2211 which directories would each database contain entries for.
2214 @node Database Formats
2215 @section Database Formats
2217 The file name databases contain lists of files that were in particular
2218 directory trees when the databases were last updated. The file name
2219 database format changed starting with GNU @code{locate} version 4.0 to
2220 allow machines with different byte orderings to share the databases. The
2221 new GNU @code{locate} can read both the old and new database formats.
2222 However, old versions of @code{locate} and @code{find} produce incorrect
2223 results if given a new-format database.
2225 If you run @samp{locate --statistics}, the resulting summary indicates
2226 the type of each locate database.
2230 * New Database Format::
2232 * Old Database Format::
2235 @node New Database Format
2236 @subsection New Database Format
2238 @code{updatedb} runs a program called @code{frcode} to
2239 @dfn{front-compress} the list of file names, which reduces the database
2240 size by a factor of 4 to 5. Front-compression (also known as
2241 incremental encoding) works as follows.
2243 The database entries are a sorted list (case-insensitively, for users'
2244 convenience). Since the list is sorted, each entry is likely to share a
2245 prefix (initial string) with the previous entry. Each database entry
2246 begins with an offset-differential count byte, which is the additional
2247 number of characters of prefix of the preceding entry to use beyond the
2248 number that the preceding entry is using of its predecessor. (The
2249 counts can be negative.) Following the count is a null-terminated ASCII
2250 remainder---the part of the name that follows the shared prefix.
2252 If the offset-differential count is larger than can be stored in a byte
2253 (+/-127), the byte has the value 0x80 and the count follows in a 2-byte
2254 word, with the high byte first (network byte order).
2256 Every database begins with a dummy entry for a file called
2257 @file{LOCATE02}, which @code{locate} checks for to ensure that the
2258 database file has the correct format; it ignores the entry in doing the
2261 Databases can not be concatenated together, even if the first (dummy)
2262 entry is trimmed from all but the first database. This is because the
2263 offset-differential count in the first entry of the second and following
2264 databases will be wrong.
2266 In the output of @samp{locate --statistics}, the new database format
2267 is referred to as @samp{LOCATE02}.
2269 @node Sample Database
2270 @subsection Sample Database
2272 Sample input to @code{frcode}:
2273 @c with nulls changed to newlines:
2277 /usr/src/cmd/aardvark.c
2278 /usr/src/cmd/armadillo.c
2282 Length of the longest prefix of the preceding entry to share:
2291 Output from @code{frcode}, with trailing nulls changed to newlines
2292 and count bytes made printable:
2302 (6 = 14 - 8, and -9 = 5 - 14)
2304 @node Old Database Format
2305 @subsection Old Database Format
2307 The old database format is used by Unix @code{locate} and @code{find}
2308 programs and earlier releases of the GNU ones. @code{updatedb} produces
2309 this format if given the @samp{--old-format} option.
2311 @code{updatedb} runs programs called @code{bigram} and @code{code} to
2312 produce old-format databases. The old format differs from the new one
2313 in the following ways. Instead of each entry starting with an
2314 offset-differential count byte and ending with a null, byte values from
2315 0 through 28 indicate offset-differential counts from -14 through 14.
2316 The byte value indicating that a long offset-differential count follows
2317 is 0x1e (30), not 0x80. The long counts are stored in host byte order,
2318 which is not necessarily network byte order, and host integer word size,
2319 which is usually 4 bytes. They also represent a count 14 less than
2320 their value. The database lines have no termination byte; the start of
2321 the next line is indicated by its first byte having a value <= 30.
2323 In addition, instead of starting with a dummy entry, the old database
2324 format starts with a 256 byte table containing the 128 most common
2325 bigrams in the file list. A bigram is a pair of adjacent bytes. Bytes
2326 in the database that have the high bit set are indexes (with the high
2327 bit cleared) into the bigram table. The bigram and offset-differential
2328 count coding makes these databases 20-25% smaller than the new format,
2329 but makes them not 8-bit clean. Any byte in a file name that is in the
2330 ranges used for the special codes is replaced in the database by a
2331 question mark, which not coincidentally is the shell wildcard to match a
2334 The old format therefore can not faithfully store entries with non-ASCII
2335 characters. It therefore should not be used in internationalized
2338 The output of @samp{locate --statistics} will give an incorrect count
2339 of the number of filenames containing newlines or high-bit characters
2340 for old-format databases.
2342 @node Newline Handling
2343 @section Newline Handling
2345 Within the database, filenames are terminated with a null character.
2346 This is the case for both the old and the new format.
2348 When the new database format is being used, the compression technique
2349 used to generate the database though relies on the ability to sort the
2350 list of files before they are presented to @code{frcode}.
2352 If the system's sort command allows its input list of files to be
2353 separated with null characters via the @samp{-z} option, this option
2354 is used and therefore @code{updatedb} and @code{locate} will both
2355 correctly handle filenames containing newlines. If the @code{sort}
2356 command lacks support for this, the list of files is delimited with
2357 the newline character, meaning that parts of filenames containing
2358 newlines will be incorrectly sorted. This can result in both
2359 incorrect matches and incorrect failures to match.
2361 On the other hand, if you are using the old database format, filenames
2362 with embedded newlines are not correctly handled. There is no
2363 technical limitation which enforces this, it's just that the
2364 @code{bigram} program has no been updated to support lists of
2365 filenames separated by nulls.
2367 So, if you are using the new database format (this is the default) and
2368 your system uses GNU @code{find}, newlines will be correctly handled
2369 at all times. Otherwise, newlines may not be correctly handled.
2371 @node File Permissions, Reference, Databases, Top
2372 @chapter File Permissions
2376 @node Reference, Security Considerations, File Permissions, Top
2379 Below are summaries of the command line syntax for the programs
2380 discussed in this manual.
2385 * Invoking updatedb::
2389 @node Invoking find, Invoking locate, , Reference
2390 @section Invoking @code{find}
2393 find @r{[-H] [-L] [-P]} @r{[}@var{file}@dots{}@r{]} @r{[}@var{expression}@r{]}
2396 @code{find} searches the directory tree rooted at each file name
2397 @var{file} by evaluating the @var{expression} on each file it finds in
2400 The options @samp{-H}, @samp{-L} or @samp{-P} may be specified at the
2401 start of the command line (if none of these is specified, @samp{-P} is
2402 assumed). The arguments after these are a list of files or
2403 directories that should be searched.
2405 This list of files to search is followed by a list of expressions
2406 describing the files we wish to search for. The first part of the
2407 expression is recognised by the fact that it begins with @samp{-},
2408 @samp{(}, @samp{)}, @samp{,}, or @samp{!}. Any arguments after it are
2409 the rest of the expression. If no paths are given, the current
2410 directory is used. If no expression is given, the expression
2411 @samp{-print} is used.
2413 @code{find} exits with status 0 if all files are processed successfully,
2414 greater than 0 if errors occur.
2416 Three options can precede the list of path names. They determine the
2417 way that symbolic links are handled.
2421 Never follow symbolic links (this is the default), except in the case
2422 of the @samp{-xtype} predicate.
2424 Always follow symbolic links, except in the case of the @samp{-xtype}
2427 Follow symbolic links specified in the list of paths to search, or
2428 which are otherwise specified on the command line.
2431 If @code{find} would follow a symbolic link, but cannot for any reason
2432 (for example, because it has insufficient permissions or the link is
2433 broken), it falls back on using the properties of the symbolic link
2434 itself. @ref{Symbolic Links} for a more complete description of how
2435 symbolic links are handled.
2437 @xref{Primary Index}, for a summary of all of the tests, actions, and
2438 options that the expression can contain. If the expression is
2439 missing, @samp{-print} is assumed.
2443 @code{find} also recognizes two options for administrative use:
2447 Print a summary of the command-line argument format and exit.
2449 Print the version number of @code{find} and exit.
2454 * Warning Messages::
2458 @node Warning Messages,,, Invoking find
2459 @subsection Warning Messages
2461 If there is an error on the @code{find} command line, an error message
2462 is normally issued. However, there are some usages that are
2463 inadvisable but which @code{find} should still accept. Under these
2464 circumstances, @code{find} may issue a warning message. By default,
2465 warnings are enabled only if @code{find} is being run interactively
2466 (specifically, if the standard input is a terminal). Warning messages
2467 can be controlled explicitly by the use of options on the command
2472 Issue warning messages where appropriate.
2474 Do not issue warning messages.
2477 These options take effect at the point on the command line where they
2478 are specified. Therefore if you specify @samp{-nowarn} at the end of
2479 the command line, you will not see warning messages for any problems
2480 occurring before that. The warning messages affected by the above
2481 options are triggered by:
2485 Use of the @samp{-d} option which is deprecated; please use
2486 @samp{-depth} instead, since the latter is POSIX-compliant.
2488 Use of the @samp{-ipath} option which is deprecated; please use
2489 @samp{-iwholename} instead.
2491 Specifying an option (for example @samp{-mindepth}) after a non-option
2492 (for example @samp{-type} or @samp{-print}) on the command line.
2496 The default behaviour above is designed to work in that way so that
2497 existing shell scripts which use such constructs don't generate
2498 spurious errors, but people will be made aware of the problem.
2500 Some warning messages are issued for less common or more serious
2501 problems, and so cannot be turned off:
2505 Use of an unrecognised backslash escape sequence with @samp{-fprintf}
2507 Use of an unrecognised formatting directive with @samp{-fprintf}
2510 @node Invoking locate, Invoking updatedb, Invoking find, Reference
2511 @section Invoking @code{locate}
2514 locate @r{[}@var{option}@dots{}@r{]} @var{pattern}@dots{}
2518 @item --database=@var{path}
2519 @itemx -d @var{path}
2520 Instead of searching the default file name database, search the file
2521 name databases in @var{path}, which is a colon-separated list of
2522 database file names. You can also use the environment variable
2523 @code{LOCATE_PATH} to set the list of database files to search. The
2524 option overrides the environment variable if both are used.
2528 Only print out such names which currently exist (instead of such names
2529 which existed when the database was created).
2530 Note that this may slow down the program a lot, if there are many matches
2535 Ignore case distinctions in both the pattern and the file names.
2539 Results are separated with the ASCII NUL character rather than the
2540 newline character. To get the full benefit of the use of this option,
2541 use the new locate database format (that is the default anyway).
2545 Just print the number of results, not the results themselves.
2549 Limit the number of results printed to N. If you use the
2550 @samp{--count} option, the value printed will never be larger than
2554 The specified pattern is matched against the whole name of the file in
2555 the locate database. If the pattern contains metacharacters, it must
2556 match exactly. If not, it must match part of the whole file name.
2557 This is the default behaviour.
2560 The specified pattern is matched against just the last component of
2561 the name of the file in the locate database. This last component is
2562 also called the ``base name''. For example, the base name of
2563 @file{/tmp/mystuff/foo.old.c} is @file{foo.old.c}. If the pattern
2564 contains metacharacters, it must match exactly. If not, it must match
2565 part of the whole file name.
2568 Print some summary information for each locate database. No search is
2572 Print a summary of the options to @code{locate} and exit.
2575 Print the version number of @code{locate} and exit.
2578 @node Invoking updatedb, Invoking xargs, Invoking locate, Reference
2579 @section Invoking @code{updatedb}
2582 updatedb @r{[}@var{option}@dots{}@r{]}
2586 @item --findoptions='@var{OPTION}@dots{}'
2587 Global options to pass on to @code{find}.
2588 The environment variable @code{FINDOPTIONS} also sets this value.
2591 @item --localpaths='@var{path}@dots{}'
2592 Non-network directories to put in the database.
2593 Default is @file{/}.
2595 @item --netpaths='@var{path}@dots{}'
2596 Network (NFS, AFS, RFS, etc.) directories to put in the database.
2597 The environment variable @code{NETPATHS} also sets this value.
2600 @item --prunepaths='@var{path}@dots{}'
2601 Directories to omit from the database, which would otherwise be included.
2602 The environment variable @code{PRUNEPATHS} also sets this value.
2603 Default is @file{/tmp /usr/tmp /var/tmp /afs}.
2605 @item --prunefs='@var{path}@dots{}'
2606 File systems to omit from the database, which would otherwise be included.
2607 Note that files are pruned when a file system is reached;
2608 Any file system mounted under an undesired file system will be
2610 The environment variable @code{PRUNEFS} also sets this value.
2611 Default is @file{nfs NFS proc}.
2613 @item --output=@var{dbfile}
2614 The database file to build.
2615 Default is system-dependent, but typically @file{/usr/local/var/locatedb}.
2617 @item --localuser=@var{user}
2618 The user to search the non-network directories as, using @code{su}.
2619 Default is to search the non-network directories as the current user.
2620 You can also use the environment variable @code{LOCALUSER} to set this user.
2622 @item --netuser=@var{user}
2623 The user to search network directories as, using @code{su}.
2624 Default is @code{daemon}.
2625 You can also use the environment variable @code{NETUSER} to set this user.
2628 Generate a locate database in the old format, for compatibility with
2629 versions of @code{locate} other than GNU @code{locate}. Using this
2630 option means that @code{locate} will not be able to properly handle
2631 non-ASCII characters in filenames (that is, filenames containing
2632 characters which have the eighth bit set, such as many of the
2633 characters from the ISO-8859-1 character set).
2635 Print a summary of the command-line argument format and exit.
2637 Print the version number of @code{updatedb} and exit.
2640 @node Invoking xargs, , Invoking updatedb, Reference
2641 @section Invoking @code{xargs}
2644 xargs @r{[}@var{option}@dots{}@r{]} @r{[}@var{command} @r{[}@var{initial-arguments}@r{]}@r{]}
2647 @code{xargs} exits with the following status:
2653 if any invocation of the command exited with status 1-125
2655 if the command exited with status 255
2657 if the command is killed by a signal
2659 if the command cannot be run
2661 if the command is not found
2663 if some other error occurred.
2667 @item --arg-file@r{=@var{inputfile}}
2668 @itemx -a @r{=@var{inputfile}}
2669 Read names from the file @var{inputfile} instead of standard input.
2673 Input filenames are terminated by a null character instead of by
2674 whitespace, and the quotes and backslash are not special (every
2675 character is taken literally). Disables the end of file string, which
2676 is treated like any other argument.
2678 @item --eof@r{[}=@var{eof-str}@r{]}
2679 @itemx -e@r{[}@var{eof-str}@r{]}
2680 Set the end of file string to @var{eof-str}. If the end of file string
2681 occurs as a line of input, the rest of the input is ignored. If
2682 @var{eof-str} is omitted, there is no end of file string. If this
2683 option is not given, the end of file string defaults to @samp{_}.
2686 Print a summary of the options to @code{xargs} and exit.
2688 @item --replace@r{[}=@var{replace-str}@r{]}
2689 @itemx -i@r{[}@var{replace-str}@r{]}
2690 Replace occurrences of @var{replace-str} in the initial arguments with
2691 names read from standard input. Also, unquoted blanks do not
2692 terminate arguments; instead, the input is split at newlines only.
2693 If @var{replace-str} is omitted, it defaults to @samp{@{@}}
2694 (like for @samp{find -exec}). Implies @samp{-x} and @samp{-l 1}.
2696 @item --max-lines@r{[}=@var{max-lines}@r{]}
2697 @itemx -l@r{[}@var{max-lines}@r{]}
2698 Use at most @var{max-lines} nonblank input lines per command line;
2699 @var{max-lines} defaults to 1 if omitted. Trailing blanks cause an
2700 input line to be logically continued on the next input line, for the
2701 purpose of counting the lines. Implies @samp{-x}.
2703 @item --max-args=@var{max-args}
2704 @itemx -n @var{max-args}
2705 Use at most @var{max-args} arguments per command line. Fewer than
2706 @var{max-args} arguments will be used if the size (see the @samp{-s}
2707 option) is exceeded, unless the @samp{-x} option is given, in which case
2708 @code{xargs} will exit.
2712 Prompt the user about whether to run each command line and read a line
2713 from the terminal. Only run the command line if the response starts
2714 with @samp{y} or @samp{Y}. Implies @samp{-t}.
2716 @item --no-run-if-empty
2718 If the standard input does not contain any nonblanks, do not run the
2719 command. By default, the command is run once even if there is no input.
2721 @item --max-chars=@var{max-chars}
2722 @itemx -s @var{max-chars}
2723 Use at most @var{max-chars} characters per command line, including the
2724 command and initial arguments and the terminating nulls at the ends of
2725 the argument strings.
2729 Print the command line on the standard error output before executing
2733 Print the version number of @code{xargs} and exit.
2737 Exit if the size (see the @samp{-s} option) is exceeded.
2740 @item --max-procs=@var{max-procs}
2741 @itemx -P @var{max-procs}
2742 Run up to @var{max-procs} processes at a time; the default is 1. If
2743 @var{max-procs} is 0, @code{xargs} will run as many processes as
2747 @node Security Considerations, Error Messages, Reference, Top
2748 @chapter Security Considerations
2750 Security considerations are important if you are using @code{find} or
2751 @code{xargs} to search for or process files that don't belong to you
2752 or over which other people have control. Security considerations
2753 relating to @code{locate} may also apply if you have files which you
2754 may not want others to see.
2756 In general, the most severe forms of security problems affecting
2757 @code{find} and related programs are where third parties can bring
2758 about a situation where those programs allow them to do something
2759 they would normally not be able to do. This is called @emph{privilege
2760 elevation}. This might include deleting files they would not normally
2761 be able to delete. It is also common for the system to periodically
2762 invoke @code{find} for housekeeping purposes. These invocations of
2763 @code{find} are particularly problematic from a security point of view
2764 as these are often invoked by the superuser and search the whole file
2765 system hierarchy. The severity of any associated problem depends on
2766 what the system is going to do with the output of @code{find}.
2769 * Levels of Risk:: What is your level of exposure to security problems?
2770 * Security Considerations for find:: Security problems with find
2771 * Security Considerations for xargs:: Security problems with xargs
2772 * Security Considerations for locate:: Security problems with locate
2773 * Security Summary:: That was all very complex, what does it boil down to?
2777 @node Levels of Risk
2778 @section Levels of Risk
2780 There are some security risks inherent in the use of @code{find},
2781 @code{xargs} and (to a lesser extent) @code{locate}. The severity of
2782 these risks depends on what sort of system you are using:
2786 Multi-user systems where you do not control (or trust) the other
2787 users, and on which you execute @code{find}, including areas where
2788 those other users can manipulate the filesystem (for example beneath
2789 @file{/home} or @file{/tmp}).
2792 Systems where the actions of other users can create filenames chosen
2793 by them, but to which they don't have access while @code{find} is
2794 being run. This access might include leaving programs running (shell
2795 background jobs, @code{at} or @code{cron} tasks, for example). On
2796 these sorts of systems, carefully written commands (avoiding use of
2797 @samp{-print} for example) should not expose you to a high degree of
2798 risk. Most systems fall into this category.
2801 Systems to which untrusted parties do not have access, cannot create
2802 filenames of their own choice (even remotely) and which contain no
2803 security flaws which might enable an untrusted third party to gain
2804 access. Most systems do not fall into this category because there are
2805 many ways in which external parties can affect the names of files that
2806 are created on your system. The system on which I am writing this for
2807 example automatically downloads software updates from the Internet;
2808 the names of the files in which these updates exist are chosen by
2809 third parties@footnote{Of course, I trust these parties to a large
2810 extent anyway, because I install software provided by them; I choose
2811 to trust them in this way, and that's a deliberate choice}.
2814 In the discussion above, ``risk'' denotes the likelihood that someone
2815 can cause @code{find}, @code{xargs}, @code{locate} or some other
2816 program which is controlled by them to do something you did not
2817 intend. The levels of risk suggested do not take any account of the
2818 consequences of this sort of event. That is, if you operate a ``low
2819 risk'' type system, but the consequences of a security problem are
2820 disastrous, then you should still give serious thought to all the
2821 possible security problems, many of which of course will not be
2822 discussed here -- this section of the manual is intended to be
2823 informative but not comprehensive or exhaustive.
2825 If you are responsible for the operation of a system where the
2826 consequences of a security problem could be very important, you should
2830 @item Define a security policy which defines who is allowed to do what
2832 @item Seek competent advice on how to enforce your policy, detect
2833 breaches of that policy, and take account of any potential problems
2834 that might fall outside the scope of your policy
2838 @node Security Considerations for find
2839 @section Security Considerations for find
2842 Some of the actions @code{find} might take have a direct effect;
2843 these include @code{-exec} and @code{-delete}. However, it is also
2844 common to use @code{-print} explicitly or implicitly, and so if
2845 @code{find} produces the wrong list of filenames, that can also be a
2846 security problem; consider the case for example where @code{find} is
2847 producing a list of files to be deleted.
2849 We normally assume that the @code{find} command line expresses the
2850 file selection criteria and actions that the user had in mind -- that
2851 is, the command line is ``trusted'' data.
2853 From a security analysis point of view, the output of @code{find}
2854 should be correct; that is, the output should contain only the names
2855 of those files which meet the user's criteria specified on the command
2856 line. This applies for the @code{-exec} and @code{-delete} actions;
2857 one can consider these to be part of the output.
2859 On the other hand, the contents of the filesystem can be manipulated
2860 by other people, and hence we regard this as ``untrusted'' data. This
2861 implies that the @code{find} command line is a filter which converts
2862 the untrusted contents of the filesystem into a correct list of output
2865 The filesystem will in general change while @code{find} is searching
2866 it; in fact, most of the potential security problems with @code{find}
2867 relate to this issue in some way.
2869 Race conditions are a general class of security problem where the
2870 relative ordering of actions taken by @code{find} (for example) and
2871 something else are important@footnote{This is more or less the
2872 definition of the term ``race condition''} .
2874 Typically, an attacker might move or rename files or directories in
2875 the hope that an action might be taken against a a file which was not
2876 normally intended to be affected. Alternatively, this sort of attack
2877 might be intended to persuade @code{find} to search part of the
2878 filesystem which would not normally be included in the search
2879 (defeating the @code{-prune} action for example).
2881 @subsection Changing the Current Working Directory
2882 As find searches the file system, it finds subdirectories and then
2883 searches within them by changing its working directory. First,
2884 @code{find} notices a subdirectory. It then decides if that
2885 subdirectory meets the criteria for being searched; that is, any
2886 @samp{-xdev} or @samp{-prune} expressions are taken into account. The
2887 @code{find} program will then change working directory using the
2888 @code{chdir()} system call and proceed to search the directory.
2890 A race condition attack might take the form that once the checks
2891 relevant to @samp{-xdev} and @samp{-prune} have been done, an attacker
2892 might rename the directory that was being considered, and put in its
2893 place a symbolic link that actually points somewhere else. The
2894 @code{find} command would then issue the @code{chdir()} system call,
2895 changing its working directory to the destination of the symbolic link
2896 (@code{chdir()} will always dereference symbolic links). This
2897 manipulation leaves @code{find} with a working directory chosen by an
2898 attacker, bypassing any protection apparently provided by @samp{-xdev}
2899 and @samp{-prune}, and any protection provided by being able to
2900 @emph{not} list particular directories on the @code{find} command
2901 line. This form of attack is particularly problematic if the attacker
2902 can predict when the @code{find} command will be run, as is the case
2903 with @code{cron} tasks for example.
2905 GNU @code{find} has specific safeguards to prevent this general class
2906 of problem. Each time @code{find} changes directory, it examines the
2907 directory it is about to move to, issues the @code{chdir()} system
2908 call, and then checks that it has ended up in the subdirectory it
2909 expected. If not, an error message is issued and @code{find} exits
2910 immediately. This prevents filesystem manipulation attacks from
2911 persuading @code{find} to search parts of the filesystem it did not
2914 Where an automounter is in use, it can be the case that the use of the
2915 @code{chdir()} system call can itself cause a new filesystem to be
2916 mounted at that point. This will cause @code{find}'s security check
2917 to fail. However, this does not normally represent a security problem
2918 (since the automounter configuration is normally set up by the system
2919 administrator). Therefore, if the @code{chdir()} sanity check fails,
2920 @code{find} will check to see if a new filesystem has been mounted at
2921 the current directory; if so, @code{find} will issue a warning message
2925 @subsection Race Conditions with -exec
2927 The @samp{-exec} action causes another program to be run. It is
2928 passed the name of the file which is being considered at the time.
2929 The invoked program will then - normally - perform some action on that
2930 file. Once again, there is a race condition which can be exploited
2931 here. We shall take as a specific example the command
2934 find /tmp -path /tmp/umsp/passwd -exec /bin/rm
2937 In this simple example, we are identifying just one file to be deleted
2938 and invoking @code{/bin/rm} to delete it. A problem exists because
2939 there is a time gap between the point where @code{find} decides that
2940 it needs to process the @samp{-exec} action and the point where the
2941 @code{/bin/rm} command actually issues the @code{unlink()} system
2942 call. Within this time period, an attacker can rename the
2943 @file{/tmp/umsp} directory, replacing it with a symbolic link to
2944 @file{/etc}. There is no way for @code{/bin/rm} to determine that it
2945 is working on the same file that @code{find} had in mind. Once the
2946 symbolic link is in place, the attacker has persuaded @code{find} to
2947 cause the deletion of the @file{/etc/passwd} file, which is not the
2948 effect intended by the command which was actually invoked.
2950 One possible defence against this type of attack is to modify the
2951 behaviour of @samp{-exec} so that the @code{/bin/rm} command is run
2952 with the argument @file{./passwd} and a suitable choice of working
2953 directory. This would allow the normal sanity check that @code{find}
2954 performs to protect against this form of attack too. Unfortunately,
2955 this strategy cannot be used as the POSIX standard specifies that the
2956 current working directory for commands invoked via @samp{-exec} must
2957 be the same as the current working directory from which @code{find}
2958 was invoked. This means that the @samp{-exec} action is inherently
2959 insecure and can't be fixed.
2961 GNU @code{find} implements a more secure variant of the @samp{-exec}
2962 action, @samp{-execdir}@footnote{at the time of writing -execdir is
2963 not yet implemented, but is planned}. The @samp{-execdir} action
2964 ensures that it is not necessary to dereference subdirectories to
2965 process target files. The current directory used to invoke programs
2966 is the same as the directory in which the file to be processed exists
2967 (@file{/tmp/umsp} in our example, and only the basename of the file to
2968 be processed is passed to the invoked command, with a @samp{./}
2969 prepended (giving @file{./passwd} in our example).
2972 @subsection Race Conditions with -print and -print0
2974 The @samp{-print} and @samp{-print0} actions can be used to produce a
2975 list of files matching some criteria, which can then be used with some
2976 other command, perhaps with @code{xargs}. Unfortunately, this means
2977 that there is an unavoidable time gap between @code{find} deciding
2978 that one or more files meet its criteria and the relevant command
2979 being executed. For this reason, the @samp{-print} and @samp{-print0}
2980 actions are just as insecure as @samp{-exec}.
2982 In fact, since the construction
2985 find .... -print | xargs ....
2988 does not cope correctly with newlines or other ``white space'' in
2989 filenames, and copes poorly with filenames containing quotes, the
2990 @samp{-print} action is less secure even than @samp{-print0}.
2993 @comment node-name, next, previous, up
2994 @comment @node Security Considerations for xargs
2995 @node Security Considerations for xargs
2996 @section Security Considerations for @code{xargs}
2998 The description of the race conditions affecting the @samp{-print}
2999 action of @code{find} shows that @code{xargs} cannot be secure if it
3000 is possible for an attacker to modify a filesystem after @code{find}
3001 has started but before @code{xargs} has completed all its actions.
3003 However, there are other security issues that exist even if it is not
3004 possible for an attacker to have access to the filesystem in real
3005 time. Firstly, if it is possible for an attacker to create files with
3006 names of their own choice on the filesystem, then @code{xargs} is
3007 insecure unless the @samp{-0} option is used. If a file with the name
3008 @file{/home/someuser/foo/bar\n/etc/passwd} exists (assume that
3009 @samp{\n} stands for a newline character), then @code{find ... -print}
3010 can be persuaded to print three separate lines:
3013 /home/someuser/foo/bar
3018 If it finds a blank line in the input, @code{xargs} will ignore it.
3019 Therefore, if some action is to be taken on the basis of this list of
3020 files, the @file{/etc/passwd} file would be included even if this was
3021 not the intent of the person running find. There are circumstances in
3022 which an attacker can use this to their advantage. The same
3023 consideration applies to filenames containing ordinary spaces rather
3024 than newlines, except that of course the list of filenames will no
3025 longer contain an ``extra'' newline.
3027 This problem is an unavoidable consequence of the default behaviour of
3028 the @code{xargs} command, which is specified by the POSIX standard.
3029 The only ways to avoid this problem are either to avoid all use of
3030 @code{xargs} in favour for example of @samp{find -exec} or (where
3031 available) @samp{find -execdir}, or to use the @samp{-0} option, which
3032 ensures that @code{xargs} considers filenames to be separated by ASCII
3033 NUL characters rather than whitespace. However, useful though this
3034 option is, the POSIX standard does not make it mandatory.
3036 @comment node-name, next, previous, up
3037 @node Security Considerations for locate
3038 @section Security Considerations for @code{locate}
3040 It is fairly unusual for the output of @code{locate} to be fed into
3041 another command. However, if this were to be done, this would raise
3042 the same set of security issues as the use of @samp{find ... -print}.
3043 Although the problems relating to whitespace in filenames can be
3044 resolved by using @code{locate}'s @samp{-0} option, this still leaves
3045 the race condition problems associated with @samp{find ... -print0}.
3046 There is no way to avoid these problems in the case of @code{locate}.
3048 @node Security Summary
3051 Where untrusted parties can create files on the system, or affect the
3052 names of files that are created, all uses for @code{find},
3053 @code{locate} and @code{xargs} have known security problems except the
3057 @item Informational use only
3058 Uses where the programs are used to prepare lists of filenames upon which no further action will ever be taken.
3061 Use of the @samp{-delete} action to delete files which meet
3065 Use of the @samp{-execdir} action where the @env{PATH}
3066 environment variable contains directories which contain only trusted
3070 Please note that the @samp{-execdir} option is not yet implemented.
3073 @comment node-name, next, previous, up
3074 @node Error Messages, Primary Index, Security Considerations, Top
3075 @chapter Error Messages
3077 This section describes some of the error messages you might get from
3078 @code{find}, @code{xargs}, or @code{locate}, explains them and in some
3079 cases provides advice as to what you should do about this.
3081 This manual is written in English. The GNU findutils software
3082 features translated error messages for many languages. For this
3083 reason where possible we try to make the error messages produced by
3084 the programs self-explanatory. This approach avoids asking people to
3085 figure out which English-language error message the test they actually
3086 saw might correspond to. Error messages which are self-explanatory
3087 will not normally be described or discussed in this document. For
3088 those messages which are discussed in this document, only the
3089 English-language version of the message will be listed.
3092 * Error Messages From find::
3093 * Error Messages From xargs::
3094 * Error Messages From locate::
3095 * Error Messages From updatedb::
3098 @node Error Messages From find, Error Messages From xargs, , Error Messages
3099 @section Error Messages From find
3102 @item invalid predicate `-foo'
3103 This means that the @code{find} command line included something that
3104 started with a dash or other special character. The @code{find}
3105 program tried to interpret this as a test, action or option, but
3106 didn't recognise it. If you intended it to be a test, check what you
3107 specified against the documentation. If, on the other hand, the
3108 string is the name of a file which has been expanded from a wildcard
3109 (for example because you have a @samp{*} on the command line),
3110 consider using @samp{./*} or just @samp{.} instead.
3112 @item unexpected extra predicate
3113 This usually happens if you have an extra bracket on the command line
3114 (for example @samp{find . -print \)}).
3116 @item Warning: filesystem /path/foo has recently been mounted
3117 @itemx Warning: filesystem /path/foo has recently been unmounted
3118 These messages might appear when @code{find} moves into a directory
3119 and finds that the device number and inode are different to what it
3120 expected them to be. If the directory @code{find} has moved into is
3121 on an NFS filesystem, it will not issue this message, because
3122 @code{automount} frequently mounts new filesystems on directories as
3123 you move into them (that is how it knows you want to use the
3124 filesystem). So, if you do see this message, be wary --
3125 @code{automount} may not have been responsible. Consider the
3126 possibility that someone else is manipulating the filesystem while
3127 @code{find} is running. Some people might do this in order to mislead
3128 @code{find} or persuade it to look at one set of files when it thought
3129 it was looking at another set.
3131 @item /path/foo changed during execution of find (old device number 12345, new device number 6789, filesystem type is <whatever>) [ref XXX]
3132 This message is issued when @code{find} changes directory and ends up
3133 somewhere it didn't expect to be. This happens in one of two
3134 circumstances. Firstly this happens when ``automount'' does its thing
3135 on a system where @code{find} doesn't know how to determine what the
3136 current set of mounted filesystems is@footnote{To do this, @code{find}
3137 requires to be able to use @code{getmntent()} - check the
3138 @file{config.h} file for HAVE_GETMNTENT, which should be #defined to
3139 1. If HAVE_GETMNTENT is not set, consider submitting a problem report
3140 to @email{bug-findutils@@gnu.org}, because @code{find} needs to be
3141 able to figure out how to enumerate the mounted devices on your
3144 Secondly, this can happen when the device number of a directory
3145 appears to change during a change of current directory, but
3146 @code{find} is moving up the filesystem hierarchy rather than down it.
3147 In order to prevent @code{find} wandering off into some unexpected
3148 part of the filesystem, we stop it at this point.
3150 @item Don't know how to use getmntent() to read `/etc/mtab'. This is a bug.
3151 This message is issued when a problem similar to the above occurs on a
3152 system where @code{find} doesn't know how to figure out the current
3153 list of mount points. Ask for help on @email{bug-findutils@@gnu.org}.
3155 @item /path/foo/bar changed during execution of find (old inode number 12345, new inode number 67893, filesystem type is <whatever>) [ref XXX]"),
3156 This message is issued when @code{find} changes directory and
3157 discovers that the inode number of that directory once it's got there
3158 is different to the inode number that it obtained when it examined the
3159 directory some time previously. This normally means that while
3160 @code{find} has been deep in a directory hierarchy doing something
3161 time consuming, somebody has moved the one of the parent directories
3162 to another location in the same filesystem. This may have been done
3163 maliciously, or may not. In any case, @code{find} stops at this point
3164 in order to avoid traversing parts of the filesystem that it wasn't
3165 intended to. You can use @code{ls -li} or @code{find /path -inum
3166 12345 -o -inum 67893} to find out more about what has happened.
3168 @item sanity check of the fnmatch() library function failed.
3169 Please submit a bug report. You may well be asked questions about
3170 your system, and if you compiled the @code{findutils} code yourself,
3171 you should keep your copy of the build tree around. The likely
3172 explanation is that your system has a buggy implementation of
3173 @code{fnmatch} that looks enough like the GNU version to fool
3174 @code{configure}, but which doesn't work properly.
3177 This normally happens if you use the @code{-exec} action or a
3178 something similar (@code{-ok} and so forth) but the system has run out
3179 of free process slots. This is either because the system is very busy
3180 and the system has reached its maximum process limit, or because you
3181 have a resource limit in place and you've reached it. Check the
3182 system for runaway processes (if @code{ps} still works). Some process
3183 slots are normally reserved for use by @samp{root}.
3185 @item some-program terminated by signal 99
3186 Some program which was launched via @code{-exec} or similar was killed
3187 with a fatal signal. This is just an advisory message.
3192 @node Error Messages From xargs, Error Messages From locate, Error Messages From find, Error Messages
3193 @section Error Messages From xargs
3196 @item environment is too large for exec
3197 This message means that you have so many environment variables set
3198 (or such large values for them) that there is no room within the
3199 system-imposed limits on program command-line argument length to
3200 invoke any program. I'm sure you did this deliberately. Please try
3201 unsetting some environment variables, or exiting the current shell.
3203 @item can not fit single argument within argument list size limit
3204 You are using the @samp{-i} option and @code{xargs} doesn't have
3205 enough space to build a command line because it has read in a really
3206 large item and it doesn't fit. You can probably work around this
3207 problem with the @samp{-s} option, but the default size is pretty
3208 large. You must be trying pretty hard to break @code{xargs}.
3211 See the description of the similar message for @code{find}.
3213 @item <program>: exited with status 255; aborting
3214 When a command run by @code{xargs} exits with status 255, @code{xargs}
3215 is supposed to stop. If this is not what you intended, wrap the
3216 program you are trying to invoke in a shell script which doesn't
3219 @item <program>: terminated by signal 99
3220 See the description of the similar message for @code{find}.
3223 @node Error Messages From locate, Error Messages From updatedb, Error Messages From xargs, Error Messages
3224 @section Error Messages From locate
3227 @item warning: database `/usr/local/var/locatedb' is more than 8 days old
3228 The @code{locate} program relies on a database which is periodically
3229 built by the @code{updatedb} program. That hasn't happened in a long
3230 time. To fix this problem, run @code{updatedb} manually. This can
3231 often happen on systems that are generally not left on, so the periodic
3232 ``cron'' task which normally does this doesn't get a chance to run.
3234 @item locate database `/usr/local/var/locatedb' is corrupt or invalid
3235 This should not happen. Re-run @code{updatedb}. If that works, but
3236 @code{locate} still produces this error, run @code{locate --version}
3237 and @code{updatedb --version}. These should produce the same output.
3238 If not, you are using a mixed toolset; check your @samp{$PATH}
3239 environment variable and your shell aliases (if you have any). If
3240 both programs claim to be GNU versions, this is a bug; all versions of
3241 these programs should interoperate without problem. Ask for help on
3242 @email{bug-findutils@@gnu.org}.
3246 @node Error Messages From updatedb, , Error Messages From locate, Error Messages
3247 @section Error Messages From updatedb
3249 The @code{updatedb} program (and the programs it invokes) do issue
3250 error messages, but none of them seem to me to be candidates for
3251 guidance. If you are having a problem understanding one of these, ask
3252 for help on @email{bug-findutils@@gnu.org}.
3254 @node Primary Index, , Error Messages, Top
3255 @unnumbered @code{find} Primary Index
3257 This is a list of all of the primaries (tests, actions, and options)
3258 that make up @code{find} expressions for selecting files. @xref{find
3259 Expressions}, for more information on expressions.
3266 @comment texi related words used by Emacs' spell checker ispell.el
3268 @comment LocalWords: texinfo setfilename settitle setchapternewpage
3269 @comment LocalWords: iftex finalout ifinfo DIR titlepage vskip pt
3270 @comment LocalWords: filll dir samp dfn noindent xref pxref
3271 @comment LocalWords: var deffn texi deffnx itemx emph asis
3272 @comment LocalWords: findex smallexample subsubsection cindex
3273 @comment LocalWords: dircategory direntry itemize
3275 @comment other words used by Emacs' spell checker ispell.el
3276 @comment LocalWords: README fred updatedb xargs Plett Rendell akefile
3277 @comment LocalWords: args grep Filesystems fo foo fOo wildcards iname
3278 @comment LocalWords: ipath regex iregex expr fubar regexps
3279 @comment LocalWords: metacharacters macs sr sc inode lname ilname
3280 @comment LocalWords: sysdep noleaf ls inum xdev filesystems usr atime
3281 @comment LocalWords: ctime mtime amin cmin mmin al daystart Sladkey rm
3282 @comment LocalWords: anewer cnewer bckw rf xtype uname gname uid gid
3283 @comment LocalWords: nouser nogroup chown chgrp perm ch maxdepth
3284 @comment LocalWords: mindepth cpio src CD AFS statted stat fstype ufs
3285 @comment LocalWords: nfs tmp mfs printf fprint dils rw djm Nov lwall
3286 @comment LocalWords: POSIXLY fls fprintf strftime locale's EDT GMT AP
3287 @comment LocalWords: EST diff perl backquotes sprintf Falstad Oct cron
3288 @comment LocalWords: eg vmunix mkdir afs allexec allwrite ARG bigram
3289 @comment LocalWords: bigrams cd chmod comp crc CVS dbfile dum eof
3290 @comment LocalWords: fileserver filesystem fn frcode Ghazi Hnewc iXX
3291 @comment LocalWords: joeuser Kaveh localpaths localuser LOGNAME
3292 @comment LocalWords: Meyering mv netpaths netuser nonblank nonblanks
3293 @comment LocalWords: ois ok Pinard printindex proc procs prunefs
3294 @comment LocalWords: prunepaths pwd RFS rmadillo rmdir rsh sbins str
3295 @comment LocalWords: su Timar ubins ug unstripped vf VM Weitzel
3296 @comment LocalWords: wildcard zlogout basename execdir wholename iwholename
3298 @comment LocalWords: occur when the @samp{-L} option
3303 @code{find} follows symbolic links to directories when searching
3306 @samp{-lname} and @samp{-ilname} always return false (unless they
3307 happen to match broken symbolic links).
3309 @samp{-type} reports the types of the files that symbolic links point
3312 Implies @samp{-noleaf} (@pxref{Directories}).
3315 If the @samp{-L} option or the @samp{-H} option is used,
3316 the filenames used as arguments to @samp{-newer}, @samp{-anewer}, and
3317 @samp{-cnewer} are dereferenced and the timestamp from the pointed-to
3318 file is used instead (if possible -- otherwise the timestamp from the
3319 symbolic link is used).
3321 @deffn Test -lname pattern
3322 @deffnx Test -ilname pattern
3323 True if the file is a symbolic link whose contents match shell pattern
3324 @var{pattern}. For @samp{-ilname}, the match is case-insensitive.
3325 @xref{Shell Pattern Matching}, for details about the @var{pattern}
3326 argument. If the @samp{-L} option is in effect, this test will always
3327 fail for symbolic links unless they are broken. So, to list any
3328 symbolic links to @file{sysdep.c} in the current directory and its
3329 subdirectories, you can do:
3332 find . -lname '*sysdep.c'
3337 @subsection Hard Links
3339 To find hard links, first get the inode number of the file whose links
3340 you want to find. You can learn a file's inode number and the number of
3341 links to it by running @samp{ls -i} or @samp{find -ls}. If the file has
3342 more than one link, you can search for the other links by passing that
3343 inode number to @samp{-inum}. Add the @samp{-xdev} option if you are
3344 starting the search at a directory that has other filesystems mounted on
3345 it, such as @file{/usr} on many systems. Doing this saves needless
3346 searching, since hard links to a file must be on the same filesystem.
3350 File has inode number @var{n}. The @samp{+} and @samp{-} qualifiers
3351 also work, though these are rarely useful.
3354 You can also search for files that have a certain number of links, with
3355 @samp{-links}. Directories normally have at least two hard links; their
3356 @file{.} entry is the second one. If they have subdirectories, each of
3357 those also has a hard link called @file{..} to its parent directory.
3359 @deffn Test -links n
3360 File has @var{n} hard links.
3363 @deffn Test -links +n
3364 File has more than @var{n} hard links.
3367 @deffn Test -links -n
3368 File has fewer than @var{n} hard links.
3374 Each file has three time stamps, which record the last time that certain
3375 operations were performed on the file:
3379 access (read the file's contents)
3381 change the status (modify the file or its attributes)
3383 modify (change the file's contents)
3386 There is no timestamp that indicates when a file was @emph{created}.
3388 You can search for files whose time stamps are within a certain age
3389 range, or compare them to other time stamps.
3393 * Comparing Timestamps::
3397 @subsection Age Ranges
3399 These tests are mainly useful with ranges (@samp{+@var{n}} and
3402 @deffn Test -atime n
3403 @deffnx Test -ctime n
3404 @deffnx Test -mtime n
3405 True if the file was last accessed (or its status changed, or it was
3406 modified) @var{n}*24 hours ago. The number of 24-hour periods since
3407 the file's timestamp is always rounded down; therefore 0 means ``less
3408 than 24 hours ago'', 1 means ``between 24 and 48 hours ago'', and so
3413 @deffnx Test -cmin n
3414 @deffnx Test -mmin n
3415 True if the file was last accessed (or its status changed, or it was
3416 modified) @var{n} minutes ago. These tests provide finer granularity of
3417 measurement than @samp{-atime} et al., but rounding is done in a
3418 similar way. For example, to list files in
3419 @file{/u/bill} that were last read from 2 to 6 minutes ago:
3422 find /u/bill -amin +2 -amin -6
3426 @deffn Option -daystart
3427 Measure times from the beginning of today rather than from 24 hours ago.
3428 So, to list the regular files in your home directory that were modified
3432 find ~ -daystart -type f -mtime 1
3436 The @samp{-daystart} option is unlike most other options in that it
3437 has an effect on the way that other tests are performed. The affected
3438 tests are @samp{-amin}, @samp{-cmin}, @samp{-mmin}, @samp{-atime},
3439 @samp{-ctime} and @samp{-mtime}.
3441 @node Comparing Timestamps
3442 @subsection Comparing Timestamps
3444 As an alternative to comparing timestamps to the current time, you can
3445 compare them to another file's timestamp. That file's timestamp could
3446 be updated by another program when some event occurs. Or you could set
3447 it to a particular fixed date using the @code{touch} command. For
3448 example, to list files in @file{/usr} modified after February 1 of the
3451 @c Idea from Rick Sladkey.
3453 touch -t 02010000 /tmp/stamp$$
3454 find /usr -newer /tmp/stamp$$
3458 @deffn Test -anewer file
3459 @deffnx Test -cnewer file
3460 @deffnx Test -newer file
3461 True if the file was last accessed (or its status changed, or it was
3462 modified) more recently than @var{file} was modified. These tests are
3463 affected by @samp{-follow} only if @samp{-follow} comes before them on
3464 the command line. @xref{Symbolic Links}, for more information on
3465 @samp{-follow}. As an example, to list any files modified since
3466 @file{/bin/sh} was last modified:
3469 find . -newer /bin/sh
3474 True if the file was last accessed @var{n} days after its status was
3475 last changed. Useful for finding files that are not being used, and
3476 could perhaps be archived or removed to save disk space.
3482 @deffn Test -size n@r{[}bckwMG@r{]}
3483 True if the file uses @var{n} units of space, rounding up. The units
3484 are 512-byte blocks by default, but they can be changed by adding a
3485 one-character suffix to @var{n}:
3489 512-byte blocks (never 1024)
3493 kilobytes (1024 bytes)
3502 The `b' suffix always considers blocks to be 512 bytes. This is not
3503 affected by the setting (or non-setting) of the POSIXLY_CORRECT
3504 environment variable. This behaviour is different to the behaviour of
3505 the @samp{-ls} action). If you want to use 1024-byte units, use the
3508 The number can be prefixed with a `+' or a `-'. A plus sign indicates
3509 that the test should succeed if the file uses at least @var{n} units
3510 of storage (this is the way I normally use this test) and a minus sign
3511 indicates that the test should succeed if the file uses less than
3512 @var{n} units of storage. There is no `=' prefix, because that's the
3515 The size does not count indirect blocks, but it does count blocks in
3516 sparse files that are not actually allocated. This handling of sparse
3517 files differs from the output of the @samp{%k} and @samp{%b} format
3518 specifiers for the @samp{-printf} predicate.
3523 True if the file is empty and is either a regular file or a directory.
3524 This might make it a good candidate for deletion. This test is useful
3525 with @samp{-depth} (@pxref{Directories}) and @samp{-delete}
3526 (@pxref{Single File}).
3533 True if the file is of type @var{c}:
3537 block (buffered) special
3539 character (unbuffered) special
3555 @deffn Test -xtype c
3556 The same as @samp{-type} unless the file is a symbolic link. For
3557 symbolic links: if @samp{-follow} has not been given, true if the file
3558 is a link to a file of type @var{c}; if @samp{-follow} has been given,
3559 true if @var{c} is @samp{l}. In other words, for symbolic links,
3560 @samp{-xtype} checks the type of the file that @samp{-type} does not
3561 check. @xref{Symbolic Links}, for more information on @samp{-follow}.
3567 @deffn Test -user uname
3568 @deffnx Test -group gname
3569 True if the file is owned by user @var{uname} (belongs to group @var{gname}).
3570 A numeric ID is allowed.
3575 True if the file's numeric user ID (group ID) is @var{n}. These tests
3576 support ranges (@samp{+@var{n}} and @samp{-@var{n}}), unlike
3577 @samp{-user} and @samp{-group}.
3581 @deffnx Test -nogroup
3582 True if no user corresponds to the file's numeric user ID (no group
3583 corresponds to the numeric group ID). These cases usually mean that the
3584 files belonged to users who have since been removed from the system.
3585 You probably should change the ownership of such files to an existing
3586 user or group, using the @code{chown} or @code{chgrp} program.
3590 @section Permissions
3592 @xref{File Permissions}, for information on how file permissions are
3593 structured and how to specify them.
3595 @deffn Test -perm mode
3597 file's permissions are exactly @var{mode} (which can be numeric or symbolic).
3598 Symbolic modes use mode 0 as a point of departure.
3599 If @var{mode} starts with @samp{-}, true if
3600 @emph{all} of the permissions set in @var{mode} are set for the file;
3601 permissions not set in @var{mode} are ignored.
3602 If @var{mode} starts with @samp{+}, true if
3603 @emph{any} of the permissions set in @var{mode} are set for the file;
3604 permissions not set in @var{mode} are ignored.
3610 To search for files based on their contents, you can use the @code{grep}
3611 program. For example, to find out which C source files in the current
3612 directory contain the string @samp{thing}, you can do:
3615 grep -l thing *.[ch]
3618 If you also want to search for the string in files in subdirectories,
3619 you can combine @code{grep} with @code{find} and @code{xargs}, like
3623 find . -name '*.[ch]' | xargs grep -l thing
3626 The @samp{-l} option causes @code{grep} to print only the names of files
3627 that contain the string, rather than the lines that contain it. The
3628 string argument (@samp{thing}) is actually a regular expression, so it
3629 can contain metacharacters. This method can be refined a little by
3630 using the @samp{-r} option to make @code{xargs} not run @code{grep} if
3631 @code{find} produces no output, and using the @code{find} action
3632 @samp{-print0} and the @code{xargs} option @samp{-0} to avoid
3633 misinterpreting files whose names contain spaces:
3636 find . -name '*.[ch]' -print0 | xargs -r -0 grep -l thing
3639 For a fuller treatment of finding files whose contents match a pattern,
3640 see the manual page for @code{grep}.
3643 @section Directories
3645 Here is how to control which directories @code{find} searches, and how
3646 it searches them. These two options allow you to process a horizontal
3647 slice of a directory tree.
3649 @deffn Option -maxdepth levels
3650 Descend at most @var{levels} (a non-negative integer) levels of
3651 directories below the command line arguments. @samp{-maxdepth 0} means
3652 only apply the tests and actions to the command line arguments.
3655 @deffn Option -mindepth levels
3656 Do not apply any tests or actions at levels less than @var{levels} (a
3657 non-negative integer). @samp{-mindepth 1} means process all files
3658 except the command line arguments.
3661 @deffn Option -depth
3662 Process each directory's contents before the directory itself. Doing
3663 this is a good idea when producing lists of files to archive with
3664 @code{cpio} or @code{tar}. If a directory does not have write
3665 permission for its owner, its contents can still be restored from the
3666 archive since the directory's permissions are restored after its contents.
3670 This is a deprecated synonym for @samp{-depth}, for compatibility with
3671 Mac OS X, FreeBSD and OpenBSD. The @samp{-depth} option is a POSIX
3672 feature, so it is better to use that.
3675 @deffn Action -prune
3676 If the file is a directory, do not descend into it. The result is
3677 true. For example, to skip the directory @file{src/emacs} and all
3678 files and directories under it, and print the names of the other files
3682 find . -wholename './src/emacs' -prune -o -print
3685 The above command will not print @file{./src/emacs} among its list of
3686 results. This however is not due to the effect of the @samp{-prune}
3687 action (which only prevents further descent, it doesn't make sure we
3688 ignore that item). Instead, this effect is due to the use of
3689 @samp{-o}. Since the left hand side of the ``or'' condition has
3690 succeeded for @file{./src/emacs}, it is not necessary to evaluate the
3691 right-hand-side (@samp{-print}) at all for this particular file. If
3692 you wanted to print that directory name you could use either an extra
3693 @samp{-print} action:
3696 find . -wholename './src/emacs' -prune -print -o -print
3699 or use the comma operator:
3702 find . -wholename './src/emacs' -prune , -print
3705 If the @samp{-depth} option is in effect, the subdirectories will have
3706 already been visited in any case. Hence @samp{-prune} has no effect
3712 Exit immediately with return value zero. No child processes will be
3713 left running, but no more paths specified on the command line will be
3714 processed. For example, @code{find /tmp/foo /tmp/bar -print -quit}
3715 will print only @samp{/tmp/foo}.
3718 @deffn Option -noleaf
3719 Do not optimize by assuming that directories contain 2 fewer
3720 subdirectories than their hard link count. This option is needed when
3721 searching filesystems that do not follow the Unix directory-link
3722 convention, such as CD-ROM or MS-DOS filesystems or AFS volume mount
3723 points. Each directory on a normal Unix filesystem has at least 2 hard
3724 links: its name and its @file{.} entry. Additionally, its
3725 subdirectories (if any) each have a @file{..} entry linked to that
3726 directory. When @code{find} is examining a directory, after it has
3727 statted 2 fewer subdirectories than the directory's link count, it knows
3728 that the rest of the entries in the directory are non-directories
3729 (@dfn{leaf} files in the directory tree). If only the files' names need
3730 to be examined, there is no need to stat them; this gives a significant
3731 increase in search speed.
3734 @deffn Option -ignore_readdir_race
3735 If a file disappears after its name has been read from a directory but
3736 before @code{find} gets around to examining the file with @code{stat},
3737 don't issue an error message. If you don't specify this option, an
3738 error message will be issued. This option can be useful in system
3739 scripts (cron scripts, for example) that examine areas of the
3740 filesystem that change frequently (mail queues, temporary directories,
3741 and so forth), because this scenario is common for those sorts of
3742 directories. Completely silencing error messages from @code{find} is
3743 undesirable, so this option neatly solves the problem. There is no
3744 way to search one part of the filesystem with this option on and part
3745 of it with this option off, though.
3748 @deffn Option -noignore_readdir_race
3749 This option reverses the effect of the @samp{-ignore_readdir_race} option.
3754 @section Filesystems
3756 A @dfn{filesystem} is a section of a disk, either on the local host or
3757 mounted from a remote host over a network. Searching network
3758 filesystems can be slow, so it is common to make @code{find} avoid them.
3760 There are two ways to avoid searching certain filesystems. One way is
3761 to tell @code{find} to only search one filesystem:
3764 @deffnx Option -mount
3765 Don't descend directories on other filesystems. These options are synonyms.
3768 The other way is to check the type of filesystem each file is on, and
3769 not descend directories that are on undesirable filesystem types:
3771 @deffn Test -fstype type
3772 True if the file is on a filesystem of type @var{type}. The valid
3773 filesystem types vary among different versions of Unix; an incomplete
3774 list of filesystem types that are accepted on some version of Unix or
3777 ext2 ext3 proc sysfs ufs 4.2 4.3 nfs tmp mfs S51K S52K
3779 You can use @samp{-printf} with the @samp{%F} directive to see the types
3780 of your filesystems. The @samp{%D} directive shows the device number.
3781 @xref{Print File Information}. @samp{-fstype} is
3782 usually used with @samp{-prune} to avoid searching remote filesystems
3783 (@pxref{Directories}).
3786 @node Combining Primaries With Operators
3787 @section Combining Primaries With Operators
3789 Operators build a complex expression from tests and actions.
3790 The operators are, in order of decreasing precedence:
3793 @item @asis{( @var{expr} )}
3795 Force precedence. True if @var{expr} is true.
3797 @item @asis{! @var{expr}}
3798 @itemx @asis{-not @var{expr}}
3801 True if @var{expr} is false.
3803 @item @asis{@var{expr1 expr2}}
3804 @itemx @asis{@var{expr1} -a @var{expr2}}
3805 @itemx @asis{@var{expr1} -and @var{expr2}}
3808 And; @var{expr2} is not evaluated if @var{expr1} is false.
3810 @item @asis{@var{expr1} -o @var{expr2}}
3811 @itemx @asis{@var{expr1} -or @var{expr2}}
3814 Or; @var{expr2} is not evaluated if @var{expr1} is true.
3816 @item @asis{@var{expr1} , @var{expr2}}
3818 List; both @var{expr1} and @var{expr2} are always evaluated. True if
3819 @var{expr2} is true. The value of @var{expr1} is discarded. This
3820 operator lets you do multiple independent operations on one traversal,
3821 without depending on whether other operations succeeded. The two
3822 operations @var{expr1} and @var{expr2} are not always filly
3823 independent, since @var{expr1} might have side effects like touching
3824 or deleting files, or it might use @samp{-prune} which would also
3828 @code{find} searches the directory tree rooted at each file name by
3829 evaluating the expression from left to right, according to the rules of
3830 precedence, until the outcome is known (the left hand side is false for
3831 @samp{-and}, true for @samp{-or}), at which point @code{find} moves on
3832 to the next file name.
3834 There are two other tests that can be useful in complex expressions:
3844 @node Actions, Common Tasks, Finding Files, Top
3847 There are several ways you can print information about the files that
3848 match the criteria you gave in the @code{find} expression. You can
3849 print the information either to the standard output or to a file that
3850 you name. You can also execute commands that have the file names as
3851 arguments. You can use those commands as further filters to select files.
3855 * Print File Information::
3861 @node Print File Name
3862 @section Print File Name
3864 @deffn Action -print
3865 True; print the full file name on the standard output, followed by a
3869 @deffn Action -fprint file
3870 True; print the full file name into file @var{file}, followed by a
3871 newline. If @var{file} does not exist when @code{find} is run, it is
3872 created; if it does exist, it is truncated to 0 bytes. The file names
3873 @file{/dev/stdout} and @file{/dev/stderr} are handled specially; they
3874 refer to the standard output and standard error output, respectively.
3877 @node Print File Information
3878 @section Print File Information
3881 True; list the current file in @samp{ls -dils} format on the standard
3882 output. The output looks like this:
3885 204744 17 -rw-r--r-- 1 djm staff 17337 Nov 2 1992 ./lwall-quotes
3892 The inode number of the file. @xref{Hard Links}, for how to find files
3893 based on their inode number.
3896 the number of blocks in the file. The block counts are of 1K blocks,
3897 unless the environment variable @code{POSIXLY_CORRECT} is set, in which
3898 case 512-byte blocks are used. @xref{Size}, for how to find files based
3902 The file's type and permissions. The type is shown as a dash for a
3903 regular file; for other file types, a letter like for @samp{-type} is
3904 used (@pxref{Type}). The permissions are read, write, and execute for
3905 the file's owner, its group, and other users, respectively; a dash means
3906 the permission is not granted. @xref{File Permissions}, for more details
3907 about file permissions. @xref{Permissions}, for how to find files based
3908 on their permissions.
3911 The number of hard links to the file.
3914 The user who owns the file.
3920 The file's size in bytes.
3923 The date the file was last modified.
3926 The file's name. @samp{-ls} quotes non-printable characters in the file
3927 names using C-like backslash escapes.
3931 @deffn Action -fls file
3932 True; like @samp{-ls} but write to @var{file} like @samp{-fprint}
3933 (@pxref{Print File Name}).
3936 @deffn Action -printf format
3937 True; print @var{format} on the standard output, interpreting @samp{\}
3938 escapes and @samp{%} directives. Field widths and precisions can be
3939 specified as with the @code{printf} C function. Format flags (like
3940 @samp{#} for example) may not work as you expect because many of the
3941 fields, even numeric ones, are printed with %s. This means though
3942 that the format flag @samp{-} will work; it forces left-alignment of
3943 the field. Unlike @samp{-print}, @samp{-printf} does not add a
3944 newline at the end of the string. If you want a newline at the end of
3945 the string, add a @samp{\n}.
3948 @deffn Action -fprintf file format
3949 True; like @samp{-printf} but write to @var{file} like @samp{-fprint}
3950 (@pxref{Print File Name}).
3955 * Format Directives::
3962 The escapes that @samp{-printf} and @samp{-fprintf} recognize are:
3970 Stop printing from this format immediately and flush the output.
3982 A literal backslash (@samp{\}).
3984 The character whose ASCII code is NNN (octal).
3987 A @samp{\} character followed by any other character is treated as an
3988 ordinary character, so they both are printed, and a warning message is
3989 printed to the standard error output (because it was probably a typo).
3991 @node Format Directives
3992 @subsection Format Directives
3994 @samp{-printf} and @samp{-fprintf} support the following format
3995 directives to print information about the file being processed. The C
3996 @code{printf} function, field width and precision specifiers are
3997 supported, as applied to string (%s) types. That is, you can specify
3998 "minimum field width"."maximum field width" for each directive.
3999 Format flags (like @samp{#} for example) may not work as you expect
4000 because many of the fields, even numeric ones, are printed with %s.
4001 The format flag @samp{-} does work; it forces left-alignment of the
4004 @samp{%%} is a literal percent sign. A @samp{%} character followed by
4005 an unrecognised character (i.e. not a known directive or printf field
4006 width and precision specifier), is discarded (but the unrecognised character
4007 is printed), and a warning message is printed to the standard error output
4008 (because it was probably a typo).
4012 * Ownership Directives::
4014 * Location Directives::
4016 * Formatting Flags::
4019 @node Name Directives
4020 @subsubsection Name Directives
4025 File's name (not the absolute path name, but the name of the file as
4026 it was encountered by find - that is, as a relative path from one of
4027 the starting points).
4029 File's name with any leading directories removed (only the last element).
4032 Leading directories of file's name (all but the last element and the
4036 File's name with the name of the command line argument under which
4037 it was found removed from the beginning.
4040 Command line argument under which file was found.
4044 @node Ownership Directives
4045 @subsubsection Ownership Directives
4050 File's group name, or numeric group ID if the group has no name.
4053 @c TODO: Needs to support # flag and 0 flag
4054 File's numeric group ID.
4057 File's user name, or numeric user ID if the user has no name.
4060 @c TODO: Needs to support # flag
4061 File's numeric user ID.
4063 @c full support, including # and 0.
4064 File's permissions (in octal). If you always want to have a leading
4065 zero on the number, use the '#' format flag, for example '%#m'.
4068 @node Size Directives
4069 @subsubsection Size Directives
4073 Amount of disk space occupied by the file, measured in 1K blocks
4074 (rounded up). This can be less than the length of the file if
4075 it is a sparse file (that is, it has ``holes'').
4077 File's size in 512-byte blocks (rounded up). This also can be less
4078 than the length of the file, if the file is sparse.
4080 File's size in bytes.
4083 @node Location Directives
4084 @subsubsection Location Directives
4088 File's depth in the directory tree (depth below a file named on the
4089 command line, not depth below the root directory). Files named on the
4090 command line have a depth of 0. Subdirectories immediately below them
4091 have a depth of 1, and so on.
4093 The device number on which the file exists (the @code{st_dev} field of
4094 @code{struct stat}), in decimal.
4096 Type of the filesystem the file is on; this value can be used for
4097 @samp{-fstype} (@pxref{Directories}).
4099 Object of symbolic link (empty string if file is not a symbolic link).
4101 File's inode number (in decimal).
4103 Number of hard links to file.
4105 Type of the file as used with @samp{-type}. If the file is a symbolic
4106 link, @samp{l} will be printed.
4108 Type of the file as used with @samp{-type}. If the file is a symbolic
4109 link, it is dereferenced. If the file is a broken symbolic link,
4110 @samp{N} is printed.
4114 @node Time Directives
4115 @subsubsection Time Directives
4117 Some of these directives use the C @code{ctime} function. Its output
4118 depends on the current locale, but it typically looks like
4121 Wed Nov 2 00:42:36 1994
4126 File's last access time in the format returned by the C @code{ctime} function.
4128 File's last access time in the format specified by @var{k}
4129 (@pxref{Time Formats}).
4131 File's last status change time in the format returned by the C @code{ctime}
4134 File's last status change time in the format specified by @var{k}
4135 (@pxref{Time Formats}).
4137 File's last modification time in the format returned by the C @code{ctime}
4140 File's last modification time in the format specified by @var{k}
4141 (@pxref{Time Formats}).
4145 @subsection Time Formats
4147 Below are the formats for the directives @samp{%A}, @samp{%C}, and
4148 @samp{%T}, which print the file's timestamps. Some of these formats
4149 might not be available on all systems, due to differences in the C
4150 @code{strftime} function between systems.
4155 * Combined Time Formats::
4158 @node Time Components
4159 @subsubsection Time Components
4161 The following format directives print single components of the time.
4175 time zone (e.g., EDT), or nothing if no time zone is determinable
4181 seconds since Jan. 1, 1970, 00:00 GMT.
4184 @node Date Components
4185 @subsubsection Date Components
4187 The following format directives print single components of the date.
4191 locale's abbreviated weekday name (Sun..Sat)
4193 locale's full weekday name, variable length (Sunday..Saturday)
4196 locale's abbreviated month name (Jan..Dec)
4198 locale's full month name, variable length (January..December)
4202 day of month (01..31)
4206 day of year (001..366)
4208 week number of year with Sunday as first day of week (00..53)
4210 week number of year with Monday as first day of week (00..53)
4214 last two digits of year (00..99)
4217 @node Combined Time Formats
4218 @subsubsection Combined Time Formats
4220 The following format directives print combinations of time and date
4225 time, 12-hour (hh:mm:ss [AP]M)
4227 time, 24-hour (hh:mm:ss)
4229 locale's time representation (H:M:S)
4231 locale's date and time (Sat Nov 04 12:02:33 EST 1989)
4235 locale's date representation (mm/dd/yy)
4237 Date and time, separated by '+', for example `2004-04-28+22:22:05'.
4238 The time is given in the current timezone (which may be affected by
4239 setting the TZ environment variable). This is a GNU extension.
4242 @node Formatting Flags
4243 @subsubsection Formatting Flags
4245 The @samp{%m} and @samp{%d} directives support the @samp{#}, @samp{0}
4246 and @samp{+} flags, but the other directives do not, even if they
4247 print numbers. Numeric directives that do not support these flags
4257 All fields support the format flag @samp{-}, which makes fields
4258 left-aligned. That is, if the field width is greater than the actual
4259 contents of the field, the requisite number of spaces are printed
4260 after the field content instead of before it.
4263 @section Run Commands
4265 You can use the list of file names created by @code{find} or
4266 @code{locate} as arguments to other commands. In this way you can
4267 perform arbitrary actions on the files.
4276 @subsection Single File
4278 Here is how to run a command on one file at a time.
4280 @deffn Action -exec command ;
4281 Execute @var{command}; true if 0 status is returned. @code{find} takes
4282 all arguments after @samp{-exec} to be part of the command until an
4283 argument consisting of @samp{;} is reached. It replaces the string
4284 @samp{@{@}} by the current file name being processed everywhere it
4285 occurs in the command. Both of these constructions need to be escaped
4286 (with a @samp{\}) or quoted to protect them from expansion by the shell.
4287 The command is executed in the directory in which @code{find} was run.
4289 For example, to compare each C header file in the current directory with
4290 the file @file{/tmp/master}:
4293 find . -name '*.h' -exec diff -u '@{@}' /tmp/master ';'
4298 @deffn Action -exec command +
4299 This variant of @samp{-exec} not yet supported. Once it has been
4300 implemented as specified in the POSIX standard, a @samp{@{@}} will expand to
4301 a list of names of matching files. This expansion is done in such a
4302 way as to avoid exceeding the maximum command line length available on
4307 @node Multiple Files
4308 @subsection Multiple Files
4310 Sometimes you need to process files alone. But when you
4311 don't, it is faster to run a command on as many files as possible at a
4312 time, rather than once per file. Doing this saves on the time it takes
4313 to start up the command each time.
4315 To run a command on more than one file at once, use the @code{xargs}
4316 command, which is invoked like this:
4319 xargs @r{[}@var{option}@dots{}@r{]} @r{[}@var{command} @r{[}@var{initial-arguments}@r{]}@r{]}
4322 @code{xargs} normally reads arguments from the standard input. These
4323 arguments are delimited by blanks (which can be protected with double
4324 or single quotes or a backslash) or newlines. It executes the
4325 @var{command} (default is @file{/bin/echo}) one or more times with any
4326 @var{initial-arguments} followed by arguments read from standard
4327 input. Blank lines on the standard input are ignored.
4329 Instead of blank-delimited names, it is safer to use @samp{find -print0}
4330 or @samp{find -fprint0} and process the output by giving the @samp{-0}
4331 or @samp{--null} option to GNU @code{xargs}, GNU @code{tar}, GNU
4332 @code{cpio}, or @code{perl}. The @code{locate} command also has a
4333 @samp{-0} or @samp{--null} option which does the same thing.
4335 You can use shell command substitution (backquotes) to process a list of
4336 arguments, like this:
4339 grep -l sprintf `find $HOME -name '*.c' -print`
4342 However, that method produces an error if the length of the @samp{.c}
4343 file names exceeds the operating system's command-line length limit.
4344 @code{xargs} avoids that problem by running the command as many times as
4345 necessary without exceeding the limit:
4348 find $HOME -name '*.c' -print | xargs grep -l sprintf
4351 However, if the command needs to have its standard input be a terminal
4352 (@code{less}, for example), you have to use the shell command
4353 substitution method or use the @samp{--arg-file} option of
4356 The @code{xargs} command will process all its input, building command
4357 lines and executing them, unless one of the commands exits with a
4358 status of 255 (this will cause xargs to issue an error message and
4359 stop) or it reads a line contains the end of file string specified
4360 with the @samp{--eof} option.
4363 * Unsafe File Name Handling::
4364 * Safe File Name Handling::
4365 * Limiting Command Size::
4366 * Interspersing File Names::
4369 @node Unsafe File Name Handling
4370 @subsubsection Unsafe File Name Handling
4372 Because file names can contain quotes, backslashes, blank characters,
4373 and even newlines, it is not safe to process them using @code{xargs} in its
4374 default mode of operation. But since most files' names do not contain
4375 blanks, this problem occurs only infrequently. If you are only
4376 searching through files that you know have safe names, then you need not
4377 be concerned about it.
4379 @c This example is adapted from:
4380 @c From: pfalstad@stone.Princeton.EDU (Paul John Falstad)
4381 @c Newsgroups: comp.unix.shell
4382 @c Subject: Re: Beware xargs security holes
4383 @c Date: 16 Oct 90 19:12:06 GMT
4385 In many applications, if @code{xargs} botches processing a file because
4386 its name contains special characters, some data might be lost. The
4387 importance of this problem depends on the importance of the data and
4388 whether anyone notices the loss soon enough to correct it. However,
4389 here is an extreme example of the problems that using blank-delimited
4390 names can cause. If the following command is run daily from
4391 @code{cron}, then any user can remove any file on the system:
4394 find / -name '#*' -atime +7 -print | xargs rm
4397 For example, you could do something like this:
4405 and then @code{cron} would delete @file{/vmunix}, if it ran
4406 @code{xargs} with @file{/} as its current directory.
4408 To delete other files, for example @file{/u/joeuser/.plan}, you could do
4416 eg$ mkdir u u/joeuser u/joeuser/.plan'
4418 eg$ echo > u/joeuser/.plan'
4421 eg$ find . -name '#*' -print | xargs echo
4422 ./# ./# /u/joeuser/.plan /#foo
4425 @node Safe File Name Handling
4426 @subsubsection Safe File Name Handling
4428 Here is how to make @code{find} output file names so that they can be
4429 used by other programs without being mangled or misinterpreted. You can
4430 process file names generated this way by giving the @samp{-0} or
4431 @samp{--null} option to GNU @code{xargs}, GNU @code{tar}, GNU
4432 @code{cpio}, or @code{perl}.
4434 @deffn Action -print0
4435 True; print the full file name on the standard output, followed by a
4439 @deffn Action -fprint0 file
4440 True; like @samp{-print0} but write to @var{file} like @samp{-fprint}
4441 (@pxref{Print File Name}).
4444 As of findutils version 4.2.4, the @code{locate} program also has a
4445 @samp{--null} option which does the same thing. For similarity with
4446 @code{xargs}, the short form of the option @samp{-0} can also be used.
4448 If you want to be able to handle file names safely but need to run
4449 commands which want to be connected to a terminal on their input, you
4450 can use the @samp{--arg-file} option to @code{xargs} like this:
4453 find / -name xyzzy -print0 > list
4454 xargs --null --arg-file=list munge
4457 The example above runs the @code{munge} program on all the files named
4458 @file{xyzzy} that we can find, but @code{munge}'s input will still be
4459 the terminal (or whatever the shell was using as standard input). If
4460 your shell has the ``process substitution'' feature @samp{<(...)}, you
4461 can do this in just one step:
4464 xargs --null --arg-file=<(find / -name xyzzy -print0) munge
4467 @node Limiting Command Size
4468 @subsubsection Limiting Command Size
4470 @code{xargs} gives you control over how many arguments it passes to the
4471 command each time it executes it. By default, it uses up to
4472 @code{ARG_MAX} - 2k, or 128k, whichever is smaller, characters per
4473 command. It uses as many lines and arguments as fit within that limit.
4474 The following options modify those values.
4477 @item --no-run-if-empty
4479 If the standard input does not contain any nonblanks, do not run the
4480 command. By default, the command is run once even if there is no input.
4482 @item --max-lines@r{[}=@var{max-lines}@r{]}
4483 @itemx -l@r{[}@var{max-lines}@r{]}
4484 Use at most @var{max-lines} nonblank input lines per command line;
4485 @var{max-lines} defaults to 1 if omitted. Trailing blanks cause an
4486 input line to be logically continued on the next input line, for the
4487 purpose of counting the lines. Implies @samp{-x}.
4489 @item --max-args=@var{max-args}
4490 @itemx -n @var{max-args}
4491 Use at most @var{max-args} arguments per command line. Fewer than
4492 @var{max-args} arguments will be used if the size (see the @samp{-s}
4493 option) is exceeded, unless the @samp{-x} option is given, in which case
4494 @code{xargs} will exit.
4496 @item --max-chars=@var{max-chars}
4497 @itemx -s @var{max-chars}
4498 Use at most @var{max-chars} characters per command line, including the
4499 command and initial arguments and the terminating nulls at the ends of
4500 the argument strings. If you specify a value for this option which is
4501 too large or small, a warning message is printed and the appropriate
4502 upper or lower limit is used instead.
4504 @item --max-procs=@var{max-procs}
4505 @itemx -P @var{max-procs}
4506 Run up to @var{max-procs} processes at a time; the default is 1. If
4507 @var{max-procs} is 0, @code{xargs} will run as many processes as
4508 possible at a time. Use the @samp{-n}, @samp{-s}, or @samp{-l} option
4509 with @samp{-P}; otherwise chances are that the command will be run only
4513 @node Interspersing File Names
4514 @subsubsection Interspersing File Names
4516 @code{xargs} can insert the name of the file it is processing between
4517 arguments you give for the command. Unless you also give options to
4518 limit the command size (@pxref{Limiting Command Size}), this mode of
4519 operation is equivalent to @samp{find -exec} (@pxref{Single File}).
4522 @item --replace@r{[}=@var{replace-str}@r{]}
4523 @itemx -i@r{[}@var{replace-str}@r{]}
4524 Replace occurrences of @var{replace-str} in the initial arguments with
4525 names read from the input. Also, unquoted blanks do not
4526 terminate arguments; instead, the input is split at newlines only. If
4527 @var{replace-str} is omitted, it defaults to @samp{@{@}} (like for
4528 @samp{find -exec}). Implies @samp{-x} and @samp{-l 1}. As an
4529 example, to sort each file the @file{bills} directory, leaving the
4530 output in that file name with @file{.sorted} appended, you could do:
4533 find bills -type f | xargs -iXX sort -o XX.sorted XX
4537 The equivalent command using @samp{find -exec} is:
4540 find bills -type f -exec sort -o '@{@}.sorted' '@{@}' ';'
4545 @subsection Querying
4547 To ask the user whether to execute a command on a single file, you can
4548 use the @code{find} primary @samp{-ok} instead of @samp{-exec}:
4550 @deffn Action -ok command ;
4551 Like @samp{-exec} (@pxref{Single File}), but ask the user first (on
4552 the standard input); if the response does not start with @samp{y} or
4553 @samp{Y}, do not run the command, and return false.
4556 When processing multiple files with a single command, to query the user
4557 you give @code{xargs} the following option. When using this option, you
4558 might find it useful to control the number of files processed per
4559 invocation of the command (@pxref{Limiting Command Size}).
4564 Prompt the user about whether to run each command line and read a line
4565 from the terminal. Only run the command line if the response starts
4566 with @samp{y} or @samp{Y}. Implies @samp{-t}.
4570 @section Delete Files
4572 @deffn Action -delete
4573 Delete files or directories; true if removal succeeded. If the
4574 removal failed, an error message is issued.
4576 The use of the @samp{-delete} action on the command line automatically
4577 turns on the @samp{-depth} option (@pxref{find Expressions}).
4581 @section Adding Tests
4583 You can test for file attributes that none of the @code{find} builtin
4584 tests check. To do this, use @code{xargs} to run a program that filters
4585 a list of files printed by @code{find}. If possible, use @code{find}
4586 builtin tests to pare down the list, so the program run by @code{xargs}
4587 has less work to do. The tests builtin to @code{find} will likely run
4588 faster than tests that other programs perform.
4590 For example, here is a way to print the names of all of the unstripped
4591 binaries in the @file{/usr/local} directory tree. Builtin tests avoid
4592 running @code{file} on files that are not regular files or are not
4596 find /usr/local -type f -perm +a=x | xargs file |
4597 grep 'not stripped' | cut -d: -f1
4601 The @code{cut} program removes everything after the file name from the
4602 output of @code{file}.
4604 @c Idea from Martin Weitzel.
4605 If you want to place a special test somewhere in the middle of a
4606 @code{find} expression, you can use @samp{-exec} to run a program that
4607 performs the test. Because @samp{-exec} evaluates to the exit status of
4608 the executed program, you can write a program (which can be a shell
4609 script) that tests for a special attribute and make it exit with a true
4610 (zero) or false (non-zero) status. It is a good idea to place such a
4611 special test @emph{after} the builtin tests, because it starts a new
4612 process which could be avoided if a builtin test evaluates to false.
4613 Use this method only when @code{xargs} is not flexible enough, because
4614 starting one or more new processes to test each file is slower than
4615 using @code{xargs} to start one process that tests many files.
4617 Here is a shell script called @code{unstripped} that checks whether its
4618 argument is an unstripped binary file:
4622 file $1 | grep 'not stripped' > /dev/null
4625 This script relies on the fact that the shell exits with the status of
4626 the last program it executed, in this case @code{grep}. @code{grep}
4627 exits with a true status if it found any matches, false if not. Here is
4628 an example of using the script (assuming it is in your search path). It
4629 lists the stripped executables in the file @file{sbins} and the
4630 unstripped ones in @file{ubins}.
4633 find /usr/local -type f -perm +a=x \
4634 \( -exec unstripped '@{@}' \; -fprint ubins -o -fprint sbins \)
4637 @node Common Tasks, Databases, Actions, Top
4638 @chapter Common Tasks
4640 The sections that follow contain some extended examples that both give a
4641 good idea of the power of these programs, and show you how to solve
4642 common real-world problems.
4645 * Viewing And Editing::
4648 * Strange File Names::
4649 * Fixing Permissions::
4650 * Classifying Files::
4653 @node Viewing And Editing
4654 @section Viewing And Editing
4656 To view a list of files that meet certain criteria, simply run your file
4657 viewing program with the file names as arguments. Shells substitute a
4658 command enclosed in backquotes with its output, so the whole command
4662 less `find /usr/include -name '*.h' | xargs grep -l mode_t`
4666 You can edit those files by giving an editor name instead of a file
4670 emacs `find /usr/include -name '*.h' | xargs grep -l mode_t`
4673 Because there is a limit to the length of any individual command line,
4674 there is a limit to the number of files that can be handled in this
4675 way. We can get around this difficulty by using xargs like this:
4678 find /usr/include -name '*.h' | xargs grep -l mode_t > todo
4679 xargs --arg-file=todo emacs
4682 Here, @code{xargs} will run @code{emacs} as many times as necessary to
4683 visit all of the files listed in the file @file{todo}.
4688 You can pass a list of files produced by @code{find} to a file archiving
4689 program. GNU @code{tar} and @code{cpio} can both read lists of file
4690 names from the standard input---either delimited by nulls (the safe way)
4691 or by blanks (the lazy, risky default way). To use null-delimited
4692 names, give them the @samp{--null} option. You can store a file archive
4693 in a file, write it on a tape, or send it over a network to extract on
4696 One common use of @code{find} to archive files is to send a list of the
4697 files in a directory tree to @code{cpio}. Use @samp{-depth} so if a
4698 directory does not have write permission for its owner, its contents can
4699 still be restored from the archive since the directory's permissions are
4700 restored after its contents. Here is an example of doing this using
4701 @code{cpio}; you could use a more complex @code{find} expression to
4702 archive only certain files.
4705 find . -depth -print0 |
4706 cpio --create --null --format=crc --file=/dev/nrst0
4709 You could restore that archive using this command:
4712 cpio --extract --null --make-dir --unconditional \
4713 --preserve --file=/dev/nrst0
4716 Here are the commands to do the same things using @code{tar}:
4719 find . -depth -print0 |
4720 tar --create --null --files-from=- --file=/dev/nrst0
4722 tar --extract --null --preserve-perm --same-owner \
4726 @c Idea from Rick Sladkey.
4727 Here is an example of copying a directory from one machine to another:
4730 find . -depth -print0 | cpio -0o -Hnewc |
4731 rsh @var{other-machine} "cd `pwd` && cpio -i0dum"
4735 @section Cleaning Up
4737 @c Idea from Jim Meyering.
4738 This section gives examples of removing unwanted files in various situations.
4739 Here is a command to remove the CVS backup files created when an update
4743 find . -name '.#*' -print0 | xargs -0r rm -f
4746 The command above works, but the following is safer:
4749 find . -name '.#*' -depth -delete
4752 @c Idea from Franc,ois Pinard.
4753 You can run this command to clean out your clutter in @file{/tmp}. You
4754 might place it in the file your shell runs when you log out
4755 (@file{.bash_logout}, @file{.logout}, or @file{.zlogout}, depending on
4756 which shell you use).
4759 find /tmp -depth -user "$LOGNAME" -type f -delete
4762 If your @code{find} command removes directories, you may find that
4763 you get a spurious error message when @code{find} tries to recurse
4764 into a directory that has now been removed. Using the @samp{-depth}
4765 option will normally resolve this problem.
4767 @c Idea from Noah Friedman.
4768 To remove old Emacs backup and auto-save files, you can use a command
4769 like the following. It is especially important in this case to use
4770 null-terminated file names because Emacs packages like the VM mailer
4771 often create temporary file names with spaces in them, like @file{#reply
4772 to David J. MacKenzie<1>#}.
4775 find ~ \( -name '*~' -o -name '#*#' \) -print0 |
4776 xargs --no-run-if-empty --null rm -vf
4779 Removing old files from @file{/tmp} is commonly done from @code{cron}:
4781 @c Idea from Kaveh Ghazi.
4783 find /tmp /var/tmp -not -type d -mtime +3 -delete
4784 find /tmp /var/tmp -depth -mindepth 1 -type d -empty -delete
4787 The second @code{find} command above uses @samp{-depth} so it cleans out
4788 empty directories depth-first, hoping that the parents become empty and
4789 can be removed too. It uses @samp{-mindepth} to avoid removing
4790 @file{/tmp} itself if it becomes totally empty.
4792 @node Strange File Names
4793 @section Strange File Names
4796 @c From: tmatimar@isgtec.com (Ted Timar)
4797 @c Newsgroups: comp.unix.questions,comp.unix.shell,comp.answers,news.answers
4798 @c Subject: Unix - Frequently Asked Questions (2/7) [Frequent posting]
4799 @c Subject: How do I remove a file with funny characters in the filename ?
4800 @c Date: Thu Mar 18 17:16:55 EST 1993
4801 @code{find} can help you remove or rename a file with strange characters
4802 in its name. People are sometimes stymied by files whose names contain
4803 characters such as spaces, tabs, control characters, or characters with
4804 the high bit set. The simplest way to remove such files is:
4807 rm -i @var{some*pattern*that*matches*the*problem*file}
4810 @code{rm} asks you whether to remove each file matching the given
4811 pattern. If you are using an old shell, this approach might not work if
4812 the file name contains a character with the high bit set; the shell may
4813 strip it off. A more reliable way is:
4816 find . -maxdepth 1 @var{tests} -ok rm '@{@}' \;
4820 where @var{tests} uniquely identify the file. The @samp{-maxdepth 1}
4821 option prevents @code{find} from wasting time searching for the file in
4822 any subdirectories; if there are no subdirectories, you may omit it. A
4823 good way to uniquely identify the problem file is to figure out its
4830 Suppose you have a file whose name contains control characters, and you
4831 have found that its inode number is 12345. This command prompts you for
4832 whether to remove it:
4835 find . -maxdepth 1 -inum 12345 -ok rm -f '@{@}' \;
4838 If you don't want to be asked, perhaps because the file name may contain
4839 a strange character sequence that will mess up your screen when printed,
4840 then use @samp{-exec} instead of @samp{-ok}.
4842 If you want to rename the file instead, you can use @code{mv} instead of
4846 find . -maxdepth 1 -inum 12345 -ok mv '@{@}' @var{new-file-name} \;
4849 @node Fixing Permissions
4850 @section Fixing Permissions
4852 Suppose you want to make sure that everyone can write to the directories in a
4853 certain directory tree. Here is a way to find directories lacking either
4854 user or group write permission (or both), and fix their permissions:
4857 find . -type d -not -perm -ug=w | xargs chmod ug+w
4861 You could also reverse the operations, if you want to make sure that
4862 directories do @emph{not} have world write permission.
4864 @node Classifying Files
4865 @section Classifying Files
4868 @c From: martin@mwtech.UUCP (Martin Weitzel)
4869 @c Newsgroups: comp.unix.wizards,comp.unix.questions
4870 @c Subject: Advanced usage of 'find' (Re: Unix security automating script)
4871 @c Date: 22 Mar 90 15:05:19 GMT
4872 If you want to classify a set of files into several groups based on
4873 different criteria, you can use the comma operator to perform multiple
4874 independent tests on the files. Here is an example:
4877 find / -type d \( -perm -o=w -fprint allwrite , \
4878 -perm -o=x -fprint allexec \)
4880 echo "Directories that can be written to by everyone:"
4883 echo "Directories with search permissions for everyone:"
4887 @code{find} has only to make one scan through the directory tree (which
4888 is one of the most time consuming parts of its work).
4890 @node Databases, File Permissions, Common Tasks, Top
4891 @chapter File Name Databases
4893 The file name databases used by @code{locate} contain lists of files
4894 that were in particular directory trees when the databases were last
4895 updated. The file name of the default database is determined when
4896 @code{locate} and @code{updatedb} are configured and installed. The
4897 frequency with which the databases are updated and the directories for
4898 which they contain entries depend on how often @code{updatedb} is run,
4899 and with which arguments.
4901 You can obtain some statistics about the databases by using
4902 @samp{locate --statistics}.
4905 * Database Locations::
4906 * Database Formats::
4907 * Newline Handling::
4911 @node Database Locations
4912 @section Database Locations
4914 There can be multiple file name databases. Users can select which
4915 databases @code{locate} searches using the @code{LOCATE_PATH}
4916 environment variable or a command line option. The system
4917 administrator can choose the file name of the default database, the
4918 frequency with which the databases are updated, and the directories
4919 for which they contain entries. File name databases are updated by
4920 running the @code{updatedb} program, typically nightly.
4922 In networked environments, it often makes sense to build a database at
4923 the root of each filesystem, containing the entries for that filesystem.
4924 @code{updatedb} is then run for each filesystem on the fileserver where
4925 that filesystem is on a local disk, to prevent thrashing the network.
4927 @xref{Invoking updatedb},
4928 for the description of the options to @code{updatedb}, which specify
4929 which directories would each database contain entries for.
4932 @node Database Formats
4933 @section Database Formats
4935 The file name databases contain lists of files that were in particular
4936 directory trees when the databases were last updated. The file name
4937 database format changed starting with GNU @code{locate} version 4.0 to
4938 allow machines with different byte orderings to share the databases. The
4939 new GNU @code{locate} can read both the old and new database formats.
4940 However, old versions of @code{locate} and @code{find} produce incorrect
4941 results if given a new-format database.
4943 If you run @samp{locate --statistics}, the resulting summary indicates
4944 the type of each locate database.
4948 * New Database Format::
4950 * Old Database Format::
4953 @node New Database Format
4954 @subsection New Database Format
4956 @code{updatedb} runs a program called @code{frcode} to
4957 @dfn{front-compress} the list of file names, which reduces the database
4958 size by a factor of 4 to 5. Front-compression (also known as
4959 incremental encoding) works as follows.
4961 The database entries are a sorted list (case-insensitively, for users'
4962 convenience). Since the list is sorted, each entry is likely to share a
4963 prefix (initial string) with the previous entry. Each database entry
4964 begins with an offset-differential count byte, which is the additional
4965 number of characters of prefix of the preceding entry to use beyond the
4966 number that the preceding entry is using of its predecessor. (The
4967 counts can be negative.) Following the count is a null-terminated ASCII
4968 remainder---the part of the name that follows the shared prefix.
4970 If the offset-differential count is larger than can be stored in a byte
4971 (+/-127), the byte has the value 0x80 and the count follows in a 2-byte
4972 word, with the high byte first (network byte order).
4974 Every database begins with a dummy entry for a file called
4975 @file{LOCATE02}, which @code{locate} checks for to ensure that the
4976 database file has the correct format; it ignores the entry in doing the
4979 Databases can not be concatenated together, even if the first (dummy)
4980 entry is trimmed from all but the first database. This is because the
4981 offset-differential count in the first entry of the second and following
4982 databases will be wrong.
4984 In the ouptut of @samp{locate --statistics}, the new database format
4985 is referred to as @samp{LOCATE02}.
4987 @node Sample Database
4988 @subsection Sample Database
4990 Sample input to @code{frcode}:
4991 @c with nulls changed to newlines:
4995 /usr/src/cmd/aardvark.c
4996 /usr/src/cmd/armadillo.c
5000 Length of the longest prefix of the preceding entry to share:
5009 Output from @code{frcode}, with trailing nulls changed to newlines
5010 and count bytes made printable:
5020 (6 = 14 - 8, and -9 = 5 - 14)
5022 @node Old Database Format
5023 @subsection Old Database Format
5025 The old database format is used by Unix @code{locate} and @code{find}
5026 programs and earlier releases of the GNU ones. @code{updatedb} produces
5027 this format if given the @samp{--old-format} option.
5029 @code{updatedb} runs programs called @code{bigram} and @code{code} to
5030 produce old-format databases. The old format differs from the new one
5031 in the following ways. Instead of each entry starting with an
5032 offset-differential count byte and ending with a null, byte values from
5033 0 through 28 indicate offset-differential counts from -14 through 14.
5034 The byte value indicating that a long offset-differential count follows
5035 is 0x1e (30), not 0x80. The long counts are stored in host byte order,
5036 which is not necessarily network byte order, and host integer word size,
5037 which is usually 4 bytes. They also represent a count 14 less than
5038 their value. The database lines have no termination byte; the start of
5039 the next line is indicated by its first byte having a value <= 30.
5041 In addition, instead of starting with a dummy entry, the old database
5042 format starts with a 256 byte table containing the 128 most common
5043 bigrams in the file list. A bigram is a pair of adjacent bytes. Bytes
5044 in the database that have the high bit set are indexes (with the high
5045 bit cleared) into the bigram table. The bigram and offset-differential
5046 count coding makes these databases 20-25% smaller than the new format,
5047 but makes them not 8-bit clean. Any byte in a file name that is in the
5048 ranges used for the special codes is replaced in the database by a
5049 question mark, which not coincidentally is the shell wildcard to match a
5052 The old format therefore can not faithfully store entries with non-ASCII
5053 characters. It therefore should not be used in internationalized
5056 The output of @samp{locate --statistics} will give an incorrect count
5057 of the number of filenames containing newlines or high-bit characters
5058 for old-format databases.
5060 @node Newline Handling
5061 @section Newline Handling
5063 Within the database, filenames are terminated with a null character.
5064 This is the case for both the old and the new format.
5066 When the new database format is being used, the compression technique
5067 used to generate the database though relies on the ability to sort the
5068 list of files before they are presented to @code{frcode}.
5070 If the system's sort command allows its input list of files to be
5071 separated with null characters via the @samp{-z} option, this option
5072 is used and therefore @code{updatedb} and @code{locate} will both
5073 correctly handle filenames containing newlines. If the @code{sort}
5074 command lacks support for this, the list of files is delimited with
5075 the newline character, meaning that parts of filenames containing
5076 newlines will be incorrectly sorted. This can result in both
5077 incorrect matches and incorrect failures to match.
5079 On the other hand, if you are using the old database format, filenames
5080 with embedded newlines are not correctly handled. There is no
5081 technical limitation which enforces this, it's just that the
5082 @code{bigram} program has no been updated to support lists of
5083 filenames separated by nulls.
5085 So, if you are using the new database format (this is the default) and
5086 your system uses GNU @code{find}, newlines will be correctly handled
5087 at all times. Otherwise, newlines may not be correctly handled.
5089 @node File Permissions, Reference, Databases, Top
5090 @chapter File Permissions
5094 @node Reference, Security Considerations, File Permissions, Top
5097 Below are summaries of the command line syntax for the programs
5098 discussed in this manual.
5103 * Invoking updatedb::
5107 @node Invoking find, Invoking locate, , Reference
5108 @section Invoking @code{find}
5111 find @r{[-H] [-L] [-P]} @r{[}@var{file}@dots{}@r{]} @r{[}@var{expression}@r{]}
5114 @code{find} searches the directory tree rooted at each file name
5115 @var{file} by evaluating the @var{expression} on each file it finds in
5118 The options @samp{-H}, @samp{-L} or @samp{-P} may be specified at the
5119 start of the command line (if none of these is specified, @samp{-P} is
5120 assumed). The arguments after these are a list of files or
5121 directories that should be searched.
5123 This list of files to search is followed by a list of expressions
5124 describing the files we wish to search for. The first part of the
5125 expression is recognised by the fact that it begins with @samp{-},
5126 @samp{(}, @samp{)}, @samp{,}, or @samp{!}. Any arguments after it are
5127 the rest of the expression. If no paths are given, the current
5128 directory is used. If no expression is given, the expression
5129 @samp{-print} is used.
5131 @code{find} exits with status 0 if all files are processed successfully,
5132 greater than 0 if errors occur.
5134 Three options can precede the list of path names. They determine the
5135 way that symbolic links are handled.
5139 Never follow symbolic links (this is the default), except in the case
5140 of the @samp{-xtype} predicate.
5142 Always follow symbolic links, except in the case of the @samp{-xtype}
5145 Follow symbolic links specified in the list of paths to search, or
5146 which are otherwise specified on the command line.
5149 If @code{find} would follow a symbolic link, but cannot for any reason
5150 (for example, because it has insufficient permissions or the link is
5151 broken), it falls back on using the properties of the symbolic link
5152 itself. @ref{Symbolic Links} for a more complete description of how
5153 symbolic links are handled.
5155 @xref{Primary Index}, for a summary of all of the tests, actions, and
5156 options that the expression can contain. If the expression is
5157 missing, @samp{-print} is assumed.
5161 @code{find} also recognizes two options for administrative use:
5165 Print a summary of the command-line argument format and exit.
5167 Print the version number of @code{find} and exit.
5172 * Warning Messages::
5176 @node Warning Messages,,, Invoking find
5177 @subsection Warning Messages
5179 If there is an error on the @code{find} command line, an error message
5180 is normally issued. However, there are some usages that are
5181 inadvisable but which @code{find} should still accept. Under these
5182 circumstances, @code{find} may issue a warning message. By default,
5183 warnings are enabled only if @code{find} is being run interactively
5184 (specifically, if the standard input is a terminal). Warning messages
5185 can be controlled explicitly by the use of options on the command
5190 Issue warning messages where appropriate.
5192 Do not issue warning messages.
5195 These options take effect at the point on the command line where they
5196 are specified. Therefore if you specify @samp{-nowarn} at the end of
5197 the command line, you will not see warning messages for any problems
5198 occurring before that. The warning messages affected by the above
5199 options are triggered by:
5203 Use of the @samp{-d} option which is deprecated; please use
5204 @samp{-depth} instead, since the latter is POSIX-compliant.
5206 Use of the @samp{-ipath} option which is deprecated; please use
5207 @samp{-iwholename} instead.
5209 Specifying an option (for example @samp{-mindepth}) after a non-option
5210 (for example @samp{-type} or @samp{-print}) on the command line.
5214 The default behaviour above is designed to work in that way so that
5215 existing shell scripts which use such constructs don't generate
5216 spurious errors, but people will be made aware of the problem.
5218 Some warning messages are issued for less common or more serious
5219 problems, and so cannot be turned off:
5223 Use of an unrecognised backslash escape sequence with @samp{-fprintf}
5225 Use of an unrecognised formatting directive with @samp{-fprintf}
5228 @node Invoking locate, Invoking updatedb, Invoking find, Reference
5229 @section Invoking @code{locate}
5232 locate @r{[}@var{option}@dots{}@r{]} @var{pattern}@dots{}
5236 @item --database=@var{path}
5237 @itemx -d @var{path}
5238 Instead of searching the default file name database, search the file
5239 name databases in @var{path}, which is a colon-separated list of
5240 database file names. You can also use the environment variable
5241 @code{LOCATE_PATH} to set the list of database files to search. The
5242 option overrides the environment variable if both are used.
5246 Only print out such names which currently exist (instead of such names
5247 which existed when the database was created).
5248 Note that this may slow down the program a lot, if there are many matches
5253 Ignore case distinctions in both the pattern and the file names.
5257 Results are separated with the ASCII NUL character rather than the
5258 newline character. To get the full benefit of the use of this option,
5259 use the new locate database format (that is the default anyway).
5263 Just print the number of results, not the results themselves.
5267 Limit the number of results printed to N. If you use the
5268 @samp{--count} option, the value printed will never be larger than
5272 The specified pattern is matched against the whole name of the file in
5273 the locate database. If the pattern contains metacharacters, it must
5274 match exactly. If not, it must match part of the whole file name.
5275 This is the default behaviour.
5278 The specified pattern is matched against just the last component of
5279 the name of the file in the locate database. This last component is
5280 also called the ``base name''. For example, the base name of
5281 @file{/tmp/mystuff/foo.old.c} is @file{foo.old.c}. If the pattern
5282 contains metacharacters, it must match exactly. If not, it must match
5283 part of the whole file name.
5286 Print some summary information for each locate database. No search is
5290 Print a summary of the options to @code{locate} and exit.
5293 Print the version number of @code{locate} and exit.
5296 @node Invoking updatedb, Invoking xargs, Invoking locate, Reference
5297 @section Invoking @code{updatedb}
5300 updatedb @r{[}@var{option}@dots{}@r{]}
5304 @item --findoptions='@var{OPTION}@dots{}'
5305 Global options to pass on to @code{find}.
5306 The environment variable @code{FINDOPTIONS} also sets this value.
5309 @item --localpaths='@var{path}@dots{}'
5310 Non-network directories to put in the database.
5311 Default is @file{/}.
5313 @item --netpaths='@var{path}@dots{}'
5314 Network (NFS, AFS, RFS, etc.) directories to put in the database.
5315 The environment variable @code{NETPATHS} also sets this value.
5318 @item --prunepaths='@var{path}@dots{}'
5319 Directories to omit from the database, which would otherwise be included.
5320 The environment variable @code{PRUNEPATHS} also sets this value.
5321 Default is @file{/tmp /usr/tmp /var/tmp /afs}.
5323 @item --prunefs='@var{path}@dots{}'
5324 File systems to omit from the database, which would otherwise be included.
5325 Note that files are pruned when a file system is reached;
5326 Any file system mounted under an undesired file system will be
5328 The environment variable @code{PRUNEFS} also sets this value.
5329 Default is @file{nfs NFS proc}.
5331 @item --output=@var{dbfile}
5332 The database file to build.
5333 Default is system-dependent, but typically @file{/usr/local/var/locatedb}.
5335 @item --localuser=@var{user}
5336 The user to search the non-network directories as, using @code{su}.
5337 Default is to search the non-network directories as the current user.
5338 You can also use the environment variable @code{LOCALUSER} to set this user.
5340 @item --netuser=@var{user}
5341 The user to search network directories as, using @code{su}.
5342 Default is @code{daemon}.
5343 You can also use the environment variable @code{NETUSER} to set this user.
5346 Generate a locate database in the old format, for compatibility with
5347 versions of @code{locate} other than GNU @code{locate}. Using this
5348 option means that @code{locate} will not be able to properly handle
5349 non-ASCII characters in filenames (that is, filenames containing
5350 characters which have the eighth bit set, such as many of the
5351 characters from the ISO-8859-1 character set).
5353 Print a summary of the command-line argument format and exit.
5355 Print the version number of @code{updatedb} and exit.
5358 @node Invoking xargs, , Invoking updatedb, Reference
5359 @section Invoking @code{xargs}
5362 xargs @r{[}@var{option}@dots{}@r{]} @r{[}@var{command} @r{[}@var{initial-arguments}@r{]}@r{]}
5365 @code{xargs} exits with the following status:
5371 if any invocation of the command exited with status 1-125
5373 if the command exited with status 255
5375 if the command is killed by a signal
5377 if the command cannot be run
5379 if the command is not found
5381 if some other error occurred.
5385 @item --arg-file@r{=@var{inputfile}}
5386 @itemx -a @r{=@var{inputfile}}
5387 Read names from the file @var{inputfile} instead of standard input.
5391 Input filenames are terminated by a null character instead of by
5392 whitespace, and the quotes and backslash are not special (every
5393 character is taken literally). Disables the end of file string, which
5394 is treated like any other argument.
5396 @item --eof@r{[}=@var{eof-str}@r{]}
5397 @itemx -e@r{[}@var{eof-str}@r{]}
5398 Set the end of file string to @var{eof-str}. If the end of file string
5399 occurs as a line of input, the rest of the input is ignored. If
5400 @var{eof-str} is omitted, there is no end of file string. If this
5401 option is not given, the end of file string defaults to @samp{_}.
5404 Print a summary of the options to @code{xargs} and exit.
5406 @item --replace@r{[}=@var{replace-str}@r{]}
5407 @itemx -i@r{[}@var{replace-str}@r{]}
5408 Replace occurrences of @var{replace-str} in the initial arguments with
5409 names read from standard input. Also, unquoted blanks do not
5410 terminate arguments; instead, the input is split at newlines only.
5411 If @var{replace-str} is omitted, it defaults to @samp{@{@}}
5412 (like for @samp{find -exec}). Implies @samp{-x} and @samp{-l 1}.
5414 @item --max-lines@r{[}=@var{max-lines}@r{]}
5415 @itemx -l@r{[}@var{max-lines}@r{]}
5416 Use at most @var{max-lines} nonblank input lines per command line;
5417 @var{max-lines} defaults to 1 if omitted. Trailing blanks cause an
5418 input line to be logically continued on the next input line, for the
5419 purpose of counting the lines. Implies @samp{-x}.
5421 @item --max-args=@var{max-args}
5422 @itemx -n @var{max-args}
5423 Use at most @var{max-args} arguments per command line. Fewer than
5424 @var{max-args} arguments will be used if the size (see the @samp{-s}
5425 option) is exceeded, unless the @samp{-x} option is given, in which case
5426 @code{xargs} will exit.
5430 Prompt the user about whether to run each command line and read a line
5431 from the terminal. Only run the command line if the response starts
5432 with @samp{y} or @samp{Y}. Implies @samp{-t}.
5434 @item --no-run-if-empty
5436 If the standard input does not contain any nonblanks, do not run the
5437 command. By default, the command is run once even if there is no input.
5439 @item --max-chars=@var{max-chars}
5440 @itemx -s @var{max-chars}
5441 Use at most @var{max-chars} characters per command line, including the
5442 command and initial arguments and the terminating nulls at the ends of
5443 the argument strings.
5447 Print the command line on the standard error output before executing
5451 Print the version number of @code{xargs} and exit.
5455 Exit if the size (see the @samp{-s} option) is exceeded.
5458 @item --max-procs=@var{max-procs}
5459 @itemx -P @var{max-procs}
5460 Run up to @var{max-procs} processes at a time; the default is 1. If
5461 @var{max-procs} is 0, @code{xargs} will run as many processes as
5465 @node Security Considerations, Error Messages, Reference, Top
5466 @chapter Security Considerations
5468 Security considerations are important if you are using @code{find} or
5469 @code{xargs} to search for or process files that don't belong to you
5470 or over which other people have control. Security considerations
5471 relating to @code{locate} may also apply if you have files which you
5472 may not want others to see.
5474 In general, the most severe forms of security problems affecting
5475 @code{find} and related programs are where third parties can bring
5476 about a situation where those programs allow them to do something
5477 they would normally not be able to do. This is called @emph{privilege
5478 elevation}. This might include deleting files they would not normally
5479 be able to delete. It is also common for the system to periodically
5480 invoke @code{find} for housekeeping purposes. These invocations of
5481 @code{find} are particularly problematic from a security point of view
5482 as these are often invoked by the superuser and search the whole file
5483 system hierarchy. The severity of any associated problem depends on
5484 what the system is going to do with the output of @code{find}.
5487 * Levels of Risk:: What is your level of exposure to security problems?
5488 * Security Considerations for find:: Security problems with find
5489 * Security Considerations for xargs:: Security problems with xargs
5490 * Security Considerations for locate:: Security problems with locate
5491 * Security Summary:: That was all very complex, what does it boil down to?
5495 @node Levels of Risk
5496 @section Levels of Risk
5498 There are some security risks inherent in the use of @code{find},
5499 @code{xargs} and (to a lesser extent) @code{locate}. The severity of
5500 these risks depends on what sort of system you are using:
5504 Multi-user systems where you do not control (or trust) the other
5505 users, and on which you execute @code{find}, including areas where
5506 those other users can manipulate the filesystem (for example beneath
5507 @file{/home} or @file{/tmp}).
5510 Systems where the actions of other users can create filenames chosen
5511 by them, but to which they don't have access while @code{find} is
5512 being run. This access might include leaving programs running (shell
5513 background jobs, @code{at} or @code{cron} tasks, for example). On
5514 these sorts of systems, carefully written commands (avoiding use of
5515 @samp{-print} for example) should not expose you to a high degree of
5516 risk. Most systems fall into this category.
5519 Systems to which untrusted parties do not have access, cannot create
5520 filenames of their own choice (even remotely) and which contain no
5521 security flaws which might enable an untrusted third party to gain
5522 access. Most systems do not fall into this category because there are
5523 many ways in which external parties can affect the names of files that
5524 are created on your system. The system on which I am writing this for
5525 example automatically downloads software updates from the Internet;
5526 the names of the files in which these updates exist are chosen by
5527 third parties@footnote{Of course, I trust these parties to a large
5528 extent anyway, because I install software provided by them; I choose
5529 to trust them in this way, and that's a deliberate choice}.
5532 In the discussion above, ``risk'' denotes the likelihood that someone
5533 can cause @code{find}, @code{xargs}, @code{locate} or some other
5534 program which is controlled by them to do something you did not
5535 intend. The levels of risk suggested do not take any account of the
5536 consequences of this sort of event. That is, if you operate a ``low
5537 risk'' type system, but the consequences of a security problem are
5538 disastrous, then you should still give serious thought to all the
5539 possible security problems, many of which of course will not be
5540 discussed here -- this section of the manual is intended to be
5541 informative but not comprehensive or exhaustive.
5543 If you are responsible for the operation of a system where the
5544 consequences of a security problem could be very important, you should
5548 @item Define a security policy which defines who is allowed to do what
5550 @item Seek competent advice on how to enforce your policy, detect
5551 breaches of that policy, and take account of any potential problems
5552 that might fall outside the scope of your policy
5556 @node Security Considerations for find
5557 @section Security Considerations for find
5560 Some of the actions @code{find} might take have a direct effect;
5561 these include @code{-exec} and @code{-delete}. However, it is also
5562 common to use @code{-print} explicitly or implicitly, and so if
5563 @code{find} produces the wrong list of filenames, that can also be a
5564 security problem; consider the case for example where @code{find} is
5565 producing a list of files to be deleted.
5567 We normally assume that the @code{find} command line expresses the
5568 file selection criteria and actions that the user had in mind -- that
5569 is, the command line is ``trusted'' data.
5571 From a security analysis point of view, the output of @code{find}
5572 should be correct; that is, the output should contain only the names
5573 of those files which meet the user's criteria specified on the command
5574 line. This applies for the @code{-exec} and @code{-delete} actions;
5575 one can consider these to be part of the output.
5577 On the other hand, the contents of the filesystem can be manipulated
5578 by other people, and hence we regard this as ``untrusted'' data. This
5579 implies that the @code{find} command line is a filter which converts
5580 the untrusted contents of the filesystem into a correct list of output
5583 The filesystem will in general change while @code{find} is searching
5584 it; in fact, most of the potential security problems with @code{find}
5585 relate to this issue in some way.
5587 @subsection Race Conditions
5588 Race conditions are a general class of security problem where the
5589 relative ordering of actions taken by @code{find} (for example) and
5590 something else are important@footnote{This is more or less the
5591 definition of the term ``race condition''} .
5593 Typically, an attacker might move or rename files or directories in
5594 the hope that an action might be taken against a a file which was not
5595 normally intended to be affected. Alternatively, this sort of attack
5596 might be intended to persuade @code{find} to search part of the
5597 filesystem which would not normally be included in the search
5598 (defeating the @code{-prune} action for example).
5600 @subsubsection Changing the Current Working Directory
5601 As find searches the file system, it finds subdirectories and then
5602 searches within them by changing its working directory. First,
5603 @code{find} notices a subdirectory. It then decides if that
5604 subdirectory meets the criteria for being searched; that is, any
5605 @samp{-xdev} or @samp{-prune} expressions are taken into account. The
5606 @code{find} program will then change working directory using the
5607 @code{chdir()} system call and proceed to search the directory.
5609 A race condition attack might take the form that once the checks
5610 relevant to @samp{-xdev} and @samp{-prune} have been done, an attacker
5611 might rename the directory that was being considered, and put in its
5612 place a symbolic link that actually points somewhere else. The
5613 @code{find} command would then issue the @code{chdir()} system call,
5614 changing its working directory to the destination of the symbolic link
5615 (@code{chdir()} will always dereference symbolic links). This
5616 manipulation leaves @code{find} with a working directory chosen by an
5617 attacker, bypassing any protection apparently provided by @samp{-xdev}
5618 and @samp{-prune}, and any protection provided by being able to
5619 @emph{not} list particular directories on the @code{find} command
5620 line. This form of attack is particularly problematic if the attacker
5621 can predict when the @code{find} command will be run, as is the case
5622 with @code{cron} tasks for example.
5624 GNU @code{find} has specific safeguards to prevent this general class
5625 of problem. Each time @code{find} changes directory, it examines the
5626 directory it is about to move to, issues the @code{chdir()} system
5627 call, and then checks that it has ended up in the subdirectory it
5628 expected. If not, an error message is issued and @code{find} exits
5629 immediately. This prevents filesystem manipulation attacks from
5630 persuading @code{find} to search parts of the filesystem it did not
5633 Where an automounter is in use, it can be the case that the use of the
5634 @code{chdir()} system call can itself cause a new filesystem to be
5635 mounted at that point. This will cause @code{find}'s security check
5636 to fail. However, this does not normally represent a security problem
5637 (since the automounter configuration is normally set up by the system
5638 administrator). Therefore, if the @code{chdir()} sanity check fails,
5639 @code{find} will check to see if a new filesystem has been mounted at
5640 the current directory; if so, @code{find} will issue a warning message
5644 @subsubsection Race Conditions with -exec
5646 The @samp{-exec} action causes another program to be run. It is
5647 passed the name of the file which is being considered at the time.
5648 The invoked program will then - normally - perform some action on that
5649 file. Once again, there is a race condition which can be exploited
5650 here. We shall take as a specific example the command
5653 find /tmp -path /tmp/umsp/passwd -exec /bin/rm
5656 In this simple example, we are identifying just one file to be deleted
5657 and invoking @code{/bin/rm} to delete it. A problem exists because
5658 there is a time gap between the point where @code{find} decides that
5659 it needs to process the @samp{-exec} action and the point where the
5660 @code{/bin/rm} command actually issues the @code{unlink()} system
5661 call. Within this time period, an attacker can rename the
5662 @file{/tmp/umsp} directory, replacing it with a symbolic link to
5663 @file{/etc}. There is no way for @code{/bin/rm} to determine that it
5664 is working on the same file that @code{find} had in mind. Once the
5665 symbolic link is in place, the attacker has persuaded @code{find} to
5666 cause the deletion of the @file{/etc/passwd} file, which is not the
5667 effect intended by the command which was actually invoked.
5669 One possible defence against this type of attack is to modify the
5670 behaviour of @samp{-exec} so that the @code{/bin/rm} command is run
5671 with the argument @file{./passwd} and a suitable choice of working
5672 directory. This would allow the normal sanity check that @code{find}
5673 performs to protect against this form of attack too. Unfortunately,
5674 this strategy cannot be used as the POSIX standard specifies that the
5675 current working directory for commands invoked via @samp{-exec} must
5676 be the same as the current working directory from which @code{find}
5677 was invoked. This means that the @samp{-exec} action is inherently
5678 insecure and can't be fixed.
5680 GNU @code{find} implements a more secure variant of the @samp{-exec}
5681 action, @samp{-execdir}@footnote{at the time of writing -execdir is
5682 not yet implemented, but is planned}. The @samp{-execdir} action
5683 ensures that it is not necessary to dereference subdirectories to
5684 process target files. The current directory used to invoke programs
5685 is the same as the directory in which the file to be processed exists
5686 (@file{/tmp/umsp} in our example, and only the basename of the file to
5687 be processed is passed to the invoked command, with a @samp{./}
5688 prepended (giving @file{./passwd} in our example).
5691 @subsubsection Race Conditions with -print and -print0
5693 The @samp{-print} and @samp{-print0} actions can be used to produce a
5694 list of files matching some criteria, which can then be used with some
5695 other command, perhaps with @code{xargs}. Unfortunately, this means
5696 that there is an unavoidable time gap between @code{find} deciding
5697 that one or more files meet its criteria and the relevant command
5698 being executed. For this reason, the @samp{-print} and @samp{-print0}
5699 actions are just as insecure as @samp{-exec}.
5701 In fact, since the construction
5704 find .... -print | xargs ....
5707 does not cope correctly with newlines or other ``white space'' in
5708 filenames, and copes poorly with filenames containing quotes, the
5709 @samp{-print} action is less secure even than @samp{-print0}.
5712 @comment node-name, next, previous, up
5713 @comment @node Security Considerations for xargs
5714 @node Security Considerations for xargs
5715 @section Security Considerations for @code{xargs}
5717 The description of the race conditions affecting the @samp{-print}
5718 action of @code{find} shows that @code{xargs} cannot be secure if it
5719 is possible for an attacker to modify a filesystem after @code{find}
5720 has started but before @code{xargs} has completed all its actions.
5722 However, there are other security issues that exist even if it is not
5723 possible for an attacker to have access to the filesystem in real
5724 time. Firstly, if it is possible for an attacker to create files with
5725 names of their own choice on the filesystem, then @code{xargs} is
5726 insecure unless the @samp{-0} option is used. If a file with the name
5727 @file{/home/someuser/foo/bar\n/etc/passwd} exists (assume that
5728 @samp{\n} stands for a newline character), then @code{find ... -print}
5729 can be persuaded to print three separate lines:
5732 /home/someuser/foo/bar
5737 If it finds a blank line in the input, @code{xargs} will ignore it.
5738 Therefore, if some action is to be taken on the basis of this list of
5739 files, the @file{/etc/passwd} file would be included even if this was
5740 not the intent of the person running find. There are circumstances in
5741 which an attacker can use this to their advantage. The same
5742 consideration applies to filenames containing ordinary spaces rather
5743 than newlines, except that of course the list of filenames will no
5744 longer contain an ``extra'' newline.
5746 This problem is an unavoidable consequence of the default behaviour of
5747 the @code{xargs} command, which is specified by the POSIX standard.
5748 The only ways to avoid this problem are either to avoid all use of
5749 @code{xargs} in favour for example of @samp{find -exec} or (where
5750 available) @samp{find -execdir}, or to use the @samp{-0} option, which
5751 ensures that @code{xargs} considers filenames to be separated by ASCII
5752 NUL characters rather than whitespace. However, useful though this
5753 option is, the POSIX standard does not make it mandatory.
5755 @comment node-name, next, previous, up
5756 @node Security Considerations for locate
5757 @section Security Considerations for @code{locate}
5759 It is fairly unusual for the output of @code{locate} to be fed into
5760 another command. However, if this were to be done, this would raise
5761 the same set of security issues as the use of @samp{find ... -print}.
5762 Although the problems relating to whitespace in filenames can be
5763 resolved by using @code{locate}'s @samp{-0} option, this still leaves
5764 the race condition problems associated with @samp{find ... -print0}.
5765 There is no way to avoid these problems in the case of @code{locate}.
5767 @node Security Summary
5770 Where untrusted parties can create files on the system, or affect the
5771 names of files that are created, all uses for @code{find},
5772 @code{locate} and @code{xargs} have known security problems except the
5776 @item Informational use only
5777 Uses where the programs are used to prepare lists of filenames upon which no further action will ever be taken.
5780 Use of the @samp{-delete} action to delete files which meet
5784 Use of the @samp{-execdir} action where the @env{PATH}
5785 environment variable contains directories which contain only trusted
5789 Please note that the @samp{-execdir} option is not yet implemented.
5792 @comment node-name, next, previous, up
5793 @node Error Messages, Primary Index, Security Considerations, Top
5794 @chapter Error Messages
5796 This section describes some of the error messages you might get from
5797 @code{find}, @code{xargs}, or @code{locate}, explains them and in some
5798 cases provides advice as to what you should do about this.
5800 This manual is written in English. The GNU findutils software
5801 features translated error messages for many languages. For this
5802 reason where possible we try to make the error messages produced by
5803 the programs self-explanatory. This approach avoids asking people to
5804 figure out which English-language error message the test they actually
5805 saw might correspond to. Error messages which are self-explanatory
5806 will not normally be described or discussed in this document. For
5807 those messages which are discussed in this document, only the
5808 English-language version of the message will be listed.
5811 * Error Messages From find::
5812 * Error Messages From xargs::
5813 * Error Messages From locate::
5814 * Error Messages From updatedb::
5817 @node Error Messages From find, Error Messages From xargs, , Error Messages
5818 @section Error Messages From find
5821 @item invalid predicate `-foo'
5822 This means that the @code{find} command line included something that
5823 started with a dash or other special character. The @code{find}
5824 program tried to interpret this as a test, action or option, but
5825 didn't recognise it. If you intended it to be a test, check what you
5826 specified against the documentation. If, on the other hand, the
5827 string is the name of a file which has been expanded from a wildcard
5828 (for example because you have a @samp{*} on the command line),
5829 consider using @samp{./*} or just @samp{.} instead.
5831 @item unexpected extra predicate
5832 This usually happens if you have an extra bracket on the command line
5833 (for example @samp{find . -print \)}).
5835 @item Warning: filesystem /path/foo has recently been mounted
5836 @itemx Warning: filesystem /path/foo has recently been unmounted
5837 These messages might appear when @code{find} moves into a directory
5838 and finds that the device number and inode are different to what it
5839 expected them to be. If the directory @code{find} has moved into is
5840 on an NFS filesystem, it will not issue this message, because
5841 @code{automount} frequently mounts new filesystems on directories as
5842 you move into them (that is how it knows you want to use the
5843 filesystem). So, if you do see this message, be wary --
5844 @code{automount} may not have been responsible. Consider the
5845 possibility that someone else is manipulating the filesystem while
5846 @code{find} is running. Some people might do this in order to mislead
5847 @code{find} or persuade it to look at one set of files when it thought
5848 it was looking at another set.
5850 @item /path/foo changed during execution of find (old device number 12345, new device number 6789, filesystem type is <whatever>) [ref XXX]
5851 This message is issued when @code{find} changes directory and ends up
5852 somewhere it didn't expect to be. This happens in one of two
5853 circumstances. Firstly this happens when ``automount'' does its thing
5854 on a system where @code{find} doesn't know how to determine what the
5855 current set of mounted filesystems is@footnote{To do this, @code{find}
5856 requires to be able to use @code{getmntent()} - check the
5857 @file{config.h} file for HAVE_GETMNTENT, which should be #defined to
5858 1. If HAVE_GETMNTENT is not set, consider submitting a problem report
5859 to @email{bug-findutils@@gnu.org}, because @code{find} needs to be
5860 able to figure out how to enumerate the mounted devices on your
5863 Secondly, this can happen when the device number of a directory
5864 appears to change during a change of current directory, but
5865 @code{find} is moving up the filesystem hierarchy rather than down it.
5866 In order to prevent @code{find} wandering off into some unexpected
5867 part of the filesystem, we stop it at this point.
5869 @item Don't know how to use getmntent() to read `/etc/mtab'. This is a bug.
5870 This message is issued when a problem similar to the above occurs on a
5871 system where @code{find} doesn't know how to figure out the current
5872 list of mount points. Ask for help on @email{bug-findutils@@gnu.org}.
5874 @item /path/foo/bar changed during execution of find (old inode number 12345, new inode number 67893, filesystem type is <whatever>) [ref XXX]"),
5875 This message is issued when @code{find} changes directory and
5876 discovers that the inode number of that directory once it's got there
5877 is different to the inode number that it obtained when it examined the
5878 directory some time previously. This normally means that while
5879 @code{find} has been deep in a directory hierarchy doing something
5880 time consuming, somebody has moved the one of the parent directories
5881 to another location in the same filesystem. This may have been done
5882 maliciously, or may not. In any case, @code{find} stops at this point
5883 in order to avoid traversing parts of the filesystem that it wasn't
5884 intended to. You can use @code{ls -li} or @code{find /path -inum
5885 12345 -o -inum 67893} to find out more about what has happened.
5887 @item sanity check of the fnmatch() library function failed.
5888 Please submit a bug report. You may well be asked questions about
5889 your system, and if you compiled the @code{findutils} code yourself,
5890 you should keep your copy of the build tree around. The likely
5891 explanation is that your system has a buggy implementation of
5892 @code{fnmatch} that looks enough like the GNU version to fool
5893 @code{configure}, but which doesn't work properly.
5896 This normally happens if you use the @code{-exec} action or a
5897 something similar (@code{-ok} and so forth) but the system has run out
5898 of free process slots. This is either because the system is very busy
5899 and the system has reached its maximum process limit, or because you
5900 have a resource limit in place and you've reached it. Check the
5901 system for runaway processes (if @code{ps} still works). Some process
5902 slots are normally reserved for use by @samp{root}.
5904 @item some-program terminated by signal 99
5905 Some program which was launched via @code{-exec} or similar was killed
5906 with a fatal signal. This is just an advisory message.
5911 @node Error Messages From xargs, Error Messages From locate, Error Messages From find, Error Messages
5912 @section Error Messages From xargs
5915 @item environment is too large for exec
5916 This message means that you have so many environment variables set
5917 (or such large values for them) that there is no room within the
5918 system-imposed limits on program command-line argument length to
5919 invoke any program. I'm sure you did this deliberately. Please try
5920 unsetting some environment variables, or exiting the current shell.
5922 @item can not fit single argument within argument list size limit
5923 You are using the @samp{-i} option and @code{xargs} doesn't have
5924 enough space to build a command line because it has read in a really
5925 large item and it doesn't fit. You can probably work around this
5926 problem with the @samp{-s} option, but the default size is pretty
5927 large. You must be trying pretty hard to break @code{xargs}.
5930 See the description of the similar message for @code{find}.
5932 @item <program>: exited with status 255; aborting
5933 When a command run by @code{xargs} exits with status 255, @code{xargs}
5934 is supposed to stop. If this is not what you intended, wrap the
5935 program you are trying to invoke in a shell script which doesn't
5938 @item <program>: terminated by signal 99
5939 See the description of the similar message for @code{find}.
5942 @node Error Messages From locate, Error Messages From updatedb, Error Messages From xargs, Error Messages
5943 @section Error Messages From locate
5946 @item warning: database `/usr/local/var/locatedb' is more than 8 days old
5947 The @code{locate} program relies on a database which is periodically
5948 built by the @code{updatedb} program. That hasn't happened in a long
5949 time. To fix this problem, run @code{updatedb} manually. This can
5950 often happen on systems that are generally not left on, so the periodic
5951 ``cron'' task which normally does this doesn't get a chance to run.
5953 @item locate database `/usr/local/var/locatedb' is corrupt or invalid
5954 This should not happen. Re-run @code{updatedb}. If that works, but
5955 @code{locate} still produces this error, run @code{locate --version}
5956 and @code{updatedb --version}. These should produce the same output.
5957 If not, you are using a mixed toolset; check your @samp{$PATH}
5958 environment variable and your shell aliases (if you have any). If
5959 both programs claim to be GNU versions, this is a bug; all versions of
5960 these programs should interoperate without problem. Ask for help on
5961 @email{bug-findutils@@gnu.org}.
5965 @node Error Messages From updatedb, , Error Messages From locate, Error Messages
5966 @section Error Messages From updatedb
5968 The @code{updatedb} program (and the programs it invokes) do issue
5969 error messages, but none of them seem to me to be candidates for
5970 guidance. If you are having a problem understanding one of these, ask
5971 for help on @email{bug-findutils@@gnu.org}.
5973 @node Primary Index, , Error Messages, Top
5974 @unnumbered @code{find} Primary Index
5976 This is a list of all of the primaries (tests, actions, and options)
5977 that make up @code{find} expressions for selecting files. @xref{find
5978 Expressions}, for more information on expressions.
5985 @comment Accept some transatlantic usage - original manual written by
5986 @comment an American.
5987 @comment LocalWords: behavior optimize recognize recognizes
5988 @comment LocalWords: internationalized
5989 @comment Accept some neologisms...
5990 @comment LocalWords: builtin automount automounter toolset unsetting
5992 @comment texi related words used by Emacs' spell checker ispell.el
5993 @comment LocalWords: texinfo setfilename settitle setchapternewpage
5994 @comment LocalWords: iftex finalout ifinfo DIR titlepage vskip pt
5995 @comment LocalWords: filll dir samp dfn noindent xref pxref
5996 @comment LocalWords: var deffn texi deffnx itemx emph asis
5997 @comment LocalWords: findex smallexample subsubsection cindex
5998 @comment LocalWords: dircategory direntry itemize
6000 @comment other words used by Emacs' spell checker ispell.el
6001 @comment LocalWords: README fred updatedb xargs Plett Rendell akefile
6002 @comment LocalWords: args grep Filesystems fo foo fOo wildcards iname
6003 @comment LocalWords: ipath regex iregex expr fubar regexps findutils
6004 @comment LocalWords: metacharacters macs sr sc inode lname ilname
6005 @comment LocalWords: sysdep noleaf ls inum xdev filesystems usr atime
6006 @comment LocalWords: ctime mtime amin cmin mmin al daystart Sladkey rm
6007 @comment LocalWords: anewer cnewer bckw rf xtype uname gname uid gid
6008 @comment LocalWords: nouser nogroup chown chgrp perm ch maxdepth
6009 @comment LocalWords: mindepth cpio src CD AFS statted stat fstype ufs
6010 @comment LocalWords: nfs tmp mfs printf fprint dils rw djm Nov lwall
6011 @comment LocalWords: POSIXLY fls fprintf strftime locale's EDT GMT AP
6012 @comment LocalWords: EST diff perl backquotes sprintf Falstad Oct cron
6013 @comment LocalWords: eg vmunix mkdir afs allexec allwrite ARG bigram
6014 @comment LocalWords: bigrams cd chmod comp crc CVS dbfile dum eof
6015 @comment LocalWords: fileserver filesystem fn frcode Ghazi Hnewc iXX
6016 @comment LocalWords: joeuser Kaveh localpaths localuser LOGNAME
6017 @comment LocalWords: Meyering mv netpaths netuser nonblank nonblanks
6018 @comment LocalWords: ois ok Pinard printindex proc procs prunefs
6019 @comment LocalWords: prunepaths pwd RFS rmadillo rmdir rsh sbins str
6020 @comment LocalWords: su Timar ubins ug unstripped vf VM Weitzel Youngman
6021 @comment LocalWords: wildcard zlogout basename execdir wholename iwholename
6022 @comment LocalWords: timestamp timestamps Solaris FreeBSD OpenBSD POSIX