1 \input texinfo @c -*-texinfo-*-
4 @settitle Finding Files
5 @c For double-sided printing, uncomment:
6 @c @setchapternewpage odd
18 * Finding Files: (find). Listing and operating on files
19 that match certain criteria.
23 This file documents the GNU utilities for finding files that match
24 certain criteria and performing various operations on them.
26 Copyright (C) 1994 Free Software Foundation, Inc.
28 Permission is granted to make and distribute verbatim copies of
29 this manual provided the copyright notice and this permission notice
30 are preserved on all copies.
33 Permission is granted to process this file through TeX and print the
34 results, provided the printed document carries copying permission
35 notice identical to this one except for the removal of this paragraph
36 (this paragraph not being relevant to the printed manual).
39 Permission is granted to copy and distribute modified versions of this
40 manual under the conditions for verbatim copying, provided that the entire
41 resulting derived work is distributed under the terms of a permission
42 notice identical to this one.
44 Permission is granted to copy and distribute translations of this manual
45 into another language, under the above conditions for modified versions,
46 except that this permission notice may be stated in a translation approved
52 @subtitle Edition @value{EDITION}, for GNU @code{find} version @value{VERSION}
53 @subtitle @value{UPDATED}
54 @author by David MacKenzie
57 @vskip 0pt plus 1filll
58 Copyright @copyright{} 1994 Free Software Foundation, Inc.
60 Permission is granted to make and distribute verbatim copies of
61 this manual provided the copyright notice and this permission notice
62 are preserved on all copies.
64 Permission is granted to copy and distribute modified versions of this
65 manual under the conditions for verbatim copying, provided that the entire
66 resulting derived work is distributed under the terms of a permission
67 notice identical to this one.
69 Permission is granted to copy and distribute translations of this manual
70 into another language, under the above conditions for modified versions,
71 except that this permission notice may be stated in a translation approved
75 @node Top, Introduction, , (dir)
76 @comment node-name, next, previous, up
79 This file documents the GNU utilities for finding files that match
80 certain criteria and performing various actions on them.
81 This is edition @value{EDITION}, for @code{find} version @value{VERSION}.
84 @c The master menu, created with texinfo-master-menu, goes here.
87 * Introduction:: Summary of the tasks this manual describes.
88 * Finding Files:: Finding files that match certain criteria.
89 * Actions:: Doing things to files you have found.
90 * Common Tasks:: Solutions to common real-world problems.
91 * Databases:: Maintaining file name databases.
92 * File Permissions:: How to control access to files.
93 * Reference:: Summary of how to invoke the programs.
94 * Primary Index:: The components of @code{find} expressions.
97 @node Introduction, Finding Files, Top, Top
100 This manual shows how to find files that meet criteria you specify, and
101 how to perform various actions on the files that you find. The
102 principal programs that you use to perform these tasks are @code{find},
103 @code{locate}, and @code{xargs}. Some of the examples in this manual
104 use capabilities specific to the GNU versions of those programs.
106 GNU @code{find} was originally written by Eric Decker, with enhancements
107 by David MacKenzie, Jay Plett, and Tim Wood. GNU @code{xargs} was
108 originally written by Mike Rendell, with enhancements by David
109 MacKenzie. GNU @code{locate} and its associated utilities were
110 originally written by James Woods, with enhancements by David MacKenzie.
111 The idea for @samp{find -print0} and @samp{xargs -0} came from Dan
112 Bernstein. 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.
317 * Combining Primaries With Operators::
323 Here are ways to search for files whose name matches a certain pattern.
324 @xref{Shell Pattern Matching}, for a description of the @var{pattern}
325 arguments to these tests.
327 Each of these tests has a case-sensitive version and a case-insensitive
328 version, whose name begins with @samp{i}. In a case-insensitive
329 comparison, the patterns @samp{fo*} and @samp{F??} match the file names
330 @file{Foo}, @samp{FOO}, @samp{foo}, @samp{fOo}, etc.
333 * Base Name Patterns::
334 * Full Name Patterns::
335 * Fast Full Name Search::
336 * Shell Pattern Matching:: Wildcards used by these programs.
339 @node Base Name Patterns
340 @subsection Base Name Patterns
342 @deffn Test -name pattern
343 @deffnx Test -iname pattern
344 True if the base of the file name (the path with the leading directories
345 removed) matches shell pattern @var{pattern}. For @samp{-iname}, the
346 match is case-insensitive. To ignore a whole directory tree, use
347 @samp{-prune} (@pxref{Directories}). As an example, to find Texinfo
348 source files in @file{/usr/local/doc}:
351 find /usr/local/doc -name '*.texi'
355 @node Full Name Patterns
356 @subsection Full Name Patterns
358 @deffn Test -path pattern
359 @deffnx Test -ipath pattern
360 True if the entire file name, starting with the command line argument
361 under which the file was found, matches shell pattern @var{pattern}.
362 For @samp{-ipath}, the match is case-insensitive. To ignore a whole
363 directory tree, use @samp{-prune} rather than checking every file in the
364 tree (@pxref{Directories}).
367 @deffn Test -regex expr
368 @deffnx Test -iregex expr
369 True if the entire file name matches regular expression @var{expr}.
370 This is a match on the whole path, not a search. For example, to match
371 a file named @file{./fubar3}, you can use the regular expression
372 @samp{.*bar.} or @samp{.*b.*3}, but not @samp{b.*r3}. @xref{Regexps, ,
373 Syntax of Regular Expressions, emacs, The GNU Emacs Manual}, for a
374 description of the syntax of regular expressions. For @samp{-iregex},
375 the match is case-insensitive.
378 @node Fast Full Name Search
379 @subsection Fast Full Name Search
381 To search for files by name without having to actually scan the
382 directories on the disk (which can be slow), you can use the
383 @code{locate} program. For each shell pattern you give it,
384 @code{locate} searches one or more databases of file names and displays
385 the file names that contain the pattern. @xref{Shell Pattern Matching},
386 for details about shell patterns.
388 If a pattern is a plain string---it contains no
389 metacharacters---@code{locate} displays all file names in the database
390 that contain that string. If a pattern contains
391 metacharacters, @code{locate} only displays file names that match the
392 pattern exactly. As a result, patterns that contain metacharacters
393 should usually begin with a @samp{*}, and will most often end with one
394 as well. The exceptions are patterns that are intended to explicitly
395 match the beginning or end of a file name.
402 is almost equivalent to
404 find @var{directories} -name @var{pattern}
407 where @var{directories} are the directories for which the file name
408 databases contain information. The differences are that the
409 @code{locate} information might be out of date, and that @code{locate}
410 handles wildcards in the pattern slightly differently than @code{find}
411 (@pxref{Shell Pattern Matching}).
413 The file name databases contain lists of files that were on the system
414 when the databases were last updated. The system administrator can
415 choose the file name of the default database, the frequency with which
416 the databases are updated, and the directories for which they contain
419 Here is how to select which file name databases @code{locate} searches.
420 The default is system-dependent.
423 @item --database=@var{path}
425 Instead of searching the default file name database, search the file
426 name databases in @var{path}, which is a colon-separated list of
427 database file names. You can also use the environment variable
428 @code{LOCATE_PATH} to set the list of database files to search. The
429 option overrides the environment variable if both are used.
432 @node Shell Pattern Matching
433 @subsection Shell Pattern Matching
435 @code{find} and @code{locate} can compare file names, or parts of file
436 names, to shell patterns. A @dfn{shell pattern} is a string that may
437 contain the following special characters, which are known as
438 @dfn{wildcards} or @dfn{metacharacters}.
440 You must quote patterns that contain metacharacters to prevent the shell
441 from expanding them itself. Double and single quotes both work; so does
442 escaping with a backslash.
446 Matches any zero or more characters.
449 Matches any one character.
452 Matches exactly one character that is a member of the string
453 @var{string}. This is called a @dfn{character class}. As a shorthand,
454 @var{string} may contain ranges, which consist of two characters with a
455 dash between them. For example, the class @samp{[a-z0-9_]} matches a
456 lowercase letter, a number, or an underscore. You can negate a class by
457 placing a @samp{!} or @samp{^} immediately after the opening bracket.
458 Thus, @samp{[^A-Z@@]} matches any character except an uppercase letter
462 Removes the special meaning of the character that follows it. This
463 works even in character classes.
466 In the @code{find} tests that do shell pattern matching (@samp{-name},
467 @samp{-path}, etc.), wildcards in the pattern do not match a @samp{.}
468 at the beginning of a file name. This is not the case for
469 @code{locate}. Thus, @samp{find -name '*macs'} does not match a file
470 named @file{.emacs}, but @samp{locate '*macs'} does.
472 Slash characters have no special significance in the shell pattern
473 matching that @code{find} and @code{locate} do, unlike in the shell, in
474 which wildcards do not match them. Therefore, a pattern @samp{foo*bar}
475 can match a file name @samp{foo3/bar}, and a pattern @samp{./sr*sc} can
476 match a file name @samp{./src/misc}.
481 There are two ways that files can be linked together. @dfn{Symbolic
482 links} are a special type of file whose contents are a portion of the
483 name of another file. @dfn{Hard links} are multiple directory entries
484 for one file; the file names all have the same index node (@dfn{inode})
493 @subsection Symbolic Links
495 @deffn Test -lname pattern
496 @deffnx Test -ilname pattern
497 True if the file is a symbolic link whose contents match shell pattern
498 @var{pattern}. For @samp{-ilname}, the match is case-insensitive.
499 @xref{Shell Pattern Matching}, for details about the @var{pattern}
500 argument. So, to list any symbolic links to @file{sysdep.c} in the
501 current directory and its subdirectories, you can do:
504 find . -lname '*sysdep.c'
508 @deffn Option -follow
509 Dereference symbolic links. The following differences in behavior occur
510 when this option is given:
514 @code{find} follows symbolic links to directories when searching
517 @samp{-lname} and @samp{-ilname} always return false.
519 @samp{-type} reports the types of the files that symbolic links point
522 Implies @samp{-noleaf} (@pxref{Directories}).
527 @subsection Hard Links
529 To find hard links, first get the inode number of the file whose links
530 you want to find. You can learn a file's inode number and the number of
531 links to it by running @samp{ls -i} or @samp{find -ls}. If the file has
532 more than one link, you can search for the other links by passing that
533 inode number to @samp{-inum}. Add the @samp{-xdev} option if you are
534 starting the search at a directory that has other filesystems mounted on
535 it, such as @file{/usr} on many systems. Doing this saves needless
536 searching, since hard links to a file must be on the same filesystem.
540 File has inode number @var{n}.
543 You can also search for files that have a certain number of links, with
544 @samp{-links}. Directories normally have at least two hard links; their
545 @file{.} entry is the second one. If they have subdirectories, each of
546 those also has a hard link called @file{..} to its parent directory.
549 File has @var{n} hard links.
555 Each file has three time stamps, which record the last time that certain
556 operations were performed on the file:
560 access (read the file's contents)
562 change the status (modify the file or its attributes)
564 modify (change the file's contents)
567 You can search for files whose time stamps are within a certain age
568 range, or compare them to other time stamps.
572 * Comparing Timestamps::
576 @subsection Age Ranges
578 These tests are mainly useful with ranges (@samp{+@var{n}} and
582 @deffnx Test -ctime n
583 @deffnx Test -mtime n
584 True if the file was last accessed (or its status changed, or it was
585 modified) @var{n}*24 hours ago.
591 True if the file was last accessed (or its status changed, or it was
592 modified) @var{n} minutes ago. These tests provide finer granularity of
593 measurement than @samp{-atime} et al. For example, to list files in
594 @file{/u/bill} that were last read from 2 to 6 minutes ago:
597 find /u/bill -amin +2 -amin -6
601 @deffn Option -daystart
602 Measure times from the beginning of today rather than from 24 hours ago.
603 So, to list the regular files in your home directory that were modified
607 find ~ -daystart -type f -mtime 1
611 @node Comparing Timestamps
612 @subsection Comparing Timestamps
614 As an alternative to comparing timestamps to the current time, you can
615 compare them to another file's timestamp. That file's timestamp could
616 be updated by another program when some event occurs. Or you could set
617 it to a particular fixed date using the @code{touch} command. For
618 example, to list files in @file{/usr} modified after February 1 of the
621 @c Idea from Rick Sladkey.
623 touch -t 02010000 /tmp/stamp$$
624 find /usr -newer /tmp/stamp$$
628 @deffn Test -anewer file
629 @deffnx Test -cnewer file
630 @deffnx Test -newer file
631 True if the file was last accessed (or its status changed, or it was
632 modified) more recently than @var{file} was modified. These tests are
633 affected by @samp{-follow} only if @samp{-follow} comes before them on
634 the command line. @xref{Symbolic Links}, for more information on
635 @samp{-follow}. As an example, to list any files modified since
636 @file{/bin/sh} was last modified:
639 find . -newer /bin/sh
644 True if the file was last accessed @var{n} days after its status was
645 last changed. Useful for finding files that are not being used, and
646 could perhaps be archived or removed to save disk space.
652 @deffn Test -size n@r{[}bckw@r{]}
653 True if the file uses @var{n} units of space, rounding up. The units
654 are 512-byte blocks by default, but they can be changed by adding a
655 one-character suffix to @var{n}:
663 kilobytes (1024 bytes)
668 The size does not count indirect blocks, but it does count blocks in
669 sparse files that are not actually allocated.
673 True if the file is empty and is either a regular file or a directory.
674 This might make it a good candidate for deletion. This test is useful
675 with @samp{-depth} (@pxref{Directories}) and @samp{-exec rm -rf '@{@}' ';'}
676 (@pxref{Single File}).
683 True if the file is of type @var{c}:
687 block (buffered) special
689 character (unbuffered) special
704 The same as @samp{-type} unless the file is a symbolic link. For
705 symbolic links: if @samp{-follow} has not been given, true if the file
706 is a link to a file of type @var{c}; if @samp{-follow} has been given,
707 true if @var{c} is @samp{l}. In other words, for symbolic links,
708 @samp{-xtype} checks the type of the file that @samp{-type} does not
709 check. @xref{Symbolic Links}, for more information on @samp{-follow}.
715 @deffn Test -user uname
716 @deffnx Test -group gname
717 True if the file is owned by user @var{uname} (belongs to group @var{gname}).
718 A numeric ID is allowed.
723 True if the file's numeric user ID (group ID) is @var{n}. These tests
724 support ranges (@samp{+@var{n}} and @samp{-@var{n}}), unlike
725 @samp{-user} and @samp{-group}.
729 @deffnx Test -nogroup
730 True if no user corresponds to the file's numeric user ID (no group
731 corresponds to the numeric group ID). These cases usually mean that the
732 files belonged to users who have since been removed from the system.
733 You probably should change the ownership of such files to an existing
734 user or group, using the @code{chown} or @code{chgrp} program.
740 @xref{File Permissions}, for information on how file permissions are
741 structured and how to specify them.
743 @deffn Test -perm mode
745 file's permissions are exactly @var{mode} (which can be numeric or symbolic).
746 Symbolic modes use mode 0 as a point of departure.
747 If @var{mode} starts with @samp{-}, true if
748 @emph{all} of the permissions set in @var{mode} are set for the file;
749 permissions not set in @var{mode} are ignored.
750 If @var{mode} starts with @samp{+}, true if
751 @emph{any} of the permissions set in @var{mode} are set for the file;
752 permissions not set in @var{mode} are ignored.
758 To search for files based on their contents, you can use the @code{grep}
759 program. For example, to find out which C source files in the current
760 directory contain the string @samp{thing}, you can do:
766 If you also want to search for the string in files in subdirectories,
767 you can combine @code{grep} with @code{find} and @code{xargs}, like
771 find . -name '*.[ch]' | xargs grep -l thing
774 The @samp{-l} option causes @code{grep} to print only the names of files
775 that contain the string, rather than the lines that contain it. The
776 string argument (@samp{thing}) is actually a regular expression, so it
777 can contain metacharacters. This method can be refined a little by
778 using the @samp{-r} option to make @code{xargs} not run @code{grep} if
779 @code{find} produces no output, and using the @code{find} action
780 @samp{-print0} and the @code{xargs} option @samp{-0} to avoid
781 misinterpreting files whose names contain spaces:
784 find . -name '*.[ch]' -print0 | xargs -r -0 grep -l thing
787 For a fuller treatment of finding files whose contents match a pattern,
788 see the manual page for @code{grep}.
793 Here is how to control which directories @code{find} searches, and how
794 it searches them. These two options allow you to process a horizontal
795 slice of a directory tree.
797 @deffn Option -maxdepth levels
798 Descend at most @var{levels} (a non-negative integer) levels of
799 directories below the command line arguments. @samp{-maxdepth 0} means
800 only apply the tests and actions to the command line arguments.
803 @deffn Option -mindepth levels
804 Do not apply any tests or actions at levels less than @var{levels} (a
805 non-negative integer). @samp{-mindepth 1} means process all files
806 except the command line arguments.
810 Process each directory's contents before the directory itself. Doing
811 this is a good idea when producing lists of files to archive with
812 @code{cpio} or @code{tar}. If a directory does not have write
813 permission for its owner, its contents can still be restored from the
814 archive since the directory's permissions are restored after its contents.
818 If @samp{-depth} is not given, true; do not descend the current
819 directory. If @samp{-depth} is given, false; no effect. @samp{-prune}
820 only affects tests and actions that come after it in the expression, not
821 those that come before.
823 For example, to skip the directory @file{src/emacs} and all files and
824 directories under it, and print the names of the other files found:
827 find . -path './src/emacs' -prune -o -print
831 @deffn Option -noleaf
832 Do not optimize by assuming that directories contain 2 fewer
833 subdirectories than their hard link count. This option is needed when
834 searching filesystems that do not follow the Unix directory-link
835 convention, such as CD-ROM or MS-DOS filesystems or AFS volume mount
836 points. Each directory on a normal Unix filesystem has at least 2 hard
837 links: its name and its @file{.} entry. Additionally, its
838 subdirectories (if any) each have a @file{..} entry linked to that
839 directory. When @code{find} is examining a directory, after it has
840 statted 2 fewer subdirectories than the directory's link count, it knows
841 that the rest of the entries in the directory are non-directories
842 (@dfn{leaf} files in the directory tree). If only the files' names need
843 to be examined, there is no need to stat them; this gives a significant
844 increase in search speed.
850 A @dfn{filesystem} is a section of a disk, either on the local host or
851 mounted from a remote host over a network. Searching network
852 filesystems can be slow, so it is common to make @code{find} avoid them.
854 There are two ways to avoid searching certain filesystems. One way is
855 to tell @code{find} to only search one filesystem:
858 @deffnx Option -mount
859 Don't descend directories on other filesystems. These options are synonyms.
862 The other way is to check the type of filesystem each file is on, and
863 not descend directories that are on undesirable filesystem types:
865 @deffn Test -fstype type
866 True if the file is on a filesystem of type @var{type}. The valid
867 filesystem types vary among different versions of Unix; an incomplete
868 list of filesystem types that are accepted on some version of Unix or
871 ufs 4.2 4.3 nfs tmp mfs S51K S52K
873 You can use @samp{-printf} with the @samp{%F} directive to see the types
874 of your filesystems. @xref{Print File Information}. @samp{-fstype} is
875 usually used with @samp{-prune} to avoid searching remote filesystems
876 (@pxref{Directories}).
879 @node Combining Primaries With Operators
880 @section Combining Primaries With Operators
882 Operators build a complex expression from tests and actions.
883 The operators are, in order of decreasing precedence:
886 @item @asis{( @var{expr} )}
888 Force precedence. True if @var{expr} is true.
890 @item @asis{! @var{expr}}
891 @itemx @asis{-not @var{expr}}
894 True if @var{expr} is false.
896 @item @asis{@var{expr1 expr2}}
897 @itemx @asis{@var{expr1} -a @var{expr2}}
898 @itemx @asis{@var{expr1} -and @var{expr2}}
901 And; @var{expr2} is not evaluated if @var{expr1} is false.
903 @item @asis{@var{expr1} -o @var{expr2}}
904 @itemx @asis{@var{expr1} -or @var{expr2}}
907 Or; @var{expr2} is not evaluated if @var{expr1} is true.
909 @item @asis{@var{expr1} , @var{expr2}}
911 List; both @var{expr1} and @var{expr2} are always evaluated. True if
912 @var{expr2} is true. The value of @var{expr1} is discarded. This
913 operator lets you do multiple independent operations on one traversal,
914 without depending on whether other operations succeeded.
917 @code{find} searches the directory tree rooted at each file name by
918 evaluating the expression from left to right, according to the rules of
919 precedence, until the outcome is known (the left hand side is false for
920 @samp{-and}, true for @samp{-or}), at which point @code{find} moves on
921 to the next file name.
923 There are two other tests that can be useful in complex expressions:
933 @node Actions, Common Tasks, Finding Files, Top
936 There are several ways you can print information about the files that
937 match the criteria you gave in the @code{find} expression. You can
938 print the information either to the standard output or to a file that
939 you name. You can also execute commands that have the file names as
940 arguments. You can use those commands as further filters to select files.
944 * Print File Information::
949 @node Print File Name
950 @section Print File Name
953 True; print the full file name on the standard output, followed by a
957 @deffn Action -fprint file
958 True; print the full file name into file @var{file}, followed by a
959 newline. If @var{file} does not exist when @code{find} is run, it is
960 created; if it does exist, it is truncated to 0 bytes. The file names
961 @file{/dev/stdout} and @file{/dev/stderr} are handled specially; they
962 refer to the standard output and standard error output, respectively.
965 @node Print File Information
966 @section Print File Information
969 True; list the current file in @samp{ls -dils} format on the standard
970 output. The output looks like this:
973 204744 17 -rw-r--r-- 1 djm staff 17337 Nov 2 1992 ./lwall-quotes
980 The inode number of the file. @xref{Hard Links}, for how to find files
981 based on their inode number.
984 the number of blocks in the file. The block counts are of 1K blocks,
985 unless the environment variable @code{POSIXLY_CORRECT} is set, in which
986 case 512-byte blocks are used. @xref{Size}, for how to find files based
990 The file's type and permissions. The type is shown as a dash for a
991 regular file; for other file types, a letter like for @samp{-type} is
992 used (@pxref{Type}). The permissions are read, write, and execute for
993 the file's owner, its group, and other users, respectively; a dash means
994 the permission is not granted. @xref{File Permissions}, for more details
995 about file permissions. @xref{Permissions}, for how to find files based
996 on their permissions.
999 The number of hard links to the file.
1002 The user who owns the file.
1008 The file's size in bytes.
1011 The date the file was last modified.
1014 The file's name. @samp{-ls} quotes non-printable characters in the file
1015 names using C-like backslash escapes.
1019 @deffn Action -fls file
1020 True; like @samp{-ls} but write to @var{file} like @samp{-fprint}
1021 (@pxref{Print File Name}).
1024 @deffn Action -printf format
1025 True; print @var{format} on the standard output, interpreting @samp{\}
1026 escapes and @samp{%} directives. Field widths and precisions can be
1027 specified as with the @code{printf} C function. Unlike @samp{-print},
1028 @samp{-printf} does not add a newline at the end of the string.
1031 @deffn Action -fprintf file format
1032 True; like @samp{-printf} but write to @var{file} like @samp{-fprint}
1033 (@pxref{Print File Name}).
1038 * Format Directives::
1045 The escapes that @samp{-printf} and @samp{-fprintf} recognize are:
1053 Stop printing from this format immediately and flush the output.
1065 A literal backslash (@samp{\}).
1068 A @samp{\} character followed by any other character is treated as an
1069 ordinary character, so they both are printed, and a warning message is
1070 printed to the standard error output (because it was probably a typo).
1072 @node Format Directives
1073 @subsection Format Directives
1075 @samp{-printf} and @samp{-fprintf} support the following format
1076 directives to print information about the file being processed. Unlike
1077 the C @code{printf} function, they do not support field width specifiers.
1079 @samp{%%} is a literal percent sign. A @samp{%} character followed by
1080 any other character is discarded (but the other character is printed),
1081 and a warning message is printed to the standard error output (because
1082 it was probably a typo).
1086 * Ownership Directives::
1088 * Location Directives::
1092 @node Name Directives
1093 @subsubsection Name Directives
1099 File's name with any leading directories removed (only the last element).
1101 Leading directories of file's name (all but the last element and the
1104 File's name with the name of the command line argument under which
1105 it was found removed from the beginning.
1107 Command line argument under which file was found.
1110 @node Ownership Directives
1111 @subsubsection Ownership Directives
1115 File's group name, or numeric group ID if the group has no name.
1117 File's numeric group ID.
1119 File's user name, or numeric user ID if the user has no name.
1121 File's numeric user ID.
1123 File's permissions (in octal).
1126 @node Size Directives
1127 @subsubsection Size Directives
1131 File's size in 1K blocks (rounded up).
1133 File's size in 512-byte blocks (rounded up).
1135 File's size in bytes.
1138 @node Location Directives
1139 @subsubsection Location Directives
1143 File's depth in the directory tree; files named on the command line
1146 Type of the filesystem the file is on; this value can be used for
1147 @samp{-fstype} (@pxref{Directories}).
1149 Object of symbolic link (empty string if file is not a symbolic link).
1151 File's inode number (in decimal).
1153 Number of hard links to file.
1156 @node Time Directives
1157 @subsubsection Time Directives
1159 Some of these directives use the C @code{ctime} function. Its output
1160 depends on the current locale, but it typically looks like
1163 Wed Nov 2 00:42:36 1994
1168 File's last access time in the format returned by the C @code{ctime} function.
1170 File's last access time in the format specified by @var{k}
1171 (@pxref{Time Formats}).
1173 File's last status change time in the format returned by the C @code{ctime}
1176 File's last status change time in the format specified by @var{k}
1177 (@pxref{Time Formats}).
1179 File's last modification time in the format returned by the C @code{ctime}
1182 File's last modification time in the format specified by @var{k}
1183 (@pxref{Time Formats}).
1187 @subsection Time Formats
1189 Below are the formats for the directives @samp{%A}, @samp{%C}, and
1190 @samp{%T}, which print the file's timestamps. Some of these formats
1191 might not be available on all systems, due to differences in the C
1192 @code{strftime} function between systems.
1197 * Combined Time Formats::
1200 @node Time Components
1201 @subsubsection Time Components
1203 The following format directives print single components of the time.
1217 time zone (e.g., EDT), or nothing if no time zone is determinable
1223 seconds since Jan. 1, 1970, 00:00 GMT.
1226 @node Date Components
1227 @subsubsection Date Components
1229 The following format directives print single components of the date.
1233 locale's abbreviated weekday name (Sun..Sat)
1235 locale's full weekday name, variable length (Sunday..Saturday)
1238 locale's abbreviated month name (Jan..Dec)
1240 locale's full month name, variable length (January..December)
1244 day of month (01..31)
1248 day of year (001..366)
1250 week number of year with Sunday as first day of week (00..53)
1252 week number of year with Monday as first day of week (00..53)
1256 last two digits of year (00..99)
1259 @node Combined Time Formats
1260 @subsubsection Combined Time Formats
1262 The following format directives print combinations of time and date
1267 time, 12-hour (hh:mm:ss [AP]M)
1269 time, 24-hour (hh:mm:ss)
1271 locale's time representation (H:M:S)
1273 locale's date and time (Sat Nov 04 12:02:33 EST 1989)
1277 locale's date representation (mm/dd/yy)
1281 @section Run Commands
1283 You can use the list of file names created by @code{find} or
1284 @code{locate} as arguments to other commands. In this way you can
1285 perform arbitrary actions on the files.
1294 @subsection Single File
1296 Here is how to run a command on one file at a time.
1298 @deffn Action -exec command ;
1299 Execute @var{command}; true if 0 status is returned. @code{find} takes
1300 all arguments after @samp{-exec} to be part of the command until an
1301 argument consisting of @samp{;} is reached. It replaces the string
1302 @samp{@{@}} by the current file name being processed everywhere it
1303 occurs in the command. Both of these constructions need to be escaped
1304 (with a @samp{\}) or quoted to protect them from expansion by the shell.
1305 The command is executed in the directory in which @code{find} was run.
1307 For example, to compare each C header file in the current directory with
1308 the file @file{/tmp/master}:
1311 find . -name '*.h' -exec diff -u '@{@}' /tmp/master ';'
1315 @node Multiple Files
1316 @subsection Multiple Files
1318 Sometimes you need to process files alone. But when you
1319 don't, it is faster to run a command on as many files as possible at a
1320 time, rather than once per file. Doing this saves on the time it takes
1321 to start up the command each time.
1323 To run a command on more than one file at once, use the @code{xargs}
1324 command, which is invoked like this:
1327 xargs @r{[}@var{option}@dots{}@r{]} @r{[}@var{command} @r{[}@var{initial-arguments}@r{]}@r{]}
1330 @code{xargs} reads arguments from the standard input, delimited by
1331 blanks (which can be protected with double or single quotes or a
1332 backslash) or newlines. It executes the @var{command} (default is
1333 @file{/bin/echo}) one or more times with any @var{initial-arguments}
1334 followed by arguments read from standard input. Blank lines on the
1335 standard input are ignored.
1337 Instead of blank-delimited names, it is safer to use @samp{find -print0}
1338 or @samp{find -fprint0} and process the output by giving the @samp{-0}
1339 or @samp{--null} option to GNU @code{xargs}, GNU @code{tar}, GNU
1340 @code{cpio}, or @code{perl}.
1342 You can use shell command substitution (backquotes) to process a list of
1343 arguments, like this:
1346 grep -l sprintf `find $HOME -name '*.c' -print`
1349 However, that method produces an error if the length of the @samp{.c}
1350 file names exceeds the operating system's command-line length limit.
1351 @code{xargs} avoids that problem by running the command as many times as
1352 necessary without exceeding the limit:
1355 find $HOME -name '*.c' -print | xargs grep -l sprintf
1358 However, if the command needs to have its standard input be a terminal
1359 (@code{less}, for example), you have to use the shell command
1360 substitution method.
1363 * Unsafe File Name Handling::
1364 * Safe File Name Handling::
1365 * Limiting Command Size::
1366 * Interspersing File Names::
1369 @node Unsafe File Name Handling
1370 @subsubsection Unsafe File Name Handling
1372 Because file names can contain quotes, backslashes, blank characters,
1373 and even newlines, it is not safe to process them using @code{xargs} in its
1374 default mode of operation. But since most files' names do not contain
1375 blanks, this problem occurs only infrequently. If you are only
1376 searching through files that you know have safe names, then you need not
1377 be concerned about it.
1379 @c This example is adapted from:
1380 @c From: pfalstad@stone.Princeton.EDU (Paul John Falstad)
1381 @c Newsgroups: comp.unix.shell
1382 @c Subject: Re: Beware xargs security holes
1383 @c Date: 16 Oct 90 19:12:06 GMT
1385 In many applications, if @code{xargs} botches processing a file because
1386 its name contains special characters, some data might be lost. The
1387 importance of this problem depends on the importance of the data and
1388 whether anyone notices the loss soon enough to correct it. However,
1389 here is an extreme example of the problems that using blank-delimited
1390 names can cause. If the following command is run daily from
1391 @code{cron}, then any user can remove any file on the system:
1394 find / -name '#*' -atime +7 -print | xargs rm
1397 For example, you could do something like this:
1405 and then @code{cron} would delete @file{/vmunix}, if it ran
1406 @code{xargs} with @file{/} as its current directory.
1408 To delete other files, for example @file{/u/joeuser/.plan}, you could do
1416 eg$ mkdir u u/joeuser u/joeuser/.plan'
1418 eg$ echo > u/joeuser/.plan'
1421 eg$ find . -name '#*' -print | xargs echo
1422 ./# ./# /u/joeuser/.plan /#foo
1425 @node Safe File Name Handling
1426 @subsubsection Safe File Name Handling
1428 Here is how to make @code{find} output file names so that they can be
1429 used by other programs without being mangled or misinterpreted. You can
1430 process file names generated this way by giving the @samp{-0} or
1431 @samp{--null} option to GNU @code{xargs}, GNU @code{tar}, GNU
1432 @code{cpio}, or @code{perl}.
1434 @deffn Action -print0
1435 True; print the full file name on the standard output, followed by a
1439 @deffn Action -fprint0 file
1440 True; like @samp{-print0} but write to @var{file} like @samp{-fprint}
1441 (@pxref{Print File Name}).
1444 @node Limiting Command Size
1445 @subsubsection Limiting Command Size
1447 @code{xargs} gives you control over how many arguments it passes to the
1448 command each time it executes it. By default, it uses up to
1449 @code{ARG_MAX} - 2k, or 20k, whichever is smaller, characters per
1450 command. It uses as many lines and arguments as fit within that limit.
1451 The following options modify those values.
1454 @item --no-run-if-empty
1456 If the standard input does not contain any nonblanks, do not run the
1457 command. By default, the command is run once even if there is no input.
1459 @item --max-lines@r{[}=@var{max-lines}@r{]}
1460 @itemx -l@r{[}@var{max-lines}@r{]}
1461 Use at most @var{max-lines} nonblank input lines per command line;
1462 @var{max-lines} defaults to 1 if omitted. Trailing blanks cause an
1463 input line to be logically continued on the next input line, for the
1464 purpose of counting the lines. Implies @samp{-x}.
1466 @item --max-args=@var{max-args}
1467 @itemx -n @var{max-args}
1468 Use at most @var{max-args} arguments per command line. Fewer than
1469 @var{max-args} arguments will be used if the size (see the @samp{-s}
1470 option) is exceeded, unless the @samp{-x} option is given, in which case
1471 @code{xargs} will exit.
1473 @item --max-chars=@var{max-chars}
1474 @itemx -s @var{max-chars}
1475 Use at most @var{max-chars} characters per command line, including the
1476 command and initial arguments and the terminating nulls at the ends of
1477 the argument strings.
1479 @item --max-procs=@var{max-procs}
1480 @itemx -P @var{max-procs}
1481 Run up to @var{max-procs} processes at a time; the default is 1. If
1482 @var{max-procs} is 0, @code{xargs} will run as many processes as
1483 possible at a time. Use the @samp{-n}, @samp{-s}, or @samp{-l} option
1484 with @samp{-P}; otherwise chances are that the command will be run only
1488 @node Interspersing File Names
1489 @subsubsection Interspersing File Names
1491 @code{xargs} can insert the name of the file it is processing between
1492 arguments you give for the command. Unless you also give options to
1493 limit the command size (@pxref{Limiting Command Size}), this mode of
1494 operation is equivalent to @samp{find -exec} (@pxref{Single File}).
1497 @item --replace@r{[}=@var{replace-str}@r{]}
1498 @itemx -i@r{[}@var{replace-str}@r{]}
1499 Replace occurences of @var{replace-str} in the initial arguments with
1500 names read from standard input. Also, unquoted blanks do not terminate
1501 arguments. If @var{replace-str} is omitted, it defaults to @samp{@{@}}
1502 (like for @samp{find -exec}). Implies @samp{-x} and @samp{-l 1}. As an
1503 example, to sort each file the @file{bills} directory, leaving the
1504 output in that file name with @file{.sorted} appended, you could do:
1507 find bills -type f | xargs -iXX sort -o XX.sorted XX
1511 The equivalent command using @samp{find -exec} is:
1514 find bills -type f -exec sort -o '@{@}.sorted' '@{@}' ';'
1519 @subsection Querying
1521 To ask the user whether to execute a command on a single file, you can
1522 use the @code{find} primary @samp{-ok} instead of @samp{-exec}:
1524 @deffn Action -ok command ;
1525 Like @samp{-exec} (@pxref{Single File}), but ask the user first (on
1526 the standard input); if the response does not start with @samp{y} or
1527 @samp{Y}, do not run the command, and return false.
1530 When processing multiple files with a single command, to query the user
1531 you give @code{xargs} the following option. When using this option, you
1532 might find it useful to control the number of files processed per
1533 invocation of the command (@pxref{Limiting Command Size}).
1538 Prompt the user about whether to run each command line and read a line
1539 from the terminal. Only run the command line if the response starts
1540 with @samp{y} or @samp{Y}. Implies @samp{-t}.
1544 @section Adding Tests
1546 You can test for file attributes that none of the @code{find} builtin
1547 tests check. To do this, use @code{xargs} to run a program that filters
1548 a list of files printed by @code{find}. If possible, use @code{find}
1549 builtin tests to pare down the list, so the program run by @code{xargs}
1550 has less work to do. The tests builtin to @code{find} will likely run
1551 faster than tests that other programs perform.
1553 For example, here is a way to print the names of all of the unstripped
1554 binaries in the @file{/usr/local} directory tree. Builtin tests avoid
1555 running @code{file} on files that are not regular files or are not
1559 find /usr/local -type f -perm +a=x | xargs file |
1560 grep 'not stripped' | cut -d: -f1
1564 The @code{cut} program removes everything after the file name from the
1565 output of @code{file}.
1567 @c Idea from Martin Weitzel.
1568 If you want to place a special test somewhere in the middle of a
1569 @code{find} expression, you can use @samp{-exec} to run a program that
1570 performs the test. Because @samp{-exec} evaluates to the exit status of
1571 the executed program, you can write a program (which can be a shell
1572 script) that tests for a special attribute and make it exit with a true
1573 (zero) or false (non-zero) status. It is a good idea to place such a
1574 special test @emph{after} the builtin tests, because it starts a new
1575 process which could be avoided if a builtin test evaluates to false.
1576 Use this method only when @code{xargs} is not flexible enough, because
1577 starting one or more new processes to test each file is slower than
1578 using @code{xargs} to start one process that tests many files.
1580 Here is a shell script called @code{unstripped} that checks whether its
1581 argument is an unstripped binary file:
1585 file $1 | grep 'not stripped' > /dev/null
1588 This script relies on the fact that the shell exits with the status of
1589 the last program it executed, in this case @code{grep}. @code{grep}
1590 exits with a true status if it found any matches, false if not. Here is
1591 an example of using the script (assuming it is in your search path). It
1592 lists the stripped executables in the file @file{sbins} and the
1593 unstripped ones in @file{ubins}.
1596 find /usr/local -type f -perm +a=x \
1597 \( -exec unstripped '@{@}' \; -fprint ubins -o -fprint sbins \)
1600 @node Common Tasks, Databases, Actions, Top
1601 @chapter Common Tasks
1603 The sections that follow contain some extended examples that both give a
1604 good idea of the power of these programs, and show you how to solve
1605 common real-world problems.
1608 * Viewing And Editing::
1611 * Strange File Names::
1612 * Fixing Permissions::
1613 * Classifying Files::
1616 @node Viewing And Editing
1617 @section Viewing And Editing
1619 To view a list of files that meet certain criteria, simply run your file
1620 viewing program with the file names as arguments. Shells substitute a
1621 command enclosed in backquotes with its output, so the whole command
1625 less `find /usr/include -name '*.h' | xargs grep -l mode_t`
1629 You can edit those files by giving an editor name instead of a file
1635 You can pass a list of files produced by @code{find} to a file archiving
1636 program. GNU @code{tar} and @code{cpio} can both read lists of file
1637 names from the standard input---either delimited by nulls (the safe way)
1638 or by blanks (the lazy, risky default way). To use null-delimited
1639 names, give them the @samp{--null} option. You can store a file archive
1640 in a file, write it on a tape, or send it over a network to extract on
1643 One common use of @code{find} to archive files is to send a list of the
1644 files in a directory tree to @code{cpio}. Use @samp{-depth} so if a
1645 directory does not have write permission for its owner, its contents can
1646 still be restored from the archive since the directory's permissions are
1647 restored after its contents. Here is an example of doing this using
1648 @code{cpio}; you could use a more complex @code{find} expression to
1649 archive only certain files.
1652 find . -depth -print0 |
1653 cpio --create --null --format=crc --file=/dev/nrst0
1656 You could restore that archive using this command:
1659 cpio --extract --null --make-dir --unconditional \
1660 --preserve --file=/dev/nrst0
1663 Here are the commands to do the same things using @code{tar}:
1666 find . -depth -print0 |
1667 tar --create --null --files-from=- --file=/dev/nrst0
1669 tar --extract --null --preserve-perm --same-owner \
1673 @c Idea from Rick Sladkey.
1674 Here is an example of copying a directory from one machine to another:
1677 find . -depth -print0 | cpio -0o -Hnewc |
1678 rsh @var{other-machine} "cd `pwd` && cpio -i0dum"
1682 @section Cleaning Up
1684 @c Idea from Jim Meyering.
1685 This section gives examples of removing unwanted files in various situations.
1686 Here is a command to remove the CVS backup files created when an update
1690 find . -name '.#*' -print0 | xargs -0r rm -f
1693 @c Idea from Franc,ois Pinard.
1694 You can run this command to clean out your clutter in @file{/tmp}. You
1695 might place it in the file your shell runs when you log out
1696 (@file{.bash_logout}, @file{.logout}, or @file{.zlogout}, depending on
1697 which shell you use).
1700 find /tmp -user $LOGNAME -type f -print0 | xargs -0 -r rm -f
1703 @c Idea from Noah Friedman.
1704 To remove old Emacs backup and auto-save files, you can use a command
1705 like the following. It is especially important in this case to use
1706 null-terminated file names because Emacs packages like the VM mailer
1707 often create temporary file names with spaces in them, like @file{#reply
1708 to David J. MacKenzie<1>#}.
1711 find ~ \( -name '*~' -o -name '#*#' \) -print0 |
1712 xargs --no-run-if-empty --null rm -vf
1715 Removing old files from @file{/tmp} is commonly done from @code{cron}:
1717 @c Idea from Kaveh Ghazi.
1719 find /tmp /var/tmp -not -type d -mtime +3 -print0 |
1720 xargs --null --no-run-if-empty rm -f
1722 find /tmp /var/tmp -depth -mindepth 1 -type d -empty -exec rmdir @{@} \;
1725 The second @code{find} command above uses @samp{-depth} so it cleans out
1726 empty directories depth-first, hoping that the parents become empty and
1727 can be removed too. It uses @samp{-mindepth} to avoid removing
1728 @file{/tmp} itself if it becomes totally empty.
1730 @node Strange File Names
1731 @section Strange File Names
1734 @c From: tmatimar@isgtec.com (Ted Timar)
1735 @c Newsgroups: comp.unix.questions,comp.unix.shell,comp.answers,news.answers
1736 @c Subject: Unix - Frequently Asked Questions (2/7) [Frequent posting]
1737 @c Subject: How do I remove a file with funny characters in the filename ?
1738 @c Date: Thu Mar 18 17:16:55 EST 1993
1739 @code{find} can help you remove or rename a file with strange characters
1740 in its name. People are sometimes stymied by files whose names contain
1741 characters such as spaces, tabs, control characters, or characters with
1742 the high bit set. The simplest way to remove such files is:
1745 rm -i @var{some*pattern*that*matches*the*problem*file}
1748 @code{rm} asks you whether to remove each file matching the given
1749 pattern. If you are using an old shell, this approach might not work if
1750 the file name contains a character with the high bit set; the shell may
1751 strip it off. A more reliable way is:
1754 find . -maxdepth 1 @var{tests} -ok rm '@{@}' \;
1758 where @var{tests} uniquely identify the file. The @samp{-maxdepth 1}
1759 option prevents @code{find} from wasting time searching for the file in
1760 any subdirectories; if there are no subdirectories, you may omit it. A
1761 good way to uniquely identify the problem file is to figure out its
1768 Suppose you have a file whose name contains control characters, and you
1769 have found that its inode number is 12345. This command prompts you for
1770 whether to remove it:
1773 find . -maxdepth 1 -inum 12345 -ok rm -f '@{@}' \;
1776 If you don't want to be asked, perhaps because the file name may contain
1777 a strange character sequence that will mess up your screen when printed,
1778 then use @samp{-exec} instead of @samp{-ok}.
1780 If you want to rename the file instead, you can use @code{mv} instead of
1784 find . -maxdepth 1 -inum 12345 -ok mv '@{@}' @var{new-file-name} \;
1787 @node Fixing Permissions
1788 @section Fixing Permissions
1790 Suppose you want to make sure that everyone can write to the directories in a
1791 certain directory tree. Here is a way to find directories lacking either
1792 user or group write permission (or both), and fix their permissions:
1795 find . -type d -not -perm -ug=w | xargs chmod ug+w
1799 You could also reverse the operations, if you want to make sure that
1800 directories do @emph{not} have world write permission.
1802 @node Classifying Files
1803 @section Classifying Files
1806 @c From: martin@mwtech.UUCP (Martin Weitzel)
1807 @c Newsgroups: comp.unix.wizards,comp.unix.questions
1808 @c Subject: Advanced usage of 'find' (Re: Unix security automating script)
1809 @c Date: 22 Mar 90 15:05:19 GMT
1810 If you want to classify a set of files into several groups based on
1811 different criteria, you can use the comma operator to perform multiple
1812 independent tests on the files. Here is an example:
1815 find / -type d \( -perm -o=w -fprint allwrite , \
1816 -perm -o=x -fprint allexec \)
1818 echo "Directories that can be written to by everyone:"
1821 echo "Directories with search permissions for everyone:"
1825 @code{find} has only to make one scan through the directory tree (which
1826 is one of the most time consuming parts of its work).
1828 @node Databases, File Permissions, Common Tasks, Top
1829 @chapter File Name Databases
1831 The file name databases used by @code{locate} contain lists of files
1832 that were in particular directory trees when the databases were last
1833 updated. The file name of the default database is determined when
1834 @code{locate} and @code{updatedb} are configured and installed. The
1835 frequency with which the databases are updated and the directories for
1836 which they contain entries depend on how often @code{updatedb} is run,
1837 and with which arguments.
1840 * Database Locations::
1841 * Database Formats::
1844 @node Database Locations
1845 @section Database Locations
1847 There can be multiple file name databases. Users can select which
1848 databases @code{locate} searches using an environment variable or a
1849 command line option. The system administrator can choose the file name
1850 of the default database, the frequency with which the databases are
1851 updated, and the directories for which they contain entries. File name
1852 databases are updated by running the @code{updatedb} program, typically
1855 In networked environments, it often makes sense to build a database at
1856 the root of each filesystem, containing the entries for that filesystem.
1857 @code{updatedb} is then run for each filesystem on the fileserver where
1858 that filesystem is on a local disk, to prevent thrashing the network.
1859 Here are the options to @code{updatedb} to select which directories each
1860 database contains entries for:
1863 @item --localpaths='@var{path}@dots{}'
1864 Non-network directories to put in the database.
1865 Default is @file{/}.
1867 @item --netpaths='@var{path}@dots{}'
1868 Network (NFS, AFS, RFS, etc.) directories to put in the database.
1869 The environment variable @code{NETPATHS} also sets this value.
1873 @item --prunepaths='@var{path}@dots{}'
1874 Directories to not put in the database, which would otherwise be.
1875 The environment variable @code{PRUNEPATHS} also sets this value.
1876 Default is @file{/tmp /usr/tmp /var/tmp /afs}.
1878 @item --prunefs='@var{path}@dots{}'
1879 File systems to not put in the database, which would otherwise be.
1880 Note that files are pruned when a file system is reached;
1881 Any file system mounted under an undesired file system will be
1883 The environment variable @code{PRUNEFS} also sets this value.
1884 Default is @file{nfs NFS proc}.
1886 @item --output=@var{dbfile}
1887 The database file to build.
1888 Default is system-dependent, but typically @file{/usr/local/var/locatedb}.
1890 @item --localuser=@var{user}
1891 The user to search the non-network directories as, using @code{su}.
1892 Default is to search the non-network directories as the current user.
1893 You can also use the environment variable @code{LOCALUSER} to set this user.
1895 @item --netuser=@var{user}
1896 The user to search network directories as, using @code{su}.
1897 Default is @code{daemon}.
1898 You can also use the environment variable @code{NETUSER} to set this user.
1901 @node Database Formats
1902 @section Database Formats
1904 The file name databases contain lists of files that were in particular
1905 directory trees when the databases were last updated. The file name
1906 database format changed starting with GNU @code{locate} version 4.0 to
1907 allow machines with diffent byte orderings to share the databases. The
1908 new GNU @code{locate} can read both the old and new database formats.
1909 However, old versions of @code{locate} and @code{find} produce incorrect
1910 results if given a new-format database.
1913 * New Database Format::
1915 * Old Database Format::
1918 @node New Database Format
1919 @subsection New Database Format
1921 @code{updatedb} runs a program called @code{frcode} to
1922 @dfn{front-compress} the list of file names, which reduces the database
1923 size by a factor of 4 to 5. Front-compression (also known as
1924 incremental encoding) works as follows.
1926 The database entries are a sorted list (case-insensitively, for users'
1927 convenience). Since the list is sorted, each entry is likely to share a
1928 prefix (initial string) with the previous entry. Each database entry
1929 begins with an offset-differential count byte, which is the additional
1930 number of characters of prefix of the preceding entry to use beyond the
1931 number that the preceding entry is using of its predecessor. (The
1932 counts can be negative.) Following the count is a null-terminated ASCII
1933 remainder---the part of the name that follows the shared prefix.
1935 If the offset-differential count is larger than can be stored in a byte
1936 (+/-127), the byte has the value 0x80 and the count follows in a 2-byte
1937 word, with the high byte first (network byte order).
1939 Every database begins with a dummy entry for a file called
1940 @file{LOCATE02}, which @code{locate} checks for to ensure that the
1941 database file has the correct format; it ignores the entry in doing the
1944 Databases can not be concatenated together, even if the first (dummy)
1945 entry is trimmed from all but the first database. This is because the
1946 offset-differential count in the first entry of the second and following
1947 databases will be wrong.
1949 @node Sample Database
1950 @subsection Sample Database
1952 Sample input to @code{frcode}:
1953 @c with nulls changed to newlines:
1957 /usr/src/cmd/aardvark.c
1958 /usr/src/cmd/armadillo.c
1962 Length of the longest prefix of the preceding entry to share:
1971 Output from @code{frcode}, with trailing nulls changed to newlines
1972 and count bytes made printable:
1982 (6 = 14 - 8, and -9 = 5 - 14)
1984 @node Old Database Format
1985 @subsection Old Database Format
1987 The old database format is used by Unix @code{locate} and @code{find}
1988 programs and earlier releases of the GNU ones. @code{updatedb} produces
1989 this format if given the @samp{--old-format} option.
1991 @code{updatedb} runs programs called @code{bigram} and @code{code} to
1992 produce old-format databases. The old format differs from the new one
1993 in the following ways. Instead of each entry starting with an
1994 offset-differential count byte and ending with a null, byte values from
1995 0 through 28 indicate offset-differential counts from -14 through 14.
1996 The byte value indicating that a long offset-differential count follows
1997 is 0x1e (30), not 0x80. The long counts are stored in host byte order,
1998 which is not necessarily network byte order, and host integer word size,
1999 which is usually 4 bytes. They also represent a count 14 less than
2000 their value. The database lines have no termination byte; the start of
2001 the next line is indicated by its first byte having a value <= 30.
2003 In addition, instead of starting with a dummy entry, the old database
2004 format starts with a 256 byte table containing the 128 most common
2005 bigrams in the file list. A bigram is a pair of adjacent bytes. Bytes
2006 in the database that have the high bit set are indexes (with the high
2007 bit cleared) into the bigram table. The bigram and offset-differential
2008 count coding makes these databases 20-25% smaller than the new format,
2009 but makes them not 8-bit clean. Any byte in a file name that is in the
2010 ranges used for the special codes is replaced in the database by a
2011 question mark, which not coincidentally is the shell wildcard to match a
2014 @node File Permissions, Reference, Databases, Top
2015 @chapter File Permissions
2019 @node Reference, Primary Index, File Permissions, Top
2022 Below are summaries of the command line syntax for the programs
2023 discussed in this manual.
2028 * Invoking updatedb::
2032 @node Invoking find, Invoking locate, , Reference
2033 @section Invoking @code{find}
2036 find @r{[}@var{file}@dots{}@r{]} @r{[}@var{expression}@r{]}
2039 @code{find} searches the directory tree rooted at each file name
2040 @var{file} by evaluating the @var{expression} on each file it finds in
2043 @code{find} considers the first argument that begins with @samp{-},
2044 @samp{(}, @samp{)}, @samp{,}, or @samp{!} to be the beginning of the
2045 expression; any arguments before it are paths to search, and any
2046 arguments after it are the rest of the expression. If no paths are
2047 given, the current directory is used. If no expression is given, the
2048 expression @samp{-print} is used.
2050 @code{find} exits with status 0 if all files are processed successfully,
2051 greater than 0 if errors occur.
2053 @xref{Primary Index}, for a summary of all of the tests, actions, and
2054 options that the expression can contain.
2056 @code{find} also recognizes two options for administrative use:
2060 Print a summary of the command-line argument format and exit.
2062 Print the version number of @code{find} and exit.
2065 @node Invoking locate, Invoking updatedb, Invoking find, Reference
2066 @section Invoking @code{locate}
2069 locate @r{[}@var{option}@dots{}@r{]} @var{pattern}@dots{}
2073 @item --database=@var{path}
2074 @itemx -d @var{path}
2075 Instead of searching the default file name database, search the file
2076 name databases in @var{path}, which is a colon-separated list of
2077 database file names. You can also use the environment variable
2078 @code{LOCATE_PATH} to set the list of database files to search. The
2079 option overrides the environment variable if both are used.
2083 Only print out such names that currently exist (instead of such names
2084 that existed when the database was created).
2085 Note that this may slow down the program a lot, if there are many matches
2089 Print a summary of the options to @code{locate} and exit.
2092 Print the version number of @code{locate} and exit.
2095 @node Invoking updatedb, Invoking xargs, Invoking locate, Reference
2096 @section Invoking @code{updatedb}
2099 updatedb @r{[}@var{option}@dots{}@r{]}
2103 @item --localpaths='@var{path}@dots{}'
2104 Non-network directories to put in the database.
2105 Default is @file{/}.
2107 @item --netpaths='@var{path}@dots{}'
2108 Network (NFS, AFS, RFS, etc.) directories to put in the database.
2109 The environment variable @code{NETPATHS} also sets this value.
2112 @item --prunepaths='@var{path}@dots{}'
2113 Directories to not put in the database, which would otherwise be.
2114 The environment variable @code{PRUNEPATHS} also sets this value.
2115 Default is @file{/tmp /usr/tmp /var/tmp /afs}.
2117 @item --prunefs='@var{path}@dots{}'
2118 File systems to not put in the database, which would otherwise be.
2119 Note that files are pruned when a file system is reached;
2120 Any file system mounted under an undesired file system will be
2122 The environment variable @code{PRUNEFS} also sets this value.
2123 Default is @file{nfs NFS proc}.
2125 @item --output=@var{dbfile}
2126 The database file to build.
2127 Default is system-dependent, but typically @file{/usr/local/var/locatedb}.
2129 @item --localuser=@var{user}
2130 The user to search the non-network directories as, using @code{su}.
2131 Default is to search the non-network directories as the current user.
2132 You can also use the environment variable @code{LOCALUSER} to set this user.
2134 @item --netuser=@var{user}
2135 The user to search network directories as, using @code{su}(1).
2136 Default is @code{daemon}.
2137 You can also use the environment variable @code{NETUSER} to set this user.
2140 @node Invoking xargs, , Invoking updatedb, Reference
2141 @section Invoking @code{xargs}
2144 xargs @r{[}@var{option}@dots{}@r{]} @r{[}@var{command} @r{[}@var{initial-arguments}@r{]}@r{]}
2147 @code{xargs} exits with the following status:
2153 if any invocation of the command exited with status 1-125
2155 if the command exited with status 255
2157 if the command is killed by a signal
2159 if the command cannot be run
2161 if the command is not found
2163 if some other error occurred.
2169 Input filenames are terminated by a null character instead of by
2170 whitespace, and the quotes and backslash are not special (every
2171 character is taken literally). Disables the end of file string, which
2172 is treated like any other argument.
2174 @item --eof@r{[}=@var{eof-str}@r{]}
2175 @itemx -e@r{[}@var{eof-str}@r{]}
2176 Set the end of file string to @var{eof-str}. If the end of file string
2177 occurs as a line of input, the rest of the input is ignored. If
2178 @var{eof-str} is omitted, there is no end of file string. If this
2179 option is not given, the end of file string defaults to @samp{_}.
2182 Print a summary of the options to @code{xargs} and exit.
2184 @item --replace@r{[}=@var{replace-str}@r{]}
2185 @itemx -i@r{[}@var{replace-str}@r{]}
2186 Replace occurences of @var{replace-str} in the initial arguments with
2187 names read from standard input. Also, unquoted blanks do not terminate
2188 arguments. If @var{replace-str} is omitted, it defaults to @samp{@{@}}
2189 (like for @samp{find -exec}). Implies @samp{-x} and @samp{-l 1}.
2191 @item --max-lines@r{[}=@var{max-lines}@r{]}
2192 @itemx -l@r{[}@var{max-lines}@r{]}
2193 Use at most @var{max-lines} nonblank input lines per command line;
2194 @var{max-lines} defaults to 1 if omitted. Trailing blanks cause an
2195 input line to be logically continued on the next input line, for the
2196 purpose of counting the lines. Implies @samp{-x}.
2198 @item --max-args=@var{max-args}
2199 @itemx -n @var{max-args}
2200 Use at most @var{max-args} arguments per command line. Fewer than
2201 @var{max-args} arguments will be used if the size (see the @samp{-s}
2202 option) is exceeded, unless the @samp{-x} option is given, in which case
2203 @code{xargs} will exit.
2207 Prompt the user about whether to run each command line and read a line
2208 from the terminal. Only run the command line if the response starts
2209 with @samp{y} or @samp{Y}. Implies @samp{-t}.
2211 @item --no-run-if-empty
2213 If the standard input does not contain any nonblanks, do not run the
2214 command. By default, the command is run once even if there is no input.
2216 @item --max-chars=@var{max-chars}
2217 @itemx -s @var{max-chars}
2218 Use at most @var{max-chars} characters per command line, including the
2219 command and initial arguments and the terminating nulls at the ends of
2220 the argument strings.
2224 Print the command line on the standard error output before executing
2228 Print the version number of @code{xargs} and exit.
2232 Exit if the size (see the @var{-s} option) is exceeded.
2234 @item --max-procs=@var{max-procs}
2235 @itemx -P @var{max-procs}
2236 Run up to @var{max-procs} processes at a time; the default is 1. If
2237 @var{max-procs} is 0, @code{xargs} will run as many processes as
2241 @node Primary Index, , Reference, Top
2242 @unnumbered @code{find} Primary Index
2244 This is a list of all of the primaries (tests, actions, and options)
2245 that make up @code{find} expressions for selecting files. @xref{find
2246 Expressions}, for more information on expressions.