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
706 The same as @samp{-type} unless the file is a symbolic link. For
707 symbolic links: if @samp{-follow} has not been given, true if the file
708 is a link to a file of type @var{c}; if @samp{-follow} has been given,
709 true if @var{c} is @samp{l}. In other words, for symbolic links,
710 @samp{-xtype} checks the type of the file that @samp{-type} does not
711 check. @xref{Symbolic Links}, for more information on @samp{-follow}.
717 @deffn Test -user uname
718 @deffnx Test -group gname
719 True if the file is owned by user @var{uname} (belongs to group @var{gname}).
720 A numeric ID is allowed.
725 True if the file's numeric user ID (group ID) is @var{n}. These tests
726 support ranges (@samp{+@var{n}} and @samp{-@var{n}}), unlike
727 @samp{-user} and @samp{-group}.
731 @deffnx Test -nogroup
732 True if no user corresponds to the file's numeric user ID (no group
733 corresponds to the numeric group ID). These cases usually mean that the
734 files belonged to users who have since been removed from the system.
735 You probably should change the ownership of such files to an existing
736 user or group, using the @code{chown} or @code{chgrp} program.
742 @xref{File Permissions}, for information on how file permissions are
743 structured and how to specify them.
745 @deffn Test -perm mode
747 file's permissions are exactly @var{mode} (which can be numeric or symbolic).
748 Symbolic modes use mode 0 as a point of departure.
749 If @var{mode} starts with @samp{-}, true if
750 @emph{all} of the permissions set in @var{mode} are set for the file;
751 permissions not set in @var{mode} are ignored.
752 If @var{mode} starts with @samp{+}, true if
753 @emph{any} of the permissions set in @var{mode} are set for the file;
754 permissions not set in @var{mode} are ignored.
760 To search for files based on their contents, you can use the @code{grep}
761 program. For example, to find out which C source files in the current
762 directory contain the string @samp{thing}, you can do:
768 If you also want to search for the string in files in subdirectories,
769 you can combine @code{grep} with @code{find} and @code{xargs}, like
773 find . -name '*.[ch]' | xargs grep -l thing
776 The @samp{-l} option causes @code{grep} to print only the names of files
777 that contain the string, rather than the lines that contain it. The
778 string argument (@samp{thing}) is actually a regular expression, so it
779 can contain metacharacters. This method can be refined a little by
780 using the @samp{-r} option to make @code{xargs} not run @code{grep} if
781 @code{find} produces no output, and using the @code{find} action
782 @samp{-print0} and the @code{xargs} option @samp{-0} to avoid
783 misinterpreting files whose names contain spaces:
786 find . -name '*.[ch]' -print0 | xargs -r -0 grep -l thing
789 For a fuller treatment of finding files whose contents match a pattern,
790 see the manual page for @code{grep}.
795 Here is how to control which directories @code{find} searches, and how
796 it searches them. These two options allow you to process a horizontal
797 slice of a directory tree.
799 @deffn Option -maxdepth levels
800 Descend at most @var{levels} (a non-negative integer) levels of
801 directories below the command line arguments. @samp{-maxdepth 0} means
802 only apply the tests and actions to the command line arguments.
805 @deffn Option -mindepth levels
806 Do not apply any tests or actions at levels less than @var{levels} (a
807 non-negative integer). @samp{-mindepth 1} means process all files
808 except the command line arguments.
812 Process each directory's contents before the directory itself. Doing
813 this is a good idea when producing lists of files to archive with
814 @code{cpio} or @code{tar}. If a directory does not have write
815 permission for its owner, its contents can still be restored from the
816 archive since the directory's permissions are restored after its contents.
820 If @samp{-depth} is not given, true; do not descend into the current
821 directory. If @samp{-depth} is given, false; no effect. @samp{-prune}
822 only affects tests and actions that come after it in the expression, not
823 those that come before.
825 For example, to skip the directory @file{src/emacs} and all files and
826 directories under it, and print the names of the other files found:
829 find . -path './src/emacs' -prune -o -print
833 @deffn Option -noleaf
834 Do not optimize by assuming that directories contain 2 fewer
835 subdirectories than their hard link count. This option is needed when
836 searching filesystems that do not follow the Unix directory-link
837 convention, such as CD-ROM or MS-DOS filesystems or AFS volume mount
838 points. Each directory on a normal Unix filesystem has at least 2 hard
839 links: its name and its @file{.} entry. Additionally, its
840 subdirectories (if any) each have a @file{..} entry linked to that
841 directory. When @code{find} is examining a directory, after it has
842 statted 2 fewer subdirectories than the directory's link count, it knows
843 that the rest of the entries in the directory are non-directories
844 (@dfn{leaf} files in the directory tree). If only the files' names need
845 to be examined, there is no need to stat them; this gives a significant
846 increase in search speed.
852 A @dfn{filesystem} is a section of a disk, either on the local host or
853 mounted from a remote host over a network. Searching network
854 filesystems can be slow, so it is common to make @code{find} avoid them.
856 There are two ways to avoid searching certain filesystems. One way is
857 to tell @code{find} to only search one filesystem:
860 @deffnx Option -mount
861 Don't descend directories on other filesystems. These options are synonyms.
864 The other way is to check the type of filesystem each file is on, and
865 not descend directories that are on undesirable filesystem types:
867 @deffn Test -fstype type
868 True if the file is on a filesystem of type @var{type}. The valid
869 filesystem types vary among different versions of Unix; an incomplete
870 list of filesystem types that are accepted on some version of Unix or
873 ufs 4.2 4.3 nfs tmp mfs S51K S52K
875 You can use @samp{-printf} with the @samp{%F} directive to see the types
876 of your filesystems. @xref{Print File Information}. @samp{-fstype} is
877 usually used with @samp{-prune} to avoid searching remote filesystems
878 (@pxref{Directories}).
881 @node Combining Primaries With Operators
882 @section Combining Primaries With Operators
884 Operators build a complex expression from tests and actions.
885 The operators are, in order of decreasing precedence:
888 @item @asis{( @var{expr} )}
890 Force precedence. True if @var{expr} is true.
892 @item @asis{! @var{expr}}
893 @itemx @asis{-not @var{expr}}
896 True if @var{expr} is false.
898 @item @asis{@var{expr1 expr2}}
899 @itemx @asis{@var{expr1} -a @var{expr2}}
900 @itemx @asis{@var{expr1} -and @var{expr2}}
903 And; @var{expr2} is not evaluated if @var{expr1} is false.
905 @item @asis{@var{expr1} -o @var{expr2}}
906 @itemx @asis{@var{expr1} -or @var{expr2}}
909 Or; @var{expr2} is not evaluated if @var{expr1} is true.
911 @item @asis{@var{expr1} , @var{expr2}}
913 List; both @var{expr1} and @var{expr2} are always evaluated. True if
914 @var{expr2} is true. The value of @var{expr1} is discarded. This
915 operator lets you do multiple independent operations on one traversal,
916 without depending on whether other operations succeeded.
919 @code{find} searches the directory tree rooted at each file name by
920 evaluating the expression from left to right, according to the rules of
921 precedence, until the outcome is known (the left hand side is false for
922 @samp{-and}, true for @samp{-or}), at which point @code{find} moves on
923 to the next file name.
925 There are two other tests that can be useful in complex expressions:
935 @node Actions, Common Tasks, Finding Files, Top
938 There are several ways you can print information about the files that
939 match the criteria you gave in the @code{find} expression. You can
940 print the information either to the standard output or to a file that
941 you name. You can also execute commands that have the file names as
942 arguments. You can use those commands as further filters to select files.
946 * Print File Information::
951 @node Print File Name
952 @section Print File Name
955 True; print the full file name on the standard output, followed by a
959 @deffn Action -fprint file
960 True; print the full file name into file @var{file}, followed by a
961 newline. If @var{file} does not exist when @code{find} is run, it is
962 created; if it does exist, it is truncated to 0 bytes. The file names
963 @file{/dev/stdout} and @file{/dev/stderr} are handled specially; they
964 refer to the standard output and standard error output, respectively.
967 @node Print File Information
968 @section Print File Information
971 True; list the current file in @samp{ls -dils} format on the standard
972 output. The output looks like this:
975 204744 17 -rw-r--r-- 1 djm staff 17337 Nov 2 1992 ./lwall-quotes
982 The inode number of the file. @xref{Hard Links}, for how to find files
983 based on their inode number.
986 the number of blocks in the file. The block counts are of 1K blocks,
987 unless the environment variable @code{POSIXLY_CORRECT} is set, in which
988 case 512-byte blocks are used. @xref{Size}, for how to find files based
992 The file's type and permissions. The type is shown as a dash for a
993 regular file; for other file types, a letter like for @samp{-type} is
994 used (@pxref{Type}). The permissions are read, write, and execute for
995 the file's owner, its group, and other users, respectively; a dash means
996 the permission is not granted. @xref{File Permissions}, for more details
997 about file permissions. @xref{Permissions}, for how to find files based
998 on their permissions.
1001 The number of hard links to the file.
1004 The user who owns the file.
1010 The file's size in bytes.
1013 The date the file was last modified.
1016 The file's name. @samp{-ls} quotes non-printable characters in the file
1017 names using C-like backslash escapes.
1021 @deffn Action -fls file
1022 True; like @samp{-ls} but write to @var{file} like @samp{-fprint}
1023 (@pxref{Print File Name}).
1026 @deffn Action -printf format
1027 True; print @var{format} on the standard output, interpreting @samp{\}
1028 escapes and @samp{%} directives. Field widths and precisions can be
1029 specified as with the @code{printf} C function. Unlike @samp{-print},
1030 @samp{-printf} does not add a newline at the end of the string.
1033 @deffn Action -fprintf file format
1034 True; like @samp{-printf} but write to @var{file} like @samp{-fprint}
1035 (@pxref{Print File Name}).
1040 * Format Directives::
1047 The escapes that @samp{-printf} and @samp{-fprintf} recognize are:
1055 Stop printing from this format immediately and flush the output.
1067 A literal backslash (@samp{\}).
1069 The character whose ASCII code is NNN (octal).
1072 A @samp{\} character followed by any other character is treated as an
1073 ordinary character, so they both are printed, and a warning message is
1074 printed to the standard error output (because it was probably a typo).
1076 @node Format Directives
1077 @subsection Format Directives
1079 @samp{-printf} and @samp{-fprintf} support the following format
1080 directives to print information about the file being processed.
1081 The C @code{printf} function, field width and precision specifiers
1082 are supported, as applied to string (%s) types. I.E. you can specify
1083 "minimum field width"."maximum field width" for each directive.
1085 @samp{%%} is a literal percent sign. A @samp{%} character followed by
1086 an unrecognised character (i.e. not a known directive or printf field
1087 width and precision specifier), is discarded (but the unrecognised character
1088 is printed), and a warning message is printed to the standard error output
1089 (because it was probably a typo).
1093 * Ownership Directives::
1095 * Location Directives::
1099 @node Name Directives
1100 @subsubsection Name Directives
1106 File's name with any leading directories removed (only the last element).
1108 Leading directories of file's name (all but the last element and the
1111 File's name with the name of the command line argument under which
1112 it was found removed from the beginning.
1114 Command line argument under which file was found.
1117 @node Ownership Directives
1118 @subsubsection Ownership Directives
1122 File's group name, or numeric group ID if the group has no name.
1124 File's numeric group ID.
1126 File's user name, or numeric user ID if the user has no name.
1128 File's numeric user ID.
1130 File's permissions (in octal).
1133 @node Size Directives
1134 @subsubsection Size Directives
1138 File's size in 1K blocks (rounded up).
1140 File's size in 512-byte blocks (rounded up).
1142 File's size in bytes.
1145 @node Location Directives
1146 @subsubsection Location Directives
1150 File's depth in the directory tree; files named on the command line
1153 Type of the filesystem the file is on; this value can be used for
1154 @samp{-fstype} (@pxref{Directories}).
1156 Object of symbolic link (empty string if file is not a symbolic link).
1158 File's inode number (in decimal).
1160 Number of hard links to file.
1163 @node Time Directives
1164 @subsubsection Time Directives
1166 Some of these directives use the C @code{ctime} function. Its output
1167 depends on the current locale, but it typically looks like
1170 Wed Nov 2 00:42:36 1994
1175 File's last access time in the format returned by the C @code{ctime} function.
1177 File's last access time in the format specified by @var{k}
1178 (@pxref{Time Formats}).
1180 File's last status change time in the format returned by the C @code{ctime}
1183 File's last status change time in the format specified by @var{k}
1184 (@pxref{Time Formats}).
1186 File's last modification time in the format returned by the C @code{ctime}
1189 File's last modification time in the format specified by @var{k}
1190 (@pxref{Time Formats}).
1194 @subsection Time Formats
1196 Below are the formats for the directives @samp{%A}, @samp{%C}, and
1197 @samp{%T}, which print the file's timestamps. Some of these formats
1198 might not be available on all systems, due to differences in the C
1199 @code{strftime} function between systems.
1204 * Combined Time Formats::
1207 @node Time Components
1208 @subsubsection Time Components
1210 The following format directives print single components of the time.
1224 time zone (e.g., EDT), or nothing if no time zone is determinable
1230 seconds since Jan. 1, 1970, 00:00 GMT.
1233 @node Date Components
1234 @subsubsection Date Components
1236 The following format directives print single components of the date.
1240 locale's abbreviated weekday name (Sun..Sat)
1242 locale's full weekday name, variable length (Sunday..Saturday)
1245 locale's abbreviated month name (Jan..Dec)
1247 locale's full month name, variable length (January..December)
1251 day of month (01..31)
1255 day of year (001..366)
1257 week number of year with Sunday as first day of week (00..53)
1259 week number of year with Monday as first day of week (00..53)
1263 last two digits of year (00..99)
1266 @node Combined Time Formats
1267 @subsubsection Combined Time Formats
1269 The following format directives print combinations of time and date
1274 time, 12-hour (hh:mm:ss [AP]M)
1276 time, 24-hour (hh:mm:ss)
1278 locale's time representation (H:M:S)
1280 locale's date and time (Sat Nov 04 12:02:33 EST 1989)
1284 locale's date representation (mm/dd/yy)
1288 @section Run Commands
1290 You can use the list of file names created by @code{find} or
1291 @code{locate} as arguments to other commands. In this way you can
1292 perform arbitrary actions on the files.
1301 @subsection Single File
1303 Here is how to run a command on one file at a time.
1305 @deffn Action -exec command ;
1306 Execute @var{command}; true if 0 status is returned. @code{find} takes
1307 all arguments after @samp{-exec} to be part of the command until an
1308 argument consisting of @samp{;} is reached. It replaces the string
1309 @samp{@{@}} by the current file name being processed everywhere it
1310 occurs in the command. Both of these constructions need to be escaped
1311 (with a @samp{\}) or quoted to protect them from expansion by the shell.
1312 The command is executed in the directory in which @code{find} was run.
1314 For example, to compare each C header file in the current directory with
1315 the file @file{/tmp/master}:
1318 find . -name '*.h' -exec diff -u '@{@}' /tmp/master ';'
1322 @node Multiple Files
1323 @subsection Multiple Files
1325 Sometimes you need to process files alone. But when you
1326 don't, it is faster to run a command on as many files as possible at a
1327 time, rather than once per file. Doing this saves on the time it takes
1328 to start up the command each time.
1330 To run a command on more than one file at once, use the @code{xargs}
1331 command, which is invoked like this:
1334 xargs @r{[}@var{option}@dots{}@r{]} @r{[}@var{command} @r{[}@var{initial-arguments}@r{]}@r{]}
1337 @code{xargs} reads arguments from the standard input, delimited by
1338 blanks (which can be protected with double or single quotes or a
1339 backslash) or newlines. It executes the @var{command} (default is
1340 @file{/bin/echo}) one or more times with any @var{initial-arguments}
1341 followed by arguments read from standard input. Blank lines on the
1342 standard input are ignored.
1344 Instead of blank-delimited names, it is safer to use @samp{find -print0}
1345 or @samp{find -fprint0} and process the output by giving the @samp{-0}
1346 or @samp{--null} option to GNU @code{xargs}, GNU @code{tar}, GNU
1347 @code{cpio}, or @code{perl}.
1349 You can use shell command substitution (backquotes) to process a list of
1350 arguments, like this:
1353 grep -l sprintf `find $HOME -name '*.c' -print`
1356 However, that method produces an error if the length of the @samp{.c}
1357 file names exceeds the operating system's command-line length limit.
1358 @code{xargs} avoids that problem by running the command as many times as
1359 necessary without exceeding the limit:
1362 find $HOME -name '*.c' -print | xargs grep -l sprintf
1365 However, if the command needs to have its standard input be a terminal
1366 (@code{less}, for example), you have to use the shell command
1367 substitution method.
1369 The @code{xargs} command will process all its input, building command
1370 lines and executing them, unless one of the commands exits with a
1371 status of 255 (this will cause xargs to issue an error message and
1372 stop) or it reads a line contains the end of file string specified
1373 with the @samp{--eof} option.
1376 * Unsafe File Name Handling::
1377 * Safe File Name Handling::
1378 * Limiting Command Size::
1379 * Interspersing File Names::
1382 @node Unsafe File Name Handling
1383 @subsubsection Unsafe File Name Handling
1385 Because file names can contain quotes, backslashes, blank characters,
1386 and even newlines, it is not safe to process them using @code{xargs} in its
1387 default mode of operation. But since most files' names do not contain
1388 blanks, this problem occurs only infrequently. If you are only
1389 searching through files that you know have safe names, then you need not
1390 be concerned about it.
1392 @c This example is adapted from:
1393 @c From: pfalstad@stone.Princeton.EDU (Paul John Falstad)
1394 @c Newsgroups: comp.unix.shell
1395 @c Subject: Re: Beware xargs security holes
1396 @c Date: 16 Oct 90 19:12:06 GMT
1398 In many applications, if @code{xargs} botches processing a file because
1399 its name contains special characters, some data might be lost. The
1400 importance of this problem depends on the importance of the data and
1401 whether anyone notices the loss soon enough to correct it. However,
1402 here is an extreme example of the problems that using blank-delimited
1403 names can cause. If the following command is run daily from
1404 @code{cron}, then any user can remove any file on the system:
1407 find / -name '#*' -atime +7 -print | xargs rm
1410 For example, you could do something like this:
1418 and then @code{cron} would delete @file{/vmunix}, if it ran
1419 @code{xargs} with @file{/} as its current directory.
1421 To delete other files, for example @file{/u/joeuser/.plan}, you could do
1429 eg$ mkdir u u/joeuser u/joeuser/.plan'
1431 eg$ echo > u/joeuser/.plan'
1434 eg$ find . -name '#*' -print | xargs echo
1435 ./# ./# /u/joeuser/.plan /#foo
1438 @node Safe File Name Handling
1439 @subsubsection Safe File Name Handling
1441 Here is how to make @code{find} output file names so that they can be
1442 used by other programs without being mangled or misinterpreted. You can
1443 process file names generated this way by giving the @samp{-0} or
1444 @samp{--null} option to GNU @code{xargs}, GNU @code{tar}, GNU
1445 @code{cpio}, or @code{perl}.
1447 @deffn Action -print0
1448 True; print the full file name on the standard output, followed by a
1452 @deffn Action -fprint0 file
1453 True; like @samp{-print0} but write to @var{file} like @samp{-fprint}
1454 (@pxref{Print File Name}).
1457 @node Limiting Command Size
1458 @subsubsection Limiting Command Size
1460 @code{xargs} gives you control over how many arguments it passes to the
1461 command each time it executes it. By default, it uses up to
1462 @code{ARG_MAX} - 2k, or 20k, whichever is smaller, characters per
1463 command. It uses as many lines and arguments as fit within that limit.
1464 The following options modify those values.
1467 @item --no-run-if-empty
1469 If the standard input does not contain any nonblanks, do not run the
1470 command. By default, the command is run once even if there is no input.
1472 @item --max-lines@r{[}=@var{max-lines}@r{]}
1473 @itemx -l@r{[}@var{max-lines}@r{]}
1474 Use at most @var{max-lines} nonblank input lines per command line;
1475 @var{max-lines} defaults to 1 if omitted. Trailing blanks cause an
1476 input line to be logically continued on the next input line, for the
1477 purpose of counting the lines. Implies @samp{-x}.
1479 @item --max-args=@var{max-args}
1480 @itemx -n @var{max-args}
1481 Use at most @var{max-args} arguments per command line. Fewer than
1482 @var{max-args} arguments will be used if the size (see the @samp{-s}
1483 option) is exceeded, unless the @samp{-x} option is given, in which case
1484 @code{xargs} will exit.
1486 @item --max-chars=@var{max-chars}
1487 @itemx -s @var{max-chars}
1488 Use at most @var{max-chars} characters per command line, including the
1489 command and initial arguments and the terminating nulls at the ends of
1490 the argument strings.
1492 @item --max-procs=@var{max-procs}
1493 @itemx -P @var{max-procs}
1494 Run up to @var{max-procs} processes at a time; the default is 1. If
1495 @var{max-procs} is 0, @code{xargs} will run as many processes as
1496 possible at a time. Use the @samp{-n}, @samp{-s}, or @samp{-l} option
1497 with @samp{-P}; otherwise chances are that the command will be run only
1501 @node Interspersing File Names
1502 @subsubsection Interspersing File Names
1504 @code{xargs} can insert the name of the file it is processing between
1505 arguments you give for the command. Unless you also give options to
1506 limit the command size (@pxref{Limiting Command Size}), this mode of
1507 operation is equivalent to @samp{find -exec} (@pxref{Single File}).
1510 @item --replace@r{[}=@var{replace-str}@r{]}
1511 @itemx -i@r{[}@var{replace-str}@r{]}
1512 Replace occurrences of @var{replace-str} in the initial arguments with
1513 names read from standard input. Also, unquoted blanks do not terminate
1514 arguments. If @var{replace-str} is omitted, it defaults to @samp{@{@}}
1515 (like for @samp{find -exec}). Implies @samp{-x} and @samp{-l 1}. As an
1516 example, to sort each file the @file{bills} directory, leaving the
1517 output in that file name with @file{.sorted} appended, you could do:
1520 find bills -type f | xargs -iXX sort -o XX.sorted XX
1524 The equivalent command using @samp{find -exec} is:
1527 find bills -type f -exec sort -o '@{@}.sorted' '@{@}' ';'
1532 @subsection Querying
1534 To ask the user whether to execute a command on a single file, you can
1535 use the @code{find} primary @samp{-ok} instead of @samp{-exec}:
1537 @deffn Action -ok command ;
1538 Like @samp{-exec} (@pxref{Single File}), but ask the user first (on
1539 the standard input); if the response does not start with @samp{y} or
1540 @samp{Y}, do not run the command, and return false.
1543 When processing multiple files with a single command, to query the user
1544 you give @code{xargs} the following option. When using this option, you
1545 might find it useful to control the number of files processed per
1546 invocation of the command (@pxref{Limiting Command Size}).
1551 Prompt the user about whether to run each command line and read a line
1552 from the terminal. Only run the command line if the response starts
1553 with @samp{y} or @samp{Y}. Implies @samp{-t}.
1557 @section Adding Tests
1559 You can test for file attributes that none of the @code{find} builtin
1560 tests check. To do this, use @code{xargs} to run a program that filters
1561 a list of files printed by @code{find}. If possible, use @code{find}
1562 builtin tests to pare down the list, so the program run by @code{xargs}
1563 has less work to do. The tests builtin to @code{find} will likely run
1564 faster than tests that other programs perform.
1566 For example, here is a way to print the names of all of the unstripped
1567 binaries in the @file{/usr/local} directory tree. Builtin tests avoid
1568 running @code{file} on files that are not regular files or are not
1572 find /usr/local -type f -perm +a=x | xargs file |
1573 grep 'not stripped' | cut -d: -f1
1577 The @code{cut} program removes everything after the file name from the
1578 output of @code{file}.
1580 @c Idea from Martin Weitzel.
1581 If you want to place a special test somewhere in the middle of a
1582 @code{find} expression, you can use @samp{-exec} to run a program that
1583 performs the test. Because @samp{-exec} evaluates to the exit status of
1584 the executed program, you can write a program (which can be a shell
1585 script) that tests for a special attribute and make it exit with a true
1586 (zero) or false (non-zero) status. It is a good idea to place such a
1587 special test @emph{after} the builtin tests, because it starts a new
1588 process which could be avoided if a builtin test evaluates to false.
1589 Use this method only when @code{xargs} is not flexible enough, because
1590 starting one or more new processes to test each file is slower than
1591 using @code{xargs} to start one process that tests many files.
1593 Here is a shell script called @code{unstripped} that checks whether its
1594 argument is an unstripped binary file:
1598 file $1 | grep 'not stripped' > /dev/null
1601 This script relies on the fact that the shell exits with the status of
1602 the last program it executed, in this case @code{grep}. @code{grep}
1603 exits with a true status if it found any matches, false if not. Here is
1604 an example of using the script (assuming it is in your search path). It
1605 lists the stripped executables in the file @file{sbins} and the
1606 unstripped ones in @file{ubins}.
1609 find /usr/local -type f -perm +a=x \
1610 \( -exec unstripped '@{@}' \; -fprint ubins -o -fprint sbins \)
1613 @node Common Tasks, Databases, Actions, Top
1614 @chapter Common Tasks
1616 The sections that follow contain some extended examples that both give a
1617 good idea of the power of these programs, and show you how to solve
1618 common real-world problems.
1621 * Viewing And Editing::
1624 * Strange File Names::
1625 * Fixing Permissions::
1626 * Classifying Files::
1629 @node Viewing And Editing
1630 @section Viewing And Editing
1632 To view a list of files that meet certain criteria, simply run your file
1633 viewing program with the file names as arguments. Shells substitute a
1634 command enclosed in backquotes with its output, so the whole command
1638 less `find /usr/include -name '*.h' | xargs grep -l mode_t`
1642 You can edit those files by giving an editor name instead of a file
1648 You can pass a list of files produced by @code{find} to a file archiving
1649 program. GNU @code{tar} and @code{cpio} can both read lists of file
1650 names from the standard input---either delimited by nulls (the safe way)
1651 or by blanks (the lazy, risky default way). To use null-delimited
1652 names, give them the @samp{--null} option. You can store a file archive
1653 in a file, write it on a tape, or send it over a network to extract on
1656 One common use of @code{find} to archive files is to send a list of the
1657 files in a directory tree to @code{cpio}. Use @samp{-depth} so if a
1658 directory does not have write permission for its owner, its contents can
1659 still be restored from the archive since the directory's permissions are
1660 restored after its contents. Here is an example of doing this using
1661 @code{cpio}; you could use a more complex @code{find} expression to
1662 archive only certain files.
1665 find . -depth -print0 |
1666 cpio --create --null --format=crc --file=/dev/nrst0
1669 You could restore that archive using this command:
1672 cpio --extract --null --make-dir --unconditional \
1673 --preserve --file=/dev/nrst0
1676 Here are the commands to do the same things using @code{tar}:
1679 find . -depth -print0 |
1680 tar --create --null --files-from=- --file=/dev/nrst0
1682 tar --extract --null --preserve-perm --same-owner \
1686 @c Idea from Rick Sladkey.
1687 Here is an example of copying a directory from one machine to another:
1690 find . -depth -print0 | cpio -0o -Hnewc |
1691 rsh @var{other-machine} "cd `pwd` && cpio -i0dum"
1695 @section Cleaning Up
1697 @c Idea from Jim Meyering.
1698 This section gives examples of removing unwanted files in various situations.
1699 Here is a command to remove the CVS backup files created when an update
1703 find . -name '.#*' -print0 | xargs -0r rm -f
1706 @c Idea from Franc,ois Pinard.
1707 You can run this command to clean out your clutter in @file{/tmp}. You
1708 might place it in the file your shell runs when you log out
1709 (@file{.bash_logout}, @file{.logout}, or @file{.zlogout}, depending on
1710 which shell you use).
1713 find /tmp -user $LOGNAME -type f -print0 | xargs -0 -r rm -f
1716 @c Idea from Noah Friedman.
1717 To remove old Emacs backup and auto-save files, you can use a command
1718 like the following. It is especially important in this case to use
1719 null-terminated file names because Emacs packages like the VM mailer
1720 often create temporary file names with spaces in them, like @file{#reply
1721 to David J. MacKenzie<1>#}.
1724 find ~ \( -name '*~' -o -name '#*#' \) -print0 |
1725 xargs --no-run-if-empty --null rm -vf
1728 Removing old files from @file{/tmp} is commonly done from @code{cron}:
1730 @c Idea from Kaveh Ghazi.
1732 find /tmp /var/tmp -not -type d -mtime +3 -print0 |
1733 xargs --null --no-run-if-empty rm -f
1735 find /tmp /var/tmp -depth -mindepth 1 -type d -empty -exec rmdir @{@} \;
1738 The second @code{find} command above uses @samp{-depth} so it cleans out
1739 empty directories depth-first, hoping that the parents become empty and
1740 can be removed too. It uses @samp{-mindepth} to avoid removing
1741 @file{/tmp} itself if it becomes totally empty.
1743 @node Strange File Names
1744 @section Strange File Names
1747 @c From: tmatimar@isgtec.com (Ted Timar)
1748 @c Newsgroups: comp.unix.questions,comp.unix.shell,comp.answers,news.answers
1749 @c Subject: Unix - Frequently Asked Questions (2/7) [Frequent posting]
1750 @c Subject: How do I remove a file with funny characters in the filename ?
1751 @c Date: Thu Mar 18 17:16:55 EST 1993
1752 @code{find} can help you remove or rename a file with strange characters
1753 in its name. People are sometimes stymied by files whose names contain
1754 characters such as spaces, tabs, control characters, or characters with
1755 the high bit set. The simplest way to remove such files is:
1758 rm -i @var{some*pattern*that*matches*the*problem*file}
1761 @code{rm} asks you whether to remove each file matching the given
1762 pattern. If you are using an old shell, this approach might not work if
1763 the file name contains a character with the high bit set; the shell may
1764 strip it off. A more reliable way is:
1767 find . -maxdepth 1 @var{tests} -ok rm '@{@}' \;
1771 where @var{tests} uniquely identify the file. The @samp{-maxdepth 1}
1772 option prevents @code{find} from wasting time searching for the file in
1773 any subdirectories; if there are no subdirectories, you may omit it. A
1774 good way to uniquely identify the problem file is to figure out its
1781 Suppose you have a file whose name contains control characters, and you
1782 have found that its inode number is 12345. This command prompts you for
1783 whether to remove it:
1786 find . -maxdepth 1 -inum 12345 -ok rm -f '@{@}' \;
1789 If you don't want to be asked, perhaps because the file name may contain
1790 a strange character sequence that will mess up your screen when printed,
1791 then use @samp{-exec} instead of @samp{-ok}.
1793 If you want to rename the file instead, you can use @code{mv} instead of
1797 find . -maxdepth 1 -inum 12345 -ok mv '@{@}' @var{new-file-name} \;
1800 @node Fixing Permissions
1801 @section Fixing Permissions
1803 Suppose you want to make sure that everyone can write to the directories in a
1804 certain directory tree. Here is a way to find directories lacking either
1805 user or group write permission (or both), and fix their permissions:
1808 find . -type d -not -perm -ug=w | xargs chmod ug+w
1812 You could also reverse the operations, if you want to make sure that
1813 directories do @emph{not} have world write permission.
1815 @node Classifying Files
1816 @section Classifying Files
1819 @c From: martin@mwtech.UUCP (Martin Weitzel)
1820 @c Newsgroups: comp.unix.wizards,comp.unix.questions
1821 @c Subject: Advanced usage of 'find' (Re: Unix security automating script)
1822 @c Date: 22 Mar 90 15:05:19 GMT
1823 If you want to classify a set of files into several groups based on
1824 different criteria, you can use the comma operator to perform multiple
1825 independent tests on the files. Here is an example:
1828 find / -type d \( -perm -o=w -fprint allwrite , \
1829 -perm -o=x -fprint allexec \)
1831 echo "Directories that can be written to by everyone:"
1834 echo "Directories with search permissions for everyone:"
1838 @code{find} has only to make one scan through the directory tree (which
1839 is one of the most time consuming parts of its work).
1841 @node Databases, File Permissions, Common Tasks, Top
1842 @chapter File Name Databases
1844 The file name databases used by @code{locate} contain lists of files
1845 that were in particular directory trees when the databases were last
1846 updated. The file name of the default database is determined when
1847 @code{locate} and @code{updatedb} are configured and installed. The
1848 frequency with which the databases are updated and the directories for
1849 which they contain entries depend on how often @code{updatedb} is run,
1850 and with which arguments.
1853 * Database Locations::
1854 * Database Formats::
1857 @node Database Locations
1858 @section Database Locations
1860 There can be multiple file name databases. Users can select which
1861 databases @code{locate} searches using an environment variable or a
1862 command line option. The system administrator can choose the file name
1863 of the default database, the frequency with which the databases are
1864 updated, and the directories for which they contain entries. File name
1865 databases are updated by running the @code{updatedb} program, typically
1868 In networked environments, it often makes sense to build a database at
1869 the root of each filesystem, containing the entries for that filesystem.
1870 @code{updatedb} is then run for each filesystem on the fileserver where
1871 that filesystem is on a local disk, to prevent thrashing the network.
1872 Here are the options to @code{updatedb} to select which directories each
1873 database contains entries for:
1876 @item --localpaths='@var{path}@dots{}'
1877 Non-network directories to put in the database.
1878 Default is @file{/}.
1880 @item --netpaths='@var{path}@dots{}'
1881 Network (NFS, AFS, RFS, etc.) directories to put in the database.
1882 The environment variable @code{NETPATHS} also sets this value.
1886 @item --prunepaths='@var{path}@dots{}'
1887 Directories to not put in the database, which would otherwise be.
1888 The environment variable @code{PRUNEPATHS} also sets this value.
1889 Default is @file{/tmp /usr/tmp /var/tmp /afs}.
1891 @item --prunefs='@var{path}@dots{}'
1892 File systems to not put in the database, which would otherwise be.
1893 Note that files are pruned when a file system is reached;
1894 Any file system mounted under an undesired file system will be
1896 The environment variable @code{PRUNEFS} also sets this value.
1897 Default is @file{nfs NFS proc}.
1899 @item --output=@var{dbfile}
1900 The database file to build.
1901 Default is system-dependent, but typically @file{/usr/local/var/locatedb}.
1903 @item --localuser=@var{user}
1904 The user to search the non-network directories as, using @code{su}.
1905 Default is to search the non-network directories as the current user.
1906 You can also use the environment variable @code{LOCALUSER} to set this user.
1908 @item --netuser=@var{user}
1909 The user to search network directories as, using @code{su}.
1910 Default is @code{daemon}.
1911 You can also use the environment variable @code{NETUSER} to set this user.
1914 @node Database Formats
1915 @section Database Formats
1917 The file name databases contain lists of files that were in particular
1918 directory trees when the databases were last updated. The file name
1919 database format changed starting with GNU @code{locate} version 4.0 to
1920 allow machines with different byte orderings to share the databases. The
1921 new GNU @code{locate} can read both the old and new database formats.
1922 However, old versions of @code{locate} and @code{find} produce incorrect
1923 results if given a new-format database.
1926 * New Database Format::
1928 * Old Database Format::
1931 @node New Database Format
1932 @subsection New Database Format
1934 @code{updatedb} runs a program called @code{frcode} to
1935 @dfn{front-compress} the list of file names, which reduces the database
1936 size by a factor of 4 to 5. Front-compression (also known as
1937 incremental encoding) works as follows.
1939 The database entries are a sorted list (case-insensitively, for users'
1940 convenience). Since the list is sorted, each entry is likely to share a
1941 prefix (initial string) with the previous entry. Each database entry
1942 begins with an offset-differential count byte, which is the additional
1943 number of characters of prefix of the preceding entry to use beyond the
1944 number that the preceding entry is using of its predecessor. (The
1945 counts can be negative.) Following the count is a null-terminated ASCII
1946 remainder---the part of the name that follows the shared prefix.
1948 If the offset-differential count is larger than can be stored in a byte
1949 (+/-127), the byte has the value 0x80 and the count follows in a 2-byte
1950 word, with the high byte first (network byte order).
1952 Every database begins with a dummy entry for a file called
1953 @file{LOCATE02}, which @code{locate} checks for to ensure that the
1954 database file has the correct format; it ignores the entry in doing the
1957 Databases can not be concatenated together, even if the first (dummy)
1958 entry is trimmed from all but the first database. This is because the
1959 offset-differential count in the first entry of the second and following
1960 databases will be wrong.
1962 @node Sample Database
1963 @subsection Sample Database
1965 Sample input to @code{frcode}:
1966 @c with nulls changed to newlines:
1970 /usr/src/cmd/aardvark.c
1971 /usr/src/cmd/armadillo.c
1975 Length of the longest prefix of the preceding entry to share:
1984 Output from @code{frcode}, with trailing nulls changed to newlines
1985 and count bytes made printable:
1995 (6 = 14 - 8, and -9 = 5 - 14)
1997 @node Old Database Format
1998 @subsection Old Database Format
2000 The old database format is used by Unix @code{locate} and @code{find}
2001 programs and earlier releases of the GNU ones. @code{updatedb} produces
2002 this format if given the @samp{--old-format} option.
2004 @code{updatedb} runs programs called @code{bigram} and @code{code} to
2005 produce old-format databases. The old format differs from the new one
2006 in the following ways. Instead of each entry starting with an
2007 offset-differential count byte and ending with a null, byte values from
2008 0 through 28 indicate offset-differential counts from -14 through 14.
2009 The byte value indicating that a long offset-differential count follows
2010 is 0x1e (30), not 0x80. The long counts are stored in host byte order,
2011 which is not necessarily network byte order, and host integer word size,
2012 which is usually 4 bytes. They also represent a count 14 less than
2013 their value. The database lines have no termination byte; the start of
2014 the next line is indicated by its first byte having a value <= 30.
2016 In addition, instead of starting with a dummy entry, the old database
2017 format starts with a 256 byte table containing the 128 most common
2018 bigrams in the file list. A bigram is a pair of adjacent bytes. Bytes
2019 in the database that have the high bit set are indexes (with the high
2020 bit cleared) into the bigram table. The bigram and offset-differential
2021 count coding makes these databases 20-25% smaller than the new format,
2022 but makes them not 8-bit clean. Any byte in a file name that is in the
2023 ranges used for the special codes is replaced in the database by a
2024 question mark, which not coincidentally is the shell wildcard to match a
2027 The old format therefore can not faithfully store entries with non-ASCII
2028 characters. It therefore should not be used in internationalized
2031 @node File Permissions, Reference, Databases, Top
2032 @chapter File Permissions
2036 @node Reference, Primary Index, File Permissions, Top
2039 Below are summaries of the command line syntax for the programs
2040 discussed in this manual.
2045 * Invoking updatedb::
2049 @node Invoking find, Invoking locate, , Reference
2050 @section Invoking @code{find}
2053 find @r{[}@var{file}@dots{}@r{]} @r{[}@var{expression}@r{]}
2056 @code{find} searches the directory tree rooted at each file name
2057 @var{file} by evaluating the @var{expression} on each file it finds in
2060 @code{find} considers the first argument that begins with @samp{-},
2061 @samp{(}, @samp{)}, @samp{,}, or @samp{!} to be the beginning of the
2062 expression; any arguments before it are paths to search, and any
2063 arguments after it are the rest of the expression. If no paths are
2064 given, the current directory is used. If no expression is given, the
2065 expression @samp{-print} is used.
2067 @code{find} exits with status 0 if all files are processed successfully,
2068 greater than 0 if errors occur.
2070 @xref{Primary Index}, for a summary of all of the tests, actions, and
2071 options that the expression can contain.
2073 @code{find} also recognizes two options for administrative use:
2077 Print a summary of the command-line argument format and exit.
2079 Print the version number of @code{find} and exit.
2082 @node Invoking locate, Invoking updatedb, Invoking find, Reference
2083 @section Invoking @code{locate}
2086 locate @r{[}@var{option}@dots{}@r{]} @var{pattern}@dots{}
2090 @item --database=@var{path}
2091 @itemx -d @var{path}
2092 Instead of searching the default file name database, search the file
2093 name databases in @var{path}, which is a colon-separated list of
2094 database file names. You can also use the environment variable
2095 @code{LOCATE_PATH} to set the list of database files to search. The
2096 option overrides the environment variable if both are used.
2100 Only print out such names which currently exist (instead of such names
2101 which existed when the database was created).
2102 Note that this may slow down the program a lot, if there are many matches
2107 Ignore case distinctions in both the pattern and the file names.
2110 Print a summary of the options to @code{locate} and exit.
2113 Print the version number of @code{locate} and exit.
2116 @node Invoking updatedb, Invoking xargs, Invoking locate, Reference
2117 @section Invoking @code{updatedb}
2120 updatedb @r{[}@var{option}@dots{}@r{]}
2124 @item --localpaths='@var{path}@dots{}'
2125 Non-network directories to put in the database.
2126 Default is @file{/}.
2128 @item --netpaths='@var{path}@dots{}'
2129 Network (NFS, AFS, RFS, etc.) directories to put in the database.
2130 The environment variable @code{NETPATHS} also sets this value.
2133 @item --prunepaths='@var{path}@dots{}'
2134 Directories to not put in the database, which would otherwise be.
2135 The environment variable @code{PRUNEPATHS} also sets this value.
2136 Default is @file{/tmp /usr/tmp /var/tmp /afs}.
2138 @item --prunefs='@var{path}@dots{}'
2139 File systems to not put in the database, which would otherwise be.
2140 Note that files are pruned when a file system is reached;
2141 Any file system mounted under an undesired file system will be
2143 The environment variable @code{PRUNEFS} also sets this value.
2144 Default is @file{nfs NFS proc}.
2146 @item --output=@var{dbfile}
2147 The database file to build.
2148 Default is system-dependent, but typically @file{/usr/local/var/locatedb}.
2150 @item --localuser=@var{user}
2151 The user to search the non-network directories as, using @code{su}.
2152 Default is to search the non-network directories as the current user.
2153 You can also use the environment variable @code{LOCALUSER} to set this user.
2155 @item --netuser=@var{user}
2156 The user to search network directories as, using @code{su}(1).
2157 Default is @code{daemon}.
2158 You can also use the environment variable @code{NETUSER} to set this user.
2161 @node Invoking xargs, , Invoking updatedb, Reference
2162 @section Invoking @code{xargs}
2165 xargs @r{[}@var{option}@dots{}@r{]} @r{[}@var{command} @r{[}@var{initial-arguments}@r{]}@r{]}
2168 @code{xargs} exits with the following status:
2174 if any invocation of the command exited with status 1-125
2176 if the command exited with status 255
2178 if the command is killed by a signal
2180 if the command cannot be run
2182 if the command is not found
2184 if some other error occurred.
2190 Input filenames are terminated by a null character instead of by
2191 whitespace, and the quotes and backslash are not special (every
2192 character is taken literally). Disables the end of file string, which
2193 is treated like any other argument.
2195 @item --eof@r{[}=@var{eof-str}@r{]}
2196 @itemx -e@r{[}@var{eof-str}@r{]}
2197 Set the end of file string to @var{eof-str}. If the end of file string
2198 occurs as a line of input, the rest of the input is ignored. If
2199 @var{eof-str} is omitted, there is no end of file string. If this
2200 option is not given, the end of file string defaults to @samp{_}.
2203 Print a summary of the options to @code{xargs} and exit.
2205 @item --replace@r{[}=@var{replace-str}@r{]}
2206 @itemx -i@r{[}@var{replace-str}@r{]}
2207 Replace occurrences of @var{replace-str} in the initial arguments with
2208 names read from standard input. Also, unquoted blanks do not terminate
2209 arguments. If @var{replace-str} is omitted, it defaults to @samp{@{@}}
2210 (like for @samp{find -exec}). Implies @samp{-x} and @samp{-l 1}.
2212 @item --max-lines@r{[}=@var{max-lines}@r{]}
2213 @itemx -l@r{[}@var{max-lines}@r{]}
2214 Use at most @var{max-lines} nonblank input lines per command line;
2215 @var{max-lines} defaults to 1 if omitted. Trailing blanks cause an
2216 input line to be logically continued on the next input line, for the
2217 purpose of counting the lines. Implies @samp{-x}.
2219 @item --max-args=@var{max-args}
2220 @itemx -n @var{max-args}
2221 Use at most @var{max-args} arguments per command line. Fewer than
2222 @var{max-args} arguments will be used if the size (see the @samp{-s}
2223 option) is exceeded, unless the @samp{-x} option is given, in which case
2224 @code{xargs} will exit.
2228 Prompt the user about whether to run each command line and read a line
2229 from the terminal. Only run the command line if the response starts
2230 with @samp{y} or @samp{Y}. Implies @samp{-t}.
2232 @item --no-run-if-empty
2234 If the standard input does not contain any nonblanks, do not run the
2235 command. By default, the command is run once even if there is no input.
2237 @item --max-chars=@var{max-chars}
2238 @itemx -s @var{max-chars}
2239 Use at most @var{max-chars} characters per command line, including the
2240 command and initial arguments and the terminating nulls at the ends of
2241 the argument strings.
2245 Print the command line on the standard error output before executing
2249 Print the version number of @code{xargs} and exit.
2253 Exit if the size (see the @samp{-s} option) is exceeded.
2256 @item --max-procs=@var{max-procs}
2257 @itemx -P @var{max-procs}
2258 Run up to @var{max-procs} processes at a time; the default is 1. If
2259 @var{max-procs} is 0, @code{xargs} will run as many processes as
2263 @node Primary Index, , Reference, Top
2264 @unnumbered @code{find} Primary Index
2266 This is a list of all of the primaries (tests, actions, and options)
2267 that make up @code{find} expressions for selecting files. @xref{find
2268 Expressions}, for more information on expressions.
2275 @comment texi related words used by Emacs' spell checker ispell.el
2277 @comment LocalWords: texinfo setfilename settitle setchapternewpage
2278 @comment LocalWords: iftex finalout ifinfo DIR titlepage vskip pt
2279 @comment LocalWords: filll dir samp dfn noindent xref pxref
2280 @comment LocalWords: var deffn texi deffnx itemx emph asis
2281 @comment LocalWords: findex smallexample subsubsection cindex
2283 @comment other words used by Emacs' spell checker ispell.el
2284 @comment LocalWords: README fred updatedb xargs Plett Rendell akefile
2285 @comment LocalWords: args grep Filesystems fo foo fOo wildcards iname
2286 @comment LocalWords: ipath regex iregex expr fubar regexps
2287 @comment LocalWords: metacharacters macs sr sc inode lname ilname
2288 @comment LocalWords: sysdep noleaf ls inum xdev filesystems usr atime
2289 @comment LocalWords: ctime mtime amin cmin mmin al daystart Sladkey rm
2290 @comment LocalWords: anewer cnewer bckw rf xtype uname gname uid gid
2291 @comment LocalWords: nouser nogroup chown chgrp perm ch maxdepth
2292 @comment LocalWords: mindepth cpio src CD AFS statted stat fstype ufs
2293 @comment LocalWords: nfs tmp mfs printf fprint dils rw djm Nov lwall
2294 @comment LocalWords: POSIXLY fls fprintf strftime locale's EDT GMT AP
2295 @comment LocalWords: EST diff perl backquotes sprintf Falstad Oct cron
2296 @comment LocalWords: eg vmunix mkdir afs allexec allwrite ARG bigram
2297 @comment LocalWords: bigrams cd chmod comp crc CVS dbfile dum eof
2298 @comment LocalWords: fileserver filesystem fn frcode Ghazi Hnewc iXX
2299 @comment LocalWords: joeuser Kaveh localpaths localuser LOGNAME
2300 @comment LocalWords: Meyering mv netpaths netuser nonblank nonblanks
2301 @comment LocalWords: ois ok Pinard printindex proc procs prunefs
2302 @comment LocalWords: prunepaths pwd RFS rmadillo rmdir rsh sbins str
2303 @comment LocalWords: su Timar ubins ug unstripped vf VM Weitzel
2304 @comment LocalWords: wildcard zlogout