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 * Primary Index:: The components of @code{find} expressions.
96 @node Introduction, Finding Files, Top, Top
99 This manual shows how to find files that meet criteria you specify, and
100 how to perform various actions on the files that you find. The
101 principal programs that you use to perform these tasks are @code{find},
102 @code{locate}, and @code{xargs}. Some of the examples in this manual
103 use capabilities specific to the GNU versions of those programs.
105 GNU @code{find} was originally written by Eric Decker, with enhancements
106 by David MacKenzie, Jay Plett, and Tim Wood. GNU @code{xargs} was
107 originally written by Mike Rendell, with enhancements by David
108 MacKenzie. GNU @code{locate} and its associated utilities were
109 originally written by James Woods, with enhancements by David MacKenzie.
110 The idea for @samp{find -print0} and @samp{xargs -0} came from Dan
111 Bernstein. The current maintainer of GNU findutils (and this manual) is
112 James Youngman. Many other people have contributed bug fixes, small
113 improvements, and helpful suggestions. Thanks!
115 Mail suggestions and bug reports for these programs to
116 @code{bug-findutils@@gnu.org}. Please include the version
117 number, which you can get by running @samp{find --version}.
128 For brevity, the word @dfn{file} in this manual means a regular file, a
129 directory, a symbolic link, or any other kind of node that has a
130 directory entry. A directory entry is also called a @dfn{file name}. A
131 file name may contain some, all, or none of the directories in a path
132 that leads to the file. These are all examples of what this manual
133 calls ``file names'':
140 /usr/local/include/termcap.h
143 A @dfn{directory tree} is a directory and the files it contains, all of
144 its subdirectories and the files they contain, etc. It can also be a
145 single non-directory file.
147 These programs enable you to find the files in one or more directory
152 have names that contain certain text or match a certain pattern;
154 are links to certain files;
156 were last used during a certain period of time;
158 are within a certain size range;
160 are of a certain type (regular file, directory, symbolic link, etc.);
162 are owned by a certain user or group;
164 have certain access permissions;
166 contain text that matches a certain pattern;
168 are within a certain depth in the directory tree;
170 or some combination of the above.
173 Once you have found the files you're looking for (or files that are
174 potentially the ones you're looking for), you can do more to them than
175 simply list their names. You can get any combination of the files'
176 attributes, or process the files in many ways, either individually or in
177 groups of various sizes. Actions that you might want to perform on the
178 files you have found include, but are not limited to:
188 change access permissions
193 This manual describes how to perform each of those tasks, and more.
198 The principal programs used for making lists of files that match given
199 criteria and running commands on them are @code{find}, @code{locate},
200 and @code{xargs}. An additional command, @code{updatedb}, is used by
201 system administrators to create databases for @code{locate} to use.
203 @code{find} searches for files in a directory hierarchy and prints
204 information about the files it found. It is run like this:
207 find @r{[}@var{file}@dots{}@r{]} @r{[}@var{expression}@r{]}
211 Here is a typical use of @code{find}. This example prints the names of
212 all files in the directory tree rooted in @file{/usr/src} whose name
213 ends with @samp{.c} and that are larger than 100 Kilobytes.
215 find /usr/src -name '*.c' -size +100k -print
218 @code{locate} searches special file name databases for file names that
219 match patterns. The system administrator runs the @code{updatedb}
220 program to create the databases. @code{locate} is run like this:
223 locate @r{[}@var{option}@dots{}@r{]} @var{pattern}@dots{}
227 This example prints the names of all files in the default file name
228 database whose name ends with @samp{Makefile} or @samp{makefile}. Which
229 file names are stored in the database depends on how the system
230 administrator ran @code{updatedb}.
232 locate '*[Mm]akefile'
235 The name @code{xargs}, pronounced EX-args, means ``combine arguments.''
236 @code{xargs} builds and executes command lines by gathering together
237 arguments it reads on the standard input. Most often, these arguments
238 are lists of file names generated by @code{find}. @code{xargs} is run
242 xargs @r{[}@var{option}@dots{}@r{]} @r{[}@var{command} @r{[}@var{initial-arguments}@r{]}@r{]}
246 The following command searches the files listed in the file
247 @file{file-list} and prints all of the lines in them that contain the
250 xargs grep typedef < file-list
253 @node find Expressions
254 @section @code{find} Expressions
256 The expression that @code{find} uses to select files consists of one or
257 more @dfn{primaries}, each of which is a separate command line argument
258 to @code{find}. @code{find} evaluates the expression each time it
259 processes a file. An expression can contain any of the following types
264 affect overall operation rather than the processing of a specific file;
266 return a true or false value, depending on the file's attributes;
268 have side effects and return a true or false value; and
270 connect the other arguments and affect when and whether they are
274 You can omit the operator between two primaries; it defaults to
275 @samp{-and}. @xref{Combining Primaries With Operators}, for ways to
276 connect primaries into more complex expressions. If the expression
277 contains no actions other than @samp{-prune}, @samp{-print} is performed
278 on all files for which the entire expression is true (@pxref{Print File
281 Options take effect immediately, rather than being evaluated for each
282 file when their place in the expression is reached. Therefore, for
283 clarity, it is best to place them at the beginning of the expression.
285 Many of the primaries take arguments, which immediately follow them in
286 the next command line argument to @code{find}. Some arguments are file
287 names, patterns, or other strings; others are numbers. Numeric
288 arguments can be specified as
292 for greater than @var{n},
294 for less than @var{n},
299 @node Finding Files, Actions, Introduction, Top
300 @chapter Finding Files
302 By default, @code{find} prints to the standard output the names of the
303 files that match the given criteria. @xref{Actions}, for how to get more
304 information about the matching files.
318 * Combining Primaries With Operators::
324 Here are ways to search for files whose name matches a certain pattern.
325 @xref{Shell Pattern Matching}, for a description of the @var{pattern}
326 arguments to these tests.
328 Each of these tests has a case-sensitive version and a case-insensitive
329 version, whose name begins with @samp{i}. In a case-insensitive
330 comparison, the patterns @samp{fo*} and @samp{F??} match the file names
331 @file{Foo}, @samp{FOO}, @samp{foo}, @samp{fOo}, etc.
334 * Base Name Patterns::
335 * Full Name Patterns::
336 * Fast Full Name Search::
337 * Shell Pattern Matching:: Wildcards used by these programs.
340 @node Base Name Patterns
341 @subsection Base Name Patterns
343 @deffn Test -name pattern
344 @deffnx Test -iname pattern
345 True if the base of the file name (the path with the leading directories
346 removed) matches shell pattern @var{pattern}. For @samp{-iname}, the
347 match is case-insensitive. To ignore a whole directory tree, use
348 @samp{-prune} (@pxref{Directories}). As an example, to find Texinfo
349 source files in @file{/usr/local/doc}:
352 find /usr/local/doc -name '*.texi'
356 Patterns for @samp{-name} and @samp{-iname} will match a filename with
357 a leading @samp{.}. For example the command @samp{find /tmp -name
358 \*bar} will match the file @file{/tmp/.foobar}.
361 @node Full Name Patterns
362 @subsection Full Name Patterns
364 @deffn Test -wholename pattern
365 @deffnx Test -iwholename pattern
366 True if the entire file name, starting with the command line argument
367 under which the file was found, matches shell pattern @var{pattern}.
368 For @samp{-iwholename}, the match is case-insensitive. To ignore a whole
369 directory tree, use @samp{-prune} rather than checking every file in the
370 tree (@pxref{Directories}).
373 @deffn Test -path pattern
374 @deffnx Test -ipath pattern
375 These tests are deprecated, but work as for @samp{-wholename} and @samp{-iwholename},
376 respectively. The @samp{-ipath} test is a GNU extension, but @samp{-path} is also
377 provided by HP-UX @code{find}.
380 @deffn Test -regex expr
381 @deffnx Test -iregex expr
382 True if the entire file name matches regular expression @var{expr}.
383 This is a match on the whole path, not a search. For example, to match
384 a file named @file{./fubar3}, you can use the regular expression
385 @samp{.*bar.} or @samp{.*b.*3}, but not @samp{b.*r3}. @xref{Regexps, ,
386 Syntax of Regular Expressions, emacs, The GNU Emacs Manual}, for a
387 description of the syntax of regular expressions. For @samp{-iregex},
388 the match is case-insensitive.
391 @node Fast Full Name Search
392 @subsection Fast Full Name Search
394 To search for files by name without having to actually scan the
395 directories on the disk (which can be slow), you can use the
396 @code{locate} program. For each shell pattern you give it,
397 @code{locate} searches one or more databases of file names and displays
398 the file names that contain the pattern. @xref{Shell Pattern Matching},
399 for details about shell patterns.
401 If a pattern is a plain string---it contains no
402 metacharacters---@code{locate} displays all file names in the database
403 that contain that string. If a pattern contains
404 metacharacters, @code{locate} only displays file names that match the
405 pattern exactly. As a result, patterns that contain metacharacters
406 should usually begin with a @samp{*}, and will most often end with one
407 as well. The exceptions are patterns that are intended to explicitly
408 match the beginning or end of a file name.
410 If you only want @code{locate} to match against the last component of
411 the filenames (the ``base name'' of the files) you can use the
412 @samp{--basename} option. The opposite behaviour is the default, but
413 can be selected explicitly by using the option @samp{--wholename}.
420 is almost equivalent to
422 find @var{directories} -name @var{pattern}
425 where @var{directories} are the directories for which the file name
426 databases contain information. The differences are that the
427 @code{locate} information might be out of date, and that @code{locate}
428 handles wildcards in the pattern slightly differently than @code{find}
429 (@pxref{Shell Pattern Matching}).
431 The file name databases contain lists of files that were on the system
432 when the databases were last updated. The system administrator can
433 choose the file name of the default database, the frequency with which
434 the databases are updated, and the directories for which they contain
437 Here is how to select which file name databases @code{locate} searches.
438 The default is system-dependent.
441 @item --database=@var{path}
443 Instead of searching the default file name database, search the file
444 name databases in @var{path}, which is a colon-separated list of
445 database file names. You can also use the environment variable
446 @code{LOCATE_PATH} to set the list of database files to search. The
447 option overrides the environment variable if both are used.
450 @node Shell Pattern Matching
451 @subsection Shell Pattern Matching
453 @code{find} and @code{locate} can compare file names, or parts of file
454 names, to shell patterns. A @dfn{shell pattern} is a string that may
455 contain the following special characters, which are known as
456 @dfn{wildcards} or @dfn{metacharacters}.
458 You must quote patterns that contain metacharacters to prevent the shell
459 from expanding them itself. Double and single quotes both work; so does
460 escaping with a backslash.
464 Matches any zero or more characters.
467 Matches any one character.
470 Matches exactly one character that is a member of the string
471 @var{string}. This is called a @dfn{character class}. As a shorthand,
472 @var{string} may contain ranges, which consist of two characters with a
473 dash between them. For example, the class @samp{[a-z0-9_]} matches a
474 lowercase letter, a number, or an underscore. You can negate a class by
475 placing a @samp{!} or @samp{^} immediately after the opening bracket.
476 Thus, @samp{[^A-Z@@]} matches any character except an uppercase letter
480 Removes the special meaning of the character that follows it. This
481 works even in character classes.
484 In the @code{find} tests that do shell pattern matching (@samp{-name},
485 @samp{-wholename}, etc.), wildcards in the pattern will match a @samp{.}
486 at the beginning of a file name. This is also the case for
487 @code{locate}. Thus, @samp{find -name '*macs'} will match a file
488 named @file{.emacs}, as will @samp{locate '*macs'}.
490 Slash characters have no special significance in the shell pattern
491 matching that @code{find} and @code{locate} do, unlike in the shell, in
492 which wildcards do not match them. Therefore, a pattern @samp{foo*bar}
493 can match a file name @samp{foo3/bar}, and a pattern @samp{./sr*sc} can
494 match a file name @samp{./src/misc}.
496 If you want to locate some files with the @samp{locate} command but
497 don't need to see the full list you can use the @samp{--limit} option
498 to see just a small number of results, or the @samp{--count} option to
499 display only the total number of matches.
504 There are two ways that files can be linked together. @dfn{Symbolic
505 links} are a special type of file whose contents are a portion of the
506 name of another file. @dfn{Hard links} are multiple directory entries
507 for one file; the file names all have the same index node (@dfn{inode})
516 @subsection Symbolic Links
518 Symbolic links are names that reference other files. GNU @code{find}
519 will handle symbolic links in one of two ways; firstly, it can
520 dereference the links for you - this means that if it comes across a
521 symblic link, it examines the file that the link points to, in order
522 to see if it matches the criteria you have specified. Secondly, it
523 can check the link itself in case you might be looking for
524 the actual link. If the file that the symbolic link points to is also
525 within the directory hierarchy you are searching with the @code{find}
526 command, you may not see a great deal of difference between these two
529 By default, @code{find} examines symbolic links themselves when it
530 finds them (and, if it later comes across the linked-to file, it will
531 examine that, too). If you would prefer @code{find} to dereference
532 the links and examine the file that each link points to, specify the
533 @samp{-L} option to @code{find}. You can explicitly specify the
534 default behaviour by using the @samp{-P} option. The @samp{-H}
535 option is a half-way-between option which ensures that any symbolic
536 links listed on the command line are dereferenced, but other symbolic
539 Symbolic links are different to ``hard links'' in the sense that you
540 need permissions upon the linked-to file in order to be able to
541 dereference the link. This can mean that even if you specify the
542 @samp{-L} option, find may not be able to determine the properties of
543 the file that the link points to (because you don't have sufficient
544 permissions). In this situation, @samp{find} uses the properties of
545 the link itself. This also occurs if a symbolic link exists but
546 points to a file that is missing.
548 The options controlling the behaviour of @code{find} with respect to
549 links are as follows :-
553 @code{find} does not dereference symbolic links at all. This is the
554 default behaviour. This option must be specified before any of the
555 path names on the command line.
557 @code{find} does not dereference symbolic links (except in the case of
558 file names on the command line, which are dereferenced). If a
559 symbolic link cannot be dereferenced, the information for the symbolic
560 link itself is used. This option must be specified before any of the
561 path names on the command line.
563 @code{find} dereferences symbolic links where possible, and where this
564 is not possible it uses the properties of the symbolic link itself.
565 This option must be specified before any of the path names on the
566 command line. Use of this option also implies the same behaviour as
567 the @samp{-noleaf} option. If you later use the @samp{-H} or
568 @samp{-P} options, this does not turn off @samp{-noleaf}.
571 This option forms part of the ``expression'' and must be specified
572 after the path names, but it is otherwise equivalent to @samp{-L}.
575 The following differences in behavior occur when the @samp{-L} option
580 @code{find} follows symbolic links to directories when searching
583 @samp{-lname} and @samp{-ilname} always return false (unless they
584 happen to match broken symbolic links).
586 @samp{-type} reports the types of the files that symbolic links point
589 Implies @samp{-noleaf} (@pxref{Directories}).
592 If the @samp{-L} option or the @samp{-H} option is used,
593 the filenames used as arguments to @samp{-newer}, @samp{-anewer}, and
594 @samp{-cnewer} are dereferenced and the timestamp from the pointed-to
595 file is used instead (if possible -- otherwise the timestamp from the
596 symbolic link is used).
598 @deffn Test -lname pattern
599 @deffnx Test -ilname pattern
600 True if the file is a symbolic link whose contents match shell pattern
601 @var{pattern}. For @samp{-ilname}, the match is case-insensitive.
602 @xref{Shell Pattern Matching}, for details about the @var{pattern}
603 argument. If the @samp{-L} option is in effect, this test will always
604 fail for symbolic links unless they are broken. So, to list any
605 symbolic links to @file{sysdep.c} in the current directory and its
606 subdirectories, you can do:
609 find . -lname '*sysdep.c'
614 @subsection Hard Links
616 To find hard links, first get the inode number of the file whose links
617 you want to find. You can learn a file's inode number and the number of
618 links to it by running @samp{ls -i} or @samp{find -ls}. If the file has
619 more than one link, you can search for the other links by passing that
620 inode number to @samp{-inum}. Add the @samp{-xdev} option if you are
621 starting the search at a directory that has other filesystems mounted on
622 it, such as @file{/usr} on many systems. Doing this saves needless
623 searching, since hard links to a file must be on the same filesystem.
627 File has inode number @var{n}. The @samp{+} and @samp{-} qualifiers
628 also work, though these are rarely useful.
631 You can also search for files that have a certain number of links, with
632 @samp{-links}. Directories normally have at least two hard links; their
633 @file{.} entry is the second one. If they have subdirectories, each of
634 those also has a hard link called @file{..} to its parent directory.
637 File has @var{n} hard links.
640 @deffn Test -links +n
641 File has more than @var{n} hard links.
644 @deffn Test -links -n
645 File has fewer than @var{n} hard links.
651 Each file has three time stamps, which record the last time that certain
652 operations were performed on the file:
656 access (read the file's contents)
658 change the status (modify the file or its attributes)
660 modify (change the file's contents)
663 You can search for files whose time stamps are within a certain age
664 range, or compare them to other time stamps.
668 * Comparing Timestamps::
672 @subsection Age Ranges
674 These tests are mainly useful with ranges (@samp{+@var{n}} and
678 @deffnx Test -ctime n
679 @deffnx Test -mtime n
680 True if the file was last accessed (or its status changed, or it was
681 modified) @var{n}*24 hours ago.
687 True if the file was last accessed (or its status changed, or it was
688 modified) @var{n} minutes ago. These tests provide finer granularity of
689 measurement than @samp{-atime} et al. For example, to list files in
690 @file{/u/bill} that were last read from 2 to 6 minutes ago:
693 find /u/bill -amin +2 -amin -6
697 @deffn Option -daystart
698 Measure times from the beginning of today rather than from 24 hours ago.
699 So, to list the regular files in your home directory that were modified
703 find ~ -daystart -type f -mtime 1
707 The @samp{-daystart} option is unlike most other options in that it
708 has an effect on the way that other tests are performed. The affected
709 tests are @samp{-amin}, @samp{-cmin}, @samp{-mmin}, @samp{-atime},
710 @samp{-ctime} and @samp{-mtime}.
712 @node Comparing Timestamps
713 @subsection Comparing Timestamps
715 As an alternative to comparing timestamps to the current time, you can
716 compare them to another file's timestamp. That file's timestamp could
717 be updated by another program when some event occurs. Or you could set
718 it to a particular fixed date using the @code{touch} command. For
719 example, to list files in @file{/usr} modified after February 1 of the
722 @c Idea from Rick Sladkey.
724 touch -t 02010000 /tmp/stamp$$
725 find /usr -newer /tmp/stamp$$
729 @deffn Test -anewer file
730 @deffnx Test -cnewer file
731 @deffnx Test -newer file
732 True if the file was last accessed (or its status changed, or it was
733 modified) more recently than @var{file} was modified. These tests are
734 affected by @samp{-follow} only if @samp{-follow} comes before them on
735 the command line. @xref{Symbolic Links}, for more information on
736 @samp{-follow}. As an example, to list any files modified since
737 @file{/bin/sh} was last modified:
740 find . -newer /bin/sh
745 True if the file was last accessed @var{n} days after its status was
746 last changed. Useful for finding files that are not being used, and
747 could perhaps be archived or removed to save disk space.
753 @deffn Test -size n@r{[}bckwMG@r{]}
754 True if the file uses @var{n} units of space, rounding up. The units
755 are 512-byte blocks by default, but they can be changed by adding a
756 one-character suffix to @var{n}:
760 512-byte blocks (never 1024)
764 kilobytes (1024 bytes)
773 The `b' suffix always considers blocks to be 512 bytes. This is not
774 affected by the setting (or non-setting) of the POSIXLY_CORRECT
775 environment variable. This behaviour is different to the behaviour of
776 the @samp{-ls} action). If you want to use 1024-byte units, use the
779 The number can be prefixed with a `+' or a `-'. A plus sign indicates
780 that the test should succeed if the file uses at least @var{n} units
781 of storage (this is the way I normally use this test) and a minus sign
782 indicates that the test should succeed if the file uses less than
783 @var{n} units of storage. There is no `=' prefix, because that's the
786 The size does not count indirect blocks, but it does count blocks in
787 sparse files that are not actually allocated. This handling of sparse
788 files differs from the output of the @samp{%k} and @samp{%b} format
789 specifiers for the @samp{-printf} predicate.
794 True if the file is empty and is either a regular file or a directory.
795 This might make it a good candidate for deletion. This test is useful
796 with @samp{-depth} (@pxref{Directories}) and @samp{-delete}
797 (@pxref{Single File}).
804 True if the file is of type @var{c}:
808 block (buffered) special
810 character (unbuffered) special
827 The same as @samp{-type} unless the file is a symbolic link. For
828 symbolic links: if @samp{-follow} has not been given, true if the file
829 is a link to a file of type @var{c}; if @samp{-follow} has been given,
830 true if @var{c} is @samp{l}. In other words, for symbolic links,
831 @samp{-xtype} checks the type of the file that @samp{-type} does not
832 check. @xref{Symbolic Links}, for more information on @samp{-follow}.
838 @deffn Test -user uname
839 @deffnx Test -group gname
840 True if the file is owned by user @var{uname} (belongs to group @var{gname}).
841 A numeric ID is allowed.
846 True if the file's numeric user ID (group ID) is @var{n}. These tests
847 support ranges (@samp{+@var{n}} and @samp{-@var{n}}), unlike
848 @samp{-user} and @samp{-group}.
852 @deffnx Test -nogroup
853 True if no user corresponds to the file's numeric user ID (no group
854 corresponds to the numeric group ID). These cases usually mean that the
855 files belonged to users who have since been removed from the system.
856 You probably should change the ownership of such files to an existing
857 user or group, using the @code{chown} or @code{chgrp} program.
863 @xref{File Permissions}, for information on how file permissions are
864 structured and how to specify them.
866 @deffn Test -perm mode
868 file's permissions are exactly @var{mode} (which can be numeric or symbolic).
869 Symbolic modes use mode 0 as a point of departure.
870 If @var{mode} starts with @samp{-}, true if
871 @emph{all} of the permissions set in @var{mode} are set for the file;
872 permissions not set in @var{mode} are ignored.
873 If @var{mode} starts with @samp{+}, true if
874 @emph{any} of the permissions set in @var{mode} are set for the file;
875 permissions not set in @var{mode} are ignored.
881 To search for files based on their contents, you can use the @code{grep}
882 program. For example, to find out which C source files in the current
883 directory contain the string @samp{thing}, you can do:
889 If you also want to search for the string in files in subdirectories,
890 you can combine @code{grep} with @code{find} and @code{xargs}, like
894 find . -name '*.[ch]' | xargs grep -l thing
897 The @samp{-l} option causes @code{grep} to print only the names of files
898 that contain the string, rather than the lines that contain it. The
899 string argument (@samp{thing}) is actually a regular expression, so it
900 can contain metacharacters. This method can be refined a little by
901 using the @samp{-r} option to make @code{xargs} not run @code{grep} if
902 @code{find} produces no output, and using the @code{find} action
903 @samp{-print0} and the @code{xargs} option @samp{-0} to avoid
904 misinterpreting files whose names contain spaces:
907 find . -name '*.[ch]' -print0 | xargs -r -0 grep -l thing
910 For a fuller treatment of finding files whose contents match a pattern,
911 see the manual page for @code{grep}.
916 Here is how to control which directories @code{find} searches, and how
917 it searches them. These two options allow you to process a horizontal
918 slice of a directory tree.
920 @deffn Option -maxdepth levels
921 Descend at most @var{levels} (a non-negative integer) levels of
922 directories below the command line arguments. @samp{-maxdepth 0} means
923 only apply the tests and actions to the command line arguments.
926 @deffn Option -mindepth levels
927 Do not apply any tests or actions at levels less than @var{levels} (a
928 non-negative integer). @samp{-mindepth 1} means process all files
929 except the command line arguments.
933 Process each directory's contents before the directory itself. Doing
934 this is a good idea when producing lists of files to archive with
935 @code{cpio} or @code{tar}. If a directory does not have write
936 permission for its owner, its contents can still be restored from the
937 archive since the directory's permissions are restored after its contents.
941 This is a deprecated synonym for @samp{-depth}, for compatibility with
942 Mac OS X, FreeBSD and OpenBSD. The @samp{-depth} option is a POSIX
943 feature, so it is better to use that.
947 If @samp{-depth} is not given, true; do not descend into the current
948 directory. If @samp{-depth} is given, false; no effect. @samp{-prune}
949 only affects tests and actions that come after it in the expression, not
950 those that come before.
952 For example, to skip the directory @file{src/emacs} and all files and
953 directories under it, and print the names of the other files found:
956 find . -wholename './src/emacs' -prune -o -print
961 Exit immediately with return value zero. No child proceses will be
962 left running, but no more paths specified on the command line will be
963 processed. For example, @code{find /tmp/foo /tmp/bar -print -quit}
964 will print only @samp{/tmp/foo}.
967 @deffn Option -noleaf
968 Do not optimize by assuming that directories contain 2 fewer
969 subdirectories than their hard link count. This option is needed when
970 searching filesystems that do not follow the Unix directory-link
971 convention, such as CD-ROM or MS-DOS filesystems or AFS volume mount
972 points. Each directory on a normal Unix filesystem has at least 2 hard
973 links: its name and its @file{.} entry. Additionally, its
974 subdirectories (if any) each have a @file{..} entry linked to that
975 directory. When @code{find} is examining a directory, after it has
976 statted 2 fewer subdirectories than the directory's link count, it knows
977 that the rest of the entries in the directory are non-directories
978 (@dfn{leaf} files in the directory tree). If only the files' names need
979 to be examined, there is no need to stat them; this gives a significant
980 increase in search speed.
983 @deffn Option -ignore_readdir_race
984 If a file disappears after its name has been read from a directory but
985 before @code{find} gets around to examining the file with @code{stat},
986 don't issue an error message. If you don't specify this option, an
987 error message will be issued. This option can be useful in system
988 scripts (cron scripts, for example) that examine areas of the
989 filesystem that change frequently (mail queues, temporary directories,
990 and so forth), because this scenario is common for those sorts of
991 directories. Completely silencing error messages from @code{find} is
992 undesirable, so this option neatly solves the problem. There is no
993 way to search one part of the filesystem with this option on and part
994 of it with this option off, though.
997 @deffn Option -noignore_readdir_race
998 This option reverses the effect of the @samp{-ignore_readdir_race} option.
1003 @section Filesystems
1005 A @dfn{filesystem} is a section of a disk, either on the local host or
1006 mounted from a remote host over a network. Searching network
1007 filesystems can be slow, so it is common to make @code{find} avoid them.
1009 There are two ways to avoid searching certain filesystems. One way is
1010 to tell @code{find} to only search one filesystem:
1013 @deffnx Option -mount
1014 Don't descend directories on other filesystems. These options are synonyms.
1017 The other way is to check the type of filesystem each file is on, and
1018 not descend directories that are on undesirable filesystem types:
1020 @deffn Test -fstype type
1021 True if the file is on a filesystem of type @var{type}. The valid
1022 filesystem types vary among different versions of Unix; an incomplete
1023 list of filesystem types that are accepted on some version of Unix or
1026 ext2 ext3 proc sysfs ufs 4.2 4.3 nfs tmp mfs S51K S52K
1028 You can use @samp{-printf} with the @samp{%F} directive to see the types
1029 of your filesystems. The @samp{%D} directive shows the device number.
1030 @xref{Print File Information}. @samp{-fstype} is
1031 usually used with @samp{-prune} to avoid searching remote filesystems
1032 (@pxref{Directories}).
1035 @node Combining Primaries With Operators
1036 @section Combining Primaries With Operators
1038 Operators build a complex expression from tests and actions.
1039 The operators are, in order of decreasing precedence:
1042 @item @asis{( @var{expr} )}
1044 Force precedence. True if @var{expr} is true.
1046 @item @asis{! @var{expr}}
1047 @itemx @asis{-not @var{expr}}
1050 True if @var{expr} is false.
1052 @item @asis{@var{expr1 expr2}}
1053 @itemx @asis{@var{expr1} -a @var{expr2}}
1054 @itemx @asis{@var{expr1} -and @var{expr2}}
1057 And; @var{expr2} is not evaluated if @var{expr1} is false.
1059 @item @asis{@var{expr1} -o @var{expr2}}
1060 @itemx @asis{@var{expr1} -or @var{expr2}}
1063 Or; @var{expr2} is not evaluated if @var{expr1} is true.
1065 @item @asis{@var{expr1} , @var{expr2}}
1067 List; both @var{expr1} and @var{expr2} are always evaluated. True if
1068 @var{expr2} is true. The value of @var{expr1} is discarded. This
1069 operator lets you do multiple independent operations on one traversal,
1070 without depending on whether other operations succeeded.
1073 @code{find} searches the directory tree rooted at each file name by
1074 evaluating the expression from left to right, according to the rules of
1075 precedence, until the outcome is known (the left hand side is false for
1076 @samp{-and}, true for @samp{-or}), at which point @code{find} moves on
1077 to the next file name.
1079 There are two other tests that can be useful in complex expressions:
1089 @node Actions, Common Tasks, Finding Files, Top
1092 There are several ways you can print information about the files that
1093 match the criteria you gave in the @code{find} expression. You can
1094 print the information either to the standard output or to a file that
1095 you name. You can also execute commands that have the file names as
1096 arguments. You can use those commands as further filters to select files.
1100 * Print File Information::
1106 @node Print File Name
1107 @section Print File Name
1109 @deffn Action -print
1110 True; print the full file name on the standard output, followed by a
1114 @deffn Action -fprint file
1115 True; print the full file name into file @var{file}, followed by a
1116 newline. If @var{file} does not exist when @code{find} is run, it is
1117 created; if it does exist, it is truncated to 0 bytes. The file names
1118 @file{/dev/stdout} and @file{/dev/stderr} are handled specially; they
1119 refer to the standard output and standard error output, respectively.
1122 @node Print File Information
1123 @section Print File Information
1126 True; list the current file in @samp{ls -dils} format on the standard
1127 output. The output looks like this:
1130 204744 17 -rw-r--r-- 1 djm staff 17337 Nov 2 1992 ./lwall-quotes
1137 The inode number of the file. @xref{Hard Links}, for how to find files
1138 based on their inode number.
1141 the number of blocks in the file. The block counts are of 1K blocks,
1142 unless the environment variable @code{POSIXLY_CORRECT} is set, in which
1143 case 512-byte blocks are used. @xref{Size}, for how to find files based
1147 The file's type and permissions. The type is shown as a dash for a
1148 regular file; for other file types, a letter like for @samp{-type} is
1149 used (@pxref{Type}). The permissions are read, write, and execute for
1150 the file's owner, its group, and other users, respectively; a dash means
1151 the permission is not granted. @xref{File Permissions}, for more details
1152 about file permissions. @xref{Permissions}, for how to find files based
1153 on their permissions.
1156 The number of hard links to the file.
1159 The user who owns the file.
1165 The file's size in bytes.
1168 The date the file was last modified.
1171 The file's name. @samp{-ls} quotes non-printable characters in the file
1172 names using C-like backslash escapes.
1176 @deffn Action -fls file
1177 True; like @samp{-ls} but write to @var{file} like @samp{-fprint}
1178 (@pxref{Print File Name}).
1181 @deffn Action -printf format
1182 True; print @var{format} on the standard output, interpreting @samp{\}
1183 escapes and @samp{%} directives. Field widths and precisions can be
1184 specified as with the @code{printf} C function. Format flags (like
1185 @samp{#} for example) mnay not work as you expect because many of the
1186 fields, even numeric ones, are printed with %s. This means though
1187 that the format flag @samp{-} will work; it forces left-alignment of
1188 the field. Unlike @samp{-print}, @samp{-printf} does not add a
1189 newline at the end of the string. If you want a newline at the end of
1190 the string, add a @samp{\n}.
1193 @deffn Action -fprintf file format
1194 True; like @samp{-printf} but write to @var{file} like @samp{-fprint}
1195 (@pxref{Print File Name}).
1200 * Format Directives::
1207 The escapes that @samp{-printf} and @samp{-fprintf} recognize are:
1215 Stop printing from this format immediately and flush the output.
1227 A literal backslash (@samp{\}).
1229 The character whose ASCII code is NNN (octal).
1232 A @samp{\} character followed by any other character is treated as an
1233 ordinary character, so they both are printed, and a warning message is
1234 printed to the standard error output (because it was probably a typo).
1236 @node Format Directives
1237 @subsection Format Directives
1239 @samp{-printf} and @samp{-fprintf} support the following format
1240 directives to print information about the file being processed. The C
1241 @code{printf} function, field width and precision specifiers are
1242 supported, as applied to string (%s) types. That is, you can specify
1243 "minimum field width"."maximum field width" for each directive.
1244 Format flags (like @samp{#} for example) mnay not work as you expect
1245 because many of the fields, even numeric ones, are printed with %s.
1246 The format flag @samp{-} does work; it forces left-alignment of the
1249 @samp{%%} is a literal percent sign. A @samp{%} character followed by
1250 an unrecognised character (i.e. not a known directive or printf field
1251 width and precision specifier), is discarded (but the unrecognised character
1252 is printed), and a warning message is printed to the standard error output
1253 (because it was probably a typo).
1257 * Ownership Directives::
1259 * Location Directives::
1261 * Formatting Flags::
1264 @node Name Directives
1265 @subsubsection Name Directives
1270 File's name (not the absolute path name, but the name of the file as
1271 it was encountered by find - that is, as a relative path from one of
1272 the starting points).
1274 File's name with any leading directories removed (only the last element).
1277 Leading directories of file's name (all but the last element and the
1281 File's name with the name of the command line argument under which
1282 it was found removed from the beginning.
1285 Command line argument under which file was found.
1289 @node Ownership Directives
1290 @subsubsection Ownership Directives
1295 File's group name, or numeric group ID if the group has no name.
1298 @c TODO: Needs to support # flag and 0 flag
1299 File's numeric group ID.
1302 File's user name, or numeric user ID if the user has no name.
1305 @c TODO: Needs to support # flag
1306 File's numeric user ID.
1308 @c full support, including # and 0.
1309 File's permissions (in octal). If you always want to have a leading
1310 zero on the number, use the '#' format flag, for example '%#m'.
1313 @node Size Directives
1314 @subsubsection Size Directives
1318 Amount of disk space occupied by the file, measured in 1K blocks
1319 (rounded up). This can be less than the length of the file if
1320 it is a sparse file (that is, it has ``holes'').
1322 File's size in 512-byte blocks (rounded up). This also can be less
1323 than the length of the file, if the file is sparse.
1325 File's size in bytes.
1328 @node Location Directives
1329 @subsubsection Location Directives
1333 File's depth in the directory tree (depth below a file named on the
1334 command line, not depth below the root directory). Files named on the
1335 command line have a depth of 0. Subdirectories immediately below them
1336 have a depth of 1, and so on.
1338 The device number on which the file exists (the @code{st_dev} field of
1339 @code{struct stat}), in decimal.
1341 Type of the filesystem the file is on; this value can be used for
1342 @samp{-fstype} (@pxref{Directories}).
1344 Object of symbolic link (empty string if file is not a symbolic link).
1346 File's inode number (in decimal).
1348 Number of hard links to file.
1350 Type of the file as used with @samp{-type}. If the file is a symbolic
1351 link, @samp{l} will be printed.
1353 Type of the file as used with @samp{-type}. If the file is a symbolic
1354 link, it is dereferenced. If the file is a broken symbolic link,
1355 @samp{N} is printed.
1359 @node Time Directives
1360 @subsubsection Time Directives
1362 Some of these directives use the C @code{ctime} function. Its output
1363 depends on the current locale, but it typically looks like
1366 Wed Nov 2 00:42:36 1994
1371 File's last access time in the format returned by the C @code{ctime} function.
1373 File's last access time in the format specified by @var{k}
1374 (@pxref{Time Formats}).
1376 File's last status change time in the format returned by the C @code{ctime}
1379 File's last status change time in the format specified by @var{k}
1380 (@pxref{Time Formats}).
1382 File's last modification time in the format returned by the C @code{ctime}
1385 File's last modification time in the format specified by @var{k}
1386 (@pxref{Time Formats}).
1390 @subsection Time Formats
1392 Below are the formats for the directives @samp{%A}, @samp{%C}, and
1393 @samp{%T}, which print the file's timestamps. Some of these formats
1394 might not be available on all systems, due to differences in the C
1395 @code{strftime} function between systems.
1400 * Combined Time Formats::
1403 @node Time Components
1404 @subsubsection Time Components
1406 The following format directives print single components of the time.
1420 time zone (e.g., EDT), or nothing if no time zone is determinable
1426 seconds since Jan. 1, 1970, 00:00 GMT.
1429 @node Date Components
1430 @subsubsection Date Components
1432 The following format directives print single components of the date.
1436 locale's abbreviated weekday name (Sun..Sat)
1438 locale's full weekday name, variable length (Sunday..Saturday)
1441 locale's abbreviated month name (Jan..Dec)
1443 locale's full month name, variable length (January..December)
1447 day of month (01..31)
1451 day of year (001..366)
1453 week number of year with Sunday as first day of week (00..53)
1455 week number of year with Monday as first day of week (00..53)
1459 last two digits of year (00..99)
1462 @node Combined Time Formats
1463 @subsubsection Combined Time Formats
1465 The following format directives print combinations of time and date
1470 time, 12-hour (hh:mm:ss [AP]M)
1472 time, 24-hour (hh:mm:ss)
1474 locale's time representation (H:M:S)
1476 locale's date and time (Sat Nov 04 12:02:33 EST 1989)
1480 locale's date representation (mm/dd/yy)
1482 Date and time, separated by '+', for example `2004-04-28+22:22:05'.
1483 The time is given in the current timezone (which may be affected by
1484 setting the TZ environment variable). This is a GNU extension.
1487 @node Formatting Flags
1488 @subsubsection Formatting Flags
1490 The @samp{%m} and @samp{%d} directives support the @samp{#}, @samp{0}
1491 and @samp{+} flags, but the other directives do not, even if they
1492 print numbers. Numeric directives that do not support these flags
1502 All fields support the format flag @samp{-}, which makes fields
1503 left-aligned. That is, if the field width is greater than the actual
1504 contents of the field, the requisite number of spaces are printed
1505 after the field content instead of before it.
1508 @section Run Commands
1510 You can use the list of file names created by @code{find} or
1511 @code{locate} as arguments to other commands. In this way you can
1512 perform arbitrary actions on the files.
1521 @subsection Single File
1523 Here is how to run a command on one file at a time.
1525 @deffn Action -exec command ;
1526 Execute @var{command}; true if 0 status is returned. @code{find} takes
1527 all arguments after @samp{-exec} to be part of the command until an
1528 argument consisting of @samp{;} is reached. It replaces the string
1529 @samp{@{@}} by the current file name being processed everywhere it
1530 occurs in the command. Both of these constructions need to be escaped
1531 (with a @samp{\}) or quoted to protect them from expansion by the shell.
1532 The command is executed in the directory in which @code{find} was run.
1534 For example, to compare each C header file in the current directory with
1535 the file @file{/tmp/master}:
1538 find . -name '*.h' -exec diff -u '@{@}' /tmp/master ';'
1543 @deffn Action -exec command +
1544 This variant of @samp{-exec} not yet supported. Once it has been
1545 implemented as specified in the POSIX standard, a @samp{@{@}} will expand to
1546 a list of names of matching files. This expansion is done in such a
1547 way as to avoid exceeding the maximum command line length available on
1552 @node Multiple Files
1553 @subsection Multiple Files
1555 Sometimes you need to process files alone. But when you
1556 don't, it is faster to run a command on as many files as possible at a
1557 time, rather than once per file. Doing this saves on the time it takes
1558 to start up the command each time.
1560 To run a command on more than one file at once, use the @code{xargs}
1561 command, which is invoked like this:
1564 xargs @r{[}@var{option}@dots{}@r{]} @r{[}@var{command} @r{[}@var{initial-arguments}@r{]}@r{]}
1567 @code{xargs} normally reads arguments from the standard input. These
1568 arguments are delimited by blanks (which can be protected with double
1569 or single quotes or a backslash) or newlines. It executes the
1570 @var{command} (default is @file{/bin/echo}) one or more times with any
1571 @var{initial-arguments} followed by arguments read from standard
1572 input. Blank lines on the standard input are ignored.
1574 Instead of blank-delimited names, it is safer to use @samp{find -print0}
1575 or @samp{find -fprint0} and process the output by giving the @samp{-0}
1576 or @samp{--null} option to GNU @code{xargs}, GNU @code{tar}, GNU
1577 @code{cpio}, or @code{perl}. The @code{locate} command also has a
1578 @samp{-0} or @samp{--null} option which does the same thing.
1580 You can use shell command substitution (backquotes) to process a list of
1581 arguments, like this:
1584 grep -l sprintf `find $HOME -name '*.c' -print`
1587 However, that method produces an error if the length of the @samp{.c}
1588 file names exceeds the operating system's command-line length limit.
1589 @code{xargs} avoids that problem by running the command as many times as
1590 necessary without exceeding the limit:
1593 find $HOME -name '*.c' -print | xargs grep -l sprintf
1596 However, if the command needs to have its standard input be a terminal
1597 (@code{less}, for example), you have to use the shell command
1598 substitution method or use the @samp{--arg-file} option of
1601 The @code{xargs} command will process all its input, building command
1602 lines and executing them, unless one of the commands exits with a
1603 status of 255 (this will cause xargs to issue an error message and
1604 stop) or it reads a line contains the end of file string specified
1605 with the @samp{--eof} option.
1608 * Unsafe File Name Handling::
1609 * Safe File Name Handling::
1610 * Limiting Command Size::
1611 * Interspersing File Names::
1614 @node Unsafe File Name Handling
1615 @subsubsection Unsafe File Name Handling
1617 Because file names can contain quotes, backslashes, blank characters,
1618 and even newlines, it is not safe to process them using @code{xargs} in its
1619 default mode of operation. But since most files' names do not contain
1620 blanks, this problem occurs only infrequently. If you are only
1621 searching through files that you know have safe names, then you need not
1622 be concerned about it.
1624 @c This example is adapted from:
1625 @c From: pfalstad@stone.Princeton.EDU (Paul John Falstad)
1626 @c Newsgroups: comp.unix.shell
1627 @c Subject: Re: Beware xargs security holes
1628 @c Date: 16 Oct 90 19:12:06 GMT
1630 In many applications, if @code{xargs} botches processing a file because
1631 its name contains special characters, some data might be lost. The
1632 importance of this problem depends on the importance of the data and
1633 whether anyone notices the loss soon enough to correct it. However,
1634 here is an extreme example of the problems that using blank-delimited
1635 names can cause. If the following command is run daily from
1636 @code{cron}, then any user can remove any file on the system:
1639 find / -name '#*' -atime +7 -print | xargs rm
1642 For example, you could do something like this:
1650 and then @code{cron} would delete @file{/vmunix}, if it ran
1651 @code{xargs} with @file{/} as its current directory.
1653 To delete other files, for example @file{/u/joeuser/.plan}, you could do
1661 eg$ mkdir u u/joeuser u/joeuser/.plan'
1663 eg$ echo > u/joeuser/.plan'
1666 eg$ find . -name '#*' -print | xargs echo
1667 ./# ./# /u/joeuser/.plan /#foo
1670 @node Safe File Name Handling
1671 @subsubsection Safe File Name Handling
1673 Here is how to make @code{find} output file names so that they can be
1674 used by other programs without being mangled or misinterpreted. You can
1675 process file names generated this way by giving the @samp{-0} or
1676 @samp{--null} option to GNU @code{xargs}, GNU @code{tar}, GNU
1677 @code{cpio}, or @code{perl}.
1679 @deffn Action -print0
1680 True; print the full file name on the standard output, followed by a
1684 @deffn Action -fprint0 file
1685 True; like @samp{-print0} but write to @var{file} like @samp{-fprint}
1686 (@pxref{Print File Name}).
1689 As of findutils version 4.2.4, the @code{locate} program also has a
1690 @samp{--null} option which does the same thing. For similarity with
1691 @code{xargs}, the short form of the option @samp{-0} can also be used.
1693 If you want to be able to handle file names safely but need to run
1694 commands which want to be connected to a terminal on their input, you
1695 can use the @samp{--arg-file} option to @code{xargs} like this:
1698 find / -name xyzzy -print0 > list
1699 xargs --null --arg-file=list munge
1702 The example above runs the @code{munge} program on all the files named
1703 @file{xyzzy} that we can find, but @code{munge}'s input will still be
1704 the terminal (or whatever the shell was using as standard input). If
1705 your shell has the ``process substitution'' feature @samp{<(...)}, you
1706 can do this in just one step:
1709 xargs --null --arg-file=<(find / -name xyzzy -print0) munge
1712 @node Limiting Command Size
1713 @subsubsection Limiting Command Size
1715 @code{xargs} gives you control over how many arguments it passes to the
1716 command each time it executes it. By default, it uses up to
1717 @code{ARG_MAX} - 2k, or 128k, whichever is smaller, characters per
1718 command. It uses as many lines and arguments as fit within that limit.
1719 The following options modify those values.
1722 @item --no-run-if-empty
1724 If the standard input does not contain any nonblanks, do not run the
1725 command. By default, the command is run once even if there is no input.
1727 @item --max-lines@r{[}=@var{max-lines}@r{]}
1728 @itemx -l@r{[}@var{max-lines}@r{]}
1729 Use at most @var{max-lines} nonblank input lines per command line;
1730 @var{max-lines} defaults to 1 if omitted. Trailing blanks cause an
1731 input line to be logically continued on the next input line, for the
1732 purpose of counting the lines. Implies @samp{-x}.
1734 @item --max-args=@var{max-args}
1735 @itemx -n @var{max-args}
1736 Use at most @var{max-args} arguments per command line. Fewer than
1737 @var{max-args} arguments will be used if the size (see the @samp{-s}
1738 option) is exceeded, unless the @samp{-x} option is given, in which case
1739 @code{xargs} will exit.
1741 @item --max-chars=@var{max-chars}
1742 @itemx -s @var{max-chars}
1743 Use at most @var{max-chars} characters per command line, including the
1744 command and initial arguments and the terminating nulls at the ends of
1745 the argument strings. If you specify a value for this option which is
1746 too large or small, a warning message is printed and the appropriate
1747 upper or lower limit is used instead.
1749 @item --max-procs=@var{max-procs}
1750 @itemx -P @var{max-procs}
1751 Run up to @var{max-procs} processes at a time; the default is 1. If
1752 @var{max-procs} is 0, @code{xargs} will run as many processes as
1753 possible at a time. Use the @samp{-n}, @samp{-s}, or @samp{-l} option
1754 with @samp{-P}; otherwise chances are that the command will be run only
1758 @node Interspersing File Names
1759 @subsubsection Interspersing File Names
1761 @code{xargs} can insert the name of the file it is processing between
1762 arguments you give for the command. Unless you also give options to
1763 limit the command size (@pxref{Limiting Command Size}), this mode of
1764 operation is equivalent to @samp{find -exec} (@pxref{Single File}).
1767 @item --replace@r{[}=@var{replace-str}@r{]}
1768 @itemx -i@r{[}@var{replace-str}@r{]}
1769 Replace occurrences of @var{replace-str} in the initial arguments with
1770 names read from the input. Also, unquoted blanks do not
1771 terminate arguments; instead, the input is split at newlines only. If
1772 @var{replace-str} is omitted, it defaults to @samp{@{@}} (like for
1773 @samp{find -exec}). Implies @samp{-x} and @samp{-l 1}. As an
1774 example, to sort each file the @file{bills} directory, leaving the
1775 output in that file name with @file{.sorted} appended, you could do:
1778 find bills -type f | xargs -iXX sort -o XX.sorted XX
1782 The equivalent command using @samp{find -exec} is:
1785 find bills -type f -exec sort -o '@{@}.sorted' '@{@}' ';'
1790 @subsection Querying
1792 To ask the user whether to execute a command on a single file, you can
1793 use the @code{find} primary @samp{-ok} instead of @samp{-exec}:
1795 @deffn Action -ok command ;
1796 Like @samp{-exec} (@pxref{Single File}), but ask the user first (on
1797 the standard input); if the response does not start with @samp{y} or
1798 @samp{Y}, do not run the command, and return false.
1801 When processing multiple files with a single command, to query the user
1802 you give @code{xargs} the following option. When using this option, you
1803 might find it useful to control the number of files processed per
1804 invocation of the command (@pxref{Limiting Command Size}).
1809 Prompt the user about whether to run each command line and read a line
1810 from the terminal. Only run the command line if the response starts
1811 with @samp{y} or @samp{Y}. Implies @samp{-t}.
1815 @section Delete Files
1817 @deffn Action -delete
1818 Delete files or directories; true if removal succeeded. If the
1819 removal failed, an error message is issued.
1821 The use of the @samp{-delete} action on the command line automatically
1822 turns on the @samp{-depth} option (@pxref{find Expressions}).
1826 @section Adding Tests
1828 You can test for file attributes that none of the @code{find} builtin
1829 tests check. To do this, use @code{xargs} to run a program that filters
1830 a list of files printed by @code{find}. If possible, use @code{find}
1831 builtin tests to pare down the list, so the program run by @code{xargs}
1832 has less work to do. The tests builtin to @code{find} will likely run
1833 faster than tests that other programs perform.
1835 For example, here is a way to print the names of all of the unstripped
1836 binaries in the @file{/usr/local} directory tree. Builtin tests avoid
1837 running @code{file} on files that are not regular files or are not
1841 find /usr/local -type f -perm +a=x | xargs file |
1842 grep 'not stripped' | cut -d: -f1
1846 The @code{cut} program removes everything after the file name from the
1847 output of @code{file}.
1849 @c Idea from Martin Weitzel.
1850 If you want to place a special test somewhere in the middle of a
1851 @code{find} expression, you can use @samp{-exec} to run a program that
1852 performs the test. Because @samp{-exec} evaluates to the exit status of
1853 the executed program, you can write a program (which can be a shell
1854 script) that tests for a special attribute and make it exit with a true
1855 (zero) or false (non-zero) status. It is a good idea to place such a
1856 special test @emph{after} the builtin tests, because it starts a new
1857 process which could be avoided if a builtin test evaluates to false.
1858 Use this method only when @code{xargs} is not flexible enough, because
1859 starting one or more new processes to test each file is slower than
1860 using @code{xargs} to start one process that tests many files.
1862 Here is a shell script called @code{unstripped} that checks whether its
1863 argument is an unstripped binary file:
1867 file $1 | grep 'not stripped' > /dev/null
1870 This script relies on the fact that the shell exits with the status of
1871 the last program it executed, in this case @code{grep}. @code{grep}
1872 exits with a true status if it found any matches, false if not. Here is
1873 an example of using the script (assuming it is in your search path). It
1874 lists the stripped executables in the file @file{sbins} and the
1875 unstripped ones in @file{ubins}.
1878 find /usr/local -type f -perm +a=x \
1879 \( -exec unstripped '@{@}' \; -fprint ubins -o -fprint sbins \)
1882 @node Common Tasks, Databases, Actions, Top
1883 @chapter Common Tasks
1885 The sections that follow contain some extended examples that both give a
1886 good idea of the power of these programs, and show you how to solve
1887 common real-world problems.
1890 * Viewing And Editing::
1893 * Strange File Names::
1894 * Fixing Permissions::
1895 * Classifying Files::
1898 @node Viewing And Editing
1899 @section Viewing And Editing
1901 To view a list of files that meet certain criteria, simply run your file
1902 viewing program with the file names as arguments. Shells substitute a
1903 command enclosed in backquotes with its output, so the whole command
1907 less `find /usr/include -name '*.h' | xargs grep -l mode_t`
1911 You can edit those files by giving an editor name instead of a file
1915 emacs `find /usr/include -name '*.h' | xargs grep -l mode_t`
1918 Because there is a limit to the length of any individual command line,
1919 there is a limit to the number of files that can be handled in this
1920 way. We can get around this difficulty by using xargs like this:
1923 find /usr/include -name '*.h' | xargs grep -l mode_t > todo
1924 xargs --arg-file=todo emacs
1927 Here, @code{xargs} will run @code{emacs} as many times as necessary to
1928 visit all of the files listed in the file @file{todo}.
1933 You can pass a list of files produced by @code{find} to a file archiving
1934 program. GNU @code{tar} and @code{cpio} can both read lists of file
1935 names from the standard input---either delimited by nulls (the safe way)
1936 or by blanks (the lazy, risky default way). To use null-delimited
1937 names, give them the @samp{--null} option. You can store a file archive
1938 in a file, write it on a tape, or send it over a network to extract on
1941 One common use of @code{find} to archive files is to send a list of the
1942 files in a directory tree to @code{cpio}. Use @samp{-depth} so if a
1943 directory does not have write permission for its owner, its contents can
1944 still be restored from the archive since the directory's permissions are
1945 restored after its contents. Here is an example of doing this using
1946 @code{cpio}; you could use a more complex @code{find} expression to
1947 archive only certain files.
1950 find . -depth -print0 |
1951 cpio --create --null --format=crc --file=/dev/nrst0
1954 You could restore that archive using this command:
1957 cpio --extract --null --make-dir --unconditional \
1958 --preserve --file=/dev/nrst0
1961 Here are the commands to do the same things using @code{tar}:
1964 find . -depth -print0 |
1965 tar --create --null --files-from=- --file=/dev/nrst0
1967 tar --extract --null --preserve-perm --same-owner \
1971 @c Idea from Rick Sladkey.
1972 Here is an example of copying a directory from one machine to another:
1975 find . -depth -print0 | cpio -0o -Hnewc |
1976 rsh @var{other-machine} "cd `pwd` && cpio -i0dum"
1980 @section Cleaning Up
1982 @c Idea from Jim Meyering.
1983 This section gives examples of removing unwanted files in various situations.
1984 Here is a command to remove the CVS backup files created when an update
1988 find . -name '.#*' -print0 | xargs -0r rm -f
1991 The command above works, but the following is safer:
1994 find . -name '.#*' -depth -delete
1997 @c Idea from Franc,ois Pinard.
1998 You can run this command to clean out your clutter in @file{/tmp}. You
1999 might place it in the file your shell runs when you log out
2000 (@file{.bash_logout}, @file{.logout}, or @file{.zlogout}, depending on
2001 which shell you use).
2004 find /tmp -depth -user "$LOGNAME" -type f -delete
2007 If your @code{find} command removes directories, you may find that
2008 you get a spurious error message when @code{find} tries to recurse
2009 into a directory that has now been removed. Using the @samp{-depth}
2010 option will normally resolve this problem.
2012 @c Idea from Noah Friedman.
2013 To remove old Emacs backup and auto-save files, you can use a command
2014 like the following. It is especially important in this case to use
2015 null-terminated file names because Emacs packages like the VM mailer
2016 often create temporary file names with spaces in them, like @file{#reply
2017 to David J. MacKenzie<1>#}.
2020 find ~ \( -name '*~' -o -name '#*#' \) -print0 |
2021 xargs --no-run-if-empty --null rm -vf
2024 Removing old files from @file{/tmp} is commonly done from @code{cron}:
2026 @c Idea from Kaveh Ghazi.
2028 find /tmp /var/tmp -not -type d -mtime +3 -delete
2029 find /tmp /var/tmp -depth -mindepth 1 -type d -empty -delete
2032 The second @code{find} command above uses @samp{-depth} so it cleans out
2033 empty directories depth-first, hoping that the parents become empty and
2034 can be removed too. It uses @samp{-mindepth} to avoid removing
2035 @file{/tmp} itself if it becomes totally empty.
2037 @node Strange File Names
2038 @section Strange File Names
2041 @c From: tmatimar@isgtec.com (Ted Timar)
2042 @c Newsgroups: comp.unix.questions,comp.unix.shell,comp.answers,news.answers
2043 @c Subject: Unix - Frequently Asked Questions (2/7) [Frequent posting]
2044 @c Subject: How do I remove a file with funny characters in the filename ?
2045 @c Date: Thu Mar 18 17:16:55 EST 1993
2046 @code{find} can help you remove or rename a file with strange characters
2047 in its name. People are sometimes stymied by files whose names contain
2048 characters such as spaces, tabs, control characters, or characters with
2049 the high bit set. The simplest way to remove such files is:
2052 rm -i @var{some*pattern*that*matches*the*problem*file}
2055 @code{rm} asks you whether to remove each file matching the given
2056 pattern. If you are using an old shell, this approach might not work if
2057 the file name contains a character with the high bit set; the shell may
2058 strip it off. A more reliable way is:
2061 find . -maxdepth 1 @var{tests} -ok rm '@{@}' \;
2065 where @var{tests} uniquely identify the file. The @samp{-maxdepth 1}
2066 option prevents @code{find} from wasting time searching for the file in
2067 any subdirectories; if there are no subdirectories, you may omit it. A
2068 good way to uniquely identify the problem file is to figure out its
2075 Suppose you have a file whose name contains control characters, and you
2076 have found that its inode number is 12345. This command prompts you for
2077 whether to remove it:
2080 find . -maxdepth 1 -inum 12345 -ok rm -f '@{@}' \;
2083 If you don't want to be asked, perhaps because the file name may contain
2084 a strange character sequence that will mess up your screen when printed,
2085 then use @samp{-exec} instead of @samp{-ok}.
2087 If you want to rename the file instead, you can use @code{mv} instead of
2091 find . -maxdepth 1 -inum 12345 -ok mv '@{@}' @var{new-file-name} \;
2094 @node Fixing Permissions
2095 @section Fixing Permissions
2097 Suppose you want to make sure that everyone can write to the directories in a
2098 certain directory tree. Here is a way to find directories lacking either
2099 user or group write permission (or both), and fix their permissions:
2102 find . -type d -not -perm -ug=w | xargs chmod ug+w
2106 You could also reverse the operations, if you want to make sure that
2107 directories do @emph{not} have world write permission.
2109 @node Classifying Files
2110 @section Classifying Files
2113 @c From: martin@mwtech.UUCP (Martin Weitzel)
2114 @c Newsgroups: comp.unix.wizards,comp.unix.questions
2115 @c Subject: Advanced usage of 'find' (Re: Unix security automating script)
2116 @c Date: 22 Mar 90 15:05:19 GMT
2117 If you want to classify a set of files into several groups based on
2118 different criteria, you can use the comma operator to perform multiple
2119 independent tests on the files. Here is an example:
2122 find / -type d \( -perm -o=w -fprint allwrite , \
2123 -perm -o=x -fprint allexec \)
2125 echo "Directories that can be written to by everyone:"
2128 echo "Directories with search permissions for everyone:"
2132 @code{find} has only to make one scan through the directory tree (which
2133 is one of the most time consuming parts of its work).
2135 @node Databases, File Permissions, Common Tasks, Top
2136 @chapter File Name Databases
2138 The file name databases used by @code{locate} contain lists of files
2139 that were in particular directory trees when the databases were last
2140 updated. The file name of the default database is determined when
2141 @code{locate} and @code{updatedb} are configured and installed. The
2142 frequency with which the databases are updated and the directories for
2143 which they contain entries depend on how often @code{updatedb} is run,
2144 and with which arguments.
2147 * Database Locations::
2148 * Database Formats::
2149 * Newline Handling::
2153 @node Database Locations
2154 @section Database Locations
2156 There can be multiple file name databases. Users can select which
2157 databases @code{locate} searches using an environment variable or a
2158 command line option. The system administrator can choose the file name
2159 of the default database, the frequency with which the databases are
2160 updated, and the directories for which they contain entries. File name
2161 databases are updated by running the @code{updatedb} program, typically
2164 In networked environments, it often makes sense to build a database at
2165 the root of each filesystem, containing the entries for that filesystem.
2166 @code{updatedb} is then run for each filesystem on the fileserver where
2167 that filesystem is on a local disk, to prevent thrashing the network.
2168 Here are the options to @code{updatedb} to select which directories each
2169 database contains entries for:
2172 @item --findoptions='@var{OPTION}@dots{}'
2173 Global options to pass on to @code{find}.
2174 The environment variable @code{FINDOPTIONS} also sets this value.
2177 @item --localpaths='@var{path}@dots{}'
2178 Non-network directories to put in the database.
2179 Default is @file{/}.
2181 @item --netpaths='@var{path}@dots{}'
2182 Network (NFS, AFS, RFS, etc.) directories to put in the database.
2183 The environment variable @code{NETPATHS} also sets this value.
2187 @item --prunepaths='@var{path}@dots{}'
2188 Directories to not put in the database, which would otherwise be.
2189 The environment variable @code{PRUNEPATHS} also sets this value.
2190 Default is @file{/tmp /usr/tmp /var/tmp /afs}.
2192 @item --prunefs='@var{path}@dots{}'
2193 File systems to not put in the database, which would otherwise be.
2194 Note that files are pruned when a file system is reached;
2195 Any file system mounted under an undesired file system will be
2197 The environment variable @code{PRUNEFS} also sets this value.
2198 Default is @file{nfs NFS proc}.
2200 @item --output=@var{dbfile}
2201 The database file to build.
2202 Default is system-dependent, but typically @file{/usr/local/var/locatedb}.
2204 @item --localuser=@var{user}
2205 The user to search the non-network directories as, using @code{su}.
2206 Default is to search the non-network directories as the current user.
2207 You can also use the environment variable @code{LOCALUSER} to set this user.
2209 @item --netuser=@var{user}
2210 The user to search network directories as, using @code{su}.
2211 Default is @code{daemon}.
2212 You can also use the environment variable @code{NETUSER} to set this user.
2215 @node Database Formats
2216 @section Database Formats
2218 The file name databases contain lists of files that were in particular
2219 directory trees when the databases were last updated. The file name
2220 database format changed starting with GNU @code{locate} version 4.0 to
2221 allow machines with different byte orderings to share the databases. The
2222 new GNU @code{locate} can read both the old and new database formats.
2223 However, old versions of @code{locate} and @code{find} produce incorrect
2224 results if given a new-format database.
2227 * New Database Format::
2229 * Old Database Format::
2232 @node New Database Format
2233 @subsection New Database Format
2235 @code{updatedb} runs a program called @code{frcode} to
2236 @dfn{front-compress} the list of file names, which reduces the database
2237 size by a factor of 4 to 5. Front-compression (also known as
2238 incremental encoding) works as follows.
2240 The database entries are a sorted list (case-insensitively, for users'
2241 convenience). Since the list is sorted, each entry is likely to share a
2242 prefix (initial string) with the previous entry. Each database entry
2243 begins with an offset-differential count byte, which is the additional
2244 number of characters of prefix of the preceding entry to use beyond the
2245 number that the preceding entry is using of its predecessor. (The
2246 counts can be negative.) Following the count is a null-terminated ASCII
2247 remainder---the part of the name that follows the shared prefix.
2249 If the offset-differential count is larger than can be stored in a byte
2250 (+/-127), the byte has the value 0x80 and the count follows in a 2-byte
2251 word, with the high byte first (network byte order).
2253 Every database begins with a dummy entry for a file called
2254 @file{LOCATE02}, which @code{locate} checks for to ensure that the
2255 database file has the correct format; it ignores the entry in doing the
2258 Databases can not be concatenated together, even if the first (dummy)
2259 entry is trimmed from all but the first database. This is because the
2260 offset-differential count in the first entry of the second and following
2261 databases will be wrong.
2263 @node Sample Database
2264 @subsection Sample Database
2266 Sample input to @code{frcode}:
2267 @c with nulls changed to newlines:
2271 /usr/src/cmd/aardvark.c
2272 /usr/src/cmd/armadillo.c
2276 Length of the longest prefix of the preceding entry to share:
2285 Output from @code{frcode}, with trailing nulls changed to newlines
2286 and count bytes made printable:
2296 (6 = 14 - 8, and -9 = 5 - 14)
2298 @node Old Database Format
2299 @subsection Old Database Format
2301 The old database format is used by Unix @code{locate} and @code{find}
2302 programs and earlier releases of the GNU ones. @code{updatedb} produces
2303 this format if given the @samp{--old-format} option.
2305 @code{updatedb} runs programs called @code{bigram} and @code{code} to
2306 produce old-format databases. The old format differs from the new one
2307 in the following ways. Instead of each entry starting with an
2308 offset-differential count byte and ending with a null, byte values from
2309 0 through 28 indicate offset-differential counts from -14 through 14.
2310 The byte value indicating that a long offset-differential count follows
2311 is 0x1e (30), not 0x80. The long counts are stored in host byte order,
2312 which is not necessarily network byte order, and host integer word size,
2313 which is usually 4 bytes. They also represent a count 14 less than
2314 their value. The database lines have no termination byte; the start of
2315 the next line is indicated by its first byte having a value <= 30.
2317 In addition, instead of starting with a dummy entry, the old database
2318 format starts with a 256 byte table containing the 128 most common
2319 bigrams in the file list. A bigram is a pair of adjacent bytes. Bytes
2320 in the database that have the high bit set are indexes (with the high
2321 bit cleared) into the bigram table. The bigram and offset-differential
2322 count coding makes these databases 20-25% smaller than the new format,
2323 but makes them not 8-bit clean. Any byte in a file name that is in the
2324 ranges used for the special codes is replaced in the database by a
2325 question mark, which not coincidentally is the shell wildcard to match a
2328 The old format therefore can not faithfully store entries with non-ASCII
2329 characters. It therefore should not be used in internationalized
2332 @node Newline Handling
2333 @section Newline Handling
2335 Within the database, filenames are terminated with a null character.
2336 This is the case for both the old and the new format.
2338 When the new database format is being used, the compression technique
2339 used to generate the database though relies on the ability to sort the
2340 list of files before they are presented to @code{frcode}.
2342 If the system's sort command allows its input list of files to be
2343 separated with null characters via the @samp{-z} option, this option
2344 is used and therefore @code{updatedb} and @code{locate} will both
2345 correctly handle filenames containing newlines. If the @code{sort}
2346 command lacks support for this, the list of files is delimited with
2347 the newline character, meaning that parts of filenames containing
2348 newlines will be incorrectly sorted. This can result in both
2349 incorrect matches and incorrect failures to match.
2351 On the other hand, if you are using the old database format, filenames
2352 with embedded newlines are not correctly handled. There is no
2353 technical limitation which enforces this, it's just that the
2354 @code{bigram} program has no been updated to support lists of
2355 filenames separated by nulls.
2357 So, if you are using the new database format (this is the default) and
2358 your system uses GNU @code{find}, newlines will be correctly handled
2359 at all times. Otherwise, newlines may not be correctly handled.
2361 @node File Permissions, Reference, Databases, Top
2362 @chapter File Permissions
2366 @node Reference, Primary Index, File Permissions, Top
2369 Below are summaries of the command line syntax for the programs
2370 discussed in this manual.
2375 * Invoking updatedb::
2379 @node Invoking find, Invoking locate, , Reference
2380 @section Invoking @code{find}
2383 find @r{[-H] [-L] [-P]} @r{[}@var{file}@dots{}@r{]} @r{[}@var{expression}@r{]}
2386 @code{find} searches the directory tree rooted at each file name
2387 @var{file} by evaluating the @var{expression} on each file it finds in
2390 The options @samp{-H}, @samp{-L} or @samp{-P} may be specified at the
2391 start of the command line (if none of these is specified, @samp{-P} is
2392 assumed). The arguments after these are a list of files or
2393 directories that should be searched.
2395 This list of files to search is followed by a list of expressions
2396 describing the files we wish to search for. The first part of the
2397 expression is recgnised by the fact that it begins with @samp{-},
2398 @samp{(}, @samp{)}, @samp{,}, or @samp{!}. Any arguments after it are
2399 the rest of the expression. If no paths are given, the current
2400 directory is used. If no expression is given, the expression
2401 @samp{-print} is used.
2403 @code{find} exits with status 0 if all files are processed successfully,
2404 greater than 0 if errors occur.
2406 Three options can precede the list of path names. They determine the
2407 way that symbolic links are handled.
2411 Never follow symbolic links (this is the default), except in the case
2412 of the @samp{-xtype} predicate.
2414 Always follow symbolic links, except in the case of the @samp{-xtype}
2417 Follow symbolic links specified in the list of paths to search, or
2418 which are otherwise specified on the command line.
2421 If @code{find} would follow a symbolic link, but cannot for any reason
2422 (for example, because it has insufficient permissions or the link is
2423 broken), it falls back on using the properties of the symbolic link
2424 itself. @ref{Symbolic Links} for a more complete description of how
2425 symbolic links are handled.
2427 @xref{Primary Index}, for a summary of all of the tests, actions, and
2428 options that the expression can contain. If the expression is
2429 missing, @samp{-print} is assumed.
2433 @code{find} also recognizes two options for administrative use:
2437 Print a summary of the command-line argument format and exit.
2439 Print the version number of @code{find} and exit.
2444 * Warning Messages::
2448 @node Warning Messages,,, Invoking find
2449 @subsection Warning Messages
2451 If there is an error on the @code{find} command line, an error message
2452 is normally issued. However, there are some usages that are
2453 inadvisable but which @code{find} should still accept. Under these
2454 circumstances, @code{find} may issue a warning message. By default,
2455 warnings are enabled only if @code{find} is being run interactively
2456 (specifically, if the standard input is a terminal). Warning messages
2457 can be controlled explicitly by the use of options on the command
2462 Issue warning messages where appropriate.
2464 Do not issue warning messages.
2467 These options take effect at the point on the command line where they
2468 are specified. Therefore if you specify @samp{-nowarn} at the end of
2469 the command line, you will not see warning messages for any problems
2470 occurring before that. The warning messages affected by the above
2471 options are triggered by:
2475 Use of the @samp{-d} option which is deprecated; please use
2476 @samp{-depth} instead, since the latter is POSIX-compliant.
2478 Use of the @samp{-ipath} option which is deprecated; please use
2479 @samp{-iwholename} instead.
2481 Specifying an option (for example @samp{-mindepth}) after a non-option
2482 (for example @samp{-type} or @samp{-print}) on the command line.
2486 The default behaviour above is designed to work in that way so that
2487 existing shell scripts which use such constructs don't generate
2488 spurious errors, but people will be made aware of the problem.
2490 Some warning messages are issued for less common or more serious
2491 problems, and so cannot be turned off:
2495 Use of an unrecognised backslash escape sequence with @samp{-fprintf}
2497 Use of an unrecognised formatting directive with @samp{-fprintf}
2500 @node Invoking locate, Invoking updatedb, Invoking find, Reference
2501 @section Invoking @code{locate}
2504 locate @r{[}@var{option}@dots{}@r{]} @var{pattern}@dots{}
2508 @item --database=@var{path}
2509 @itemx -d @var{path}
2510 Instead of searching the default file name database, search the file
2511 name databases in @var{path}, which is a colon-separated list of
2512 database file names. You can also use the environment variable
2513 @code{LOCATE_PATH} to set the list of database files to search. The
2514 option overrides the environment variable if both are used.
2518 Only print out such names which currently exist (instead of such names
2519 which existed when the database was created).
2520 Note that this may slow down the program a lot, if there are many matches
2525 Ignore case distinctions in both the pattern and the file names.
2529 Results are separated with the ASCII NUL character rather than the
2534 Just print the number of results, not the results themselves.
2538 Limit the number of results printed to N. If you use the
2539 @samp{--count} option, the value printed will never be larger than
2543 The specified pattern is matched against the whole name of the file in
2544 the locate database. If the pattern contains metacharacters, it must
2545 match exactly. If not, it must match part of the whole file name.
2546 This is the default behaviour.
2549 The specified pattern is matched against just the last component of
2550 the name of the file in the locate database. This last component is
2551 also called the ``base name''. For example, the base name of
2552 @file{/tmp/mystuff/foo.old.c} is @file{foo.old.c}. If the pattern
2553 contains metacharacters, it must match exactly. If not, it must match
2554 part of the whole file name.
2557 Print a summary of the options to @code{locate} and exit.
2560 Print the version number of @code{locate} and exit.
2563 @node Invoking updatedb, Invoking xargs, Invoking locate, Reference
2564 @section Invoking @code{updatedb}
2567 updatedb @r{[}@var{option}@dots{}@r{]}
2571 @item --findoptions='@var{OPTION}@dots{}'
2572 Global options to pass on to @code{find}.
2573 The environment variable @code{FINDOPTIONS} also sets this value.
2576 @item --localpaths='@var{path}@dots{}'
2577 Non-network directories to put in the database.
2578 Default is @file{/}.
2580 @item --netpaths='@var{path}@dots{}'
2581 Network (NFS, AFS, RFS, etc.) directories to put in the database.
2582 The environment variable @code{NETPATHS} also sets this value.
2585 @item --prunepaths='@var{path}@dots{}'
2586 Directories to not put in the database, which would otherwise be.
2587 The environment variable @code{PRUNEPATHS} also sets this value.
2588 Default is @file{/tmp /usr/tmp /var/tmp /afs}.
2590 @item --prunefs='@var{path}@dots{}'
2591 File systems to omit from the database, which would otherwise be included.
2592 Note that files are pruned when a file system is reached;
2593 Any file system mounted under an undesired file system will be
2595 The environment variable @code{PRUNEFS} also sets this value.
2596 Default is @file{nfs NFS proc}.
2598 @item --output=@var{dbfile}
2599 The database file to build.
2600 Default is system-dependent, but typically @file{/usr/local/var/locatedb}.
2602 @item --localuser=@var{user}
2603 The user to search the non-network directories as, using @code{su}.
2604 Default is to search the non-network directories as the current user.
2605 You can also use the environment variable @code{LOCALUSER} to set this user.
2607 @item --netuser=@var{user}
2608 The user to search network directories as, using @code{su}(1).
2609 Default is @code{daemon}.
2610 You can also use the environment variable @code{NETUSER} to set this user.
2613 @node Invoking xargs, , Invoking updatedb, Reference
2614 @section Invoking @code{xargs}
2617 xargs @r{[}@var{option}@dots{}@r{]} @r{[}@var{command} @r{[}@var{initial-arguments}@r{]}@r{]}
2620 @code{xargs} exits with the following status:
2626 if any invocation of the command exited with status 1-125
2628 if the command exited with status 255
2630 if the command is killed by a signal
2632 if the command cannot be run
2634 if the command is not found
2636 if some other error occurred.
2640 @item --arg-file@r{=@var{inputfile}}
2641 @itemx -a @r{=@var{inputfile}}
2642 Read names from the file @var{inputfile} instead of standard input.
2646 Input filenames are terminated by a null character instead of by
2647 whitespace, and the quotes and backslash are not special (every
2648 character is taken literally). Disables the end of file string, which
2649 is treated like any other argument.
2651 @item --eof@r{[}=@var{eof-str}@r{]}
2652 @itemx -e@r{[}@var{eof-str}@r{]}
2653 Set the end of file string to @var{eof-str}. If the end of file string
2654 occurs as a line of input, the rest of the input is ignored. If
2655 @var{eof-str} is omitted, there is no end of file string. If this
2656 option is not given, the end of file string defaults to @samp{_}.
2659 Print a summary of the options to @code{xargs} and exit.
2661 @item --replace@r{[}=@var{replace-str}@r{]}
2662 @itemx -i@r{[}@var{replace-str}@r{]}
2663 Replace occurrences of @var{replace-str} in the initial arguments with
2664 names read from standard input. Also, unquoted blanks do not
2665 terminate arguments; instead, the input is split at newlines only.
2666 If @var{replace-str} is omitted, it defaults to @samp{@{@}}
2667 (like for @samp{find -exec}). Implies @samp{-x} and @samp{-l 1}.
2669 @item --max-lines@r{[}=@var{max-lines}@r{]}
2670 @itemx -l@r{[}@var{max-lines}@r{]}
2671 Use at most @var{max-lines} nonblank input lines per command line;
2672 @var{max-lines} defaults to 1 if omitted. Trailing blanks cause an
2673 input line to be logically continued on the next input line, for the
2674 purpose of counting the lines. Implies @samp{-x}.
2676 @item --max-args=@var{max-args}
2677 @itemx -n @var{max-args}
2678 Use at most @var{max-args} arguments per command line. Fewer than
2679 @var{max-args} arguments will be used if the size (see the @samp{-s}
2680 option) is exceeded, unless the @samp{-x} option is given, in which case
2681 @code{xargs} will exit.
2685 Prompt the user about whether to run each command line and read a line
2686 from the terminal. Only run the command line if the response starts
2687 with @samp{y} or @samp{Y}. Implies @samp{-t}.
2689 @item --no-run-if-empty
2691 If the standard input does not contain any nonblanks, do not run the
2692 command. By default, the command is run once even if there is no input.
2694 @item --max-chars=@var{max-chars}
2695 @itemx -s @var{max-chars}
2696 Use at most @var{max-chars} characters per command line, including the
2697 command and initial arguments and the terminating nulls at the ends of
2698 the argument strings.
2702 Print the command line on the standard error output before executing
2706 Print the version number of @code{xargs} and exit.
2710 Exit if the size (see the @samp{-s} option) is exceeded.
2713 @item --max-procs=@var{max-procs}
2714 @itemx -P @var{max-procs}
2715 Run up to @var{max-procs} processes at a time; the default is 1. If
2716 @var{max-procs} is 0, @code{xargs} will run as many processes as
2720 @node Primary Index, , Reference, Top
2721 @unnumbered @code{find} Primary Index
2723 This is a list of all of the primaries (tests, actions, and options)
2724 that make up @code{find} expressions for selecting files. @xref{find
2725 Expressions}, for more information on expressions.
2732 @comment texi related words used by Emacs' spell checker ispell.el
2734 @comment LocalWords: texinfo setfilename settitle setchapternewpage
2735 @comment LocalWords: iftex finalout ifinfo DIR titlepage vskip pt
2736 @comment LocalWords: filll dir samp dfn noindent xref pxref
2737 @comment LocalWords: var deffn texi deffnx itemx emph asis
2738 @comment LocalWords: findex smallexample subsubsection cindex
2740 @comment other words used by Emacs' spell checker ispell.el
2741 @comment LocalWords: README fred updatedb xargs Plett Rendell akefile
2742 @comment LocalWords: args grep Filesystems fo foo fOo wildcards iname
2743 @comment LocalWords: ipath regex iregex expr fubar regexps
2744 @comment LocalWords: metacharacters macs sr sc inode lname ilname
2745 @comment LocalWords: sysdep noleaf ls inum xdev filesystems usr atime
2746 @comment LocalWords: ctime mtime amin cmin mmin al daystart Sladkey rm
2747 @comment LocalWords: anewer cnewer bckw rf xtype uname gname uid gid
2748 @comment LocalWords: nouser nogroup chown chgrp perm ch maxdepth
2749 @comment LocalWords: mindepth cpio src CD AFS statted stat fstype ufs
2750 @comment LocalWords: nfs tmp mfs printf fprint dils rw djm Nov lwall
2751 @comment LocalWords: POSIXLY fls fprintf strftime locale's EDT GMT AP
2752 @comment LocalWords: EST diff perl backquotes sprintf Falstad Oct cron
2753 @comment LocalWords: eg vmunix mkdir afs allexec allwrite ARG bigram
2754 @comment LocalWords: bigrams cd chmod comp crc CVS dbfile dum eof
2755 @comment LocalWords: fileserver filesystem fn frcode Ghazi Hnewc iXX
2756 @comment LocalWords: joeuser Kaveh localpaths localuser LOGNAME
2757 @comment LocalWords: Meyering mv netpaths netuser nonblank nonblanks
2758 @comment LocalWords: ois ok Pinard printindex proc procs prunefs
2759 @comment LocalWords: prunepaths pwd RFS rmadillo rmdir rsh sbins str
2760 @comment LocalWords: su Timar ubins ug unstripped vf VM Weitzel
2761 @comment LocalWords: wildcard zlogout