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{[}bckwMG@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}:
659 512-byte blocks (never 1024)
663 kilobytes (1024 bytes)
672 The `b' suffix always considers blocks to be 512 bytes. This is not
673 affected by the setting (or non-setting) of the POSIXLY_CORRECT
674 environment variable. This behaviour is different to the behaviour of
675 the @samp{-ls} action). If you want to use 1024-byte units, use the
678 The number can be prefixed with a `+' or a `-'. A plus sign indicates
679 that the test should succeed if the file uses at least @var{n} units
680 of storage (this is the way I normally use this test) and a minus sign
681 indicates that the test should succeed if the file uses less than
682 @var{n} units of storage. There is no `=' prefix, because that's the
685 The size does not count indirect blocks, but it does count blocks in
686 sparse files that are not actually allocated. This handling of sparse
687 files differs from the output of the @samp{%k} and @samp{%b} format
688 specifiers for the @samp{-printf} predicate.
693 True if the file is empty and is either a regular file or a directory.
694 This might make it a good candidate for deletion. This test is useful
695 with @samp{-depth} (@pxref{Directories}) and @samp{-exec rm -rf '@{@}' ';'}
696 (@pxref{Single File}).
703 True if the file is of type @var{c}:
707 block (buffered) special
709 character (unbuffered) special
726 The same as @samp{-type} unless the file is a symbolic link. For
727 symbolic links: if @samp{-follow} has not been given, true if the file
728 is a link to a file of type @var{c}; if @samp{-follow} has been given,
729 true if @var{c} is @samp{l}. In other words, for symbolic links,
730 @samp{-xtype} checks the type of the file that @samp{-type} does not
731 check. @xref{Symbolic Links}, for more information on @samp{-follow}.
737 @deffn Test -user uname
738 @deffnx Test -group gname
739 True if the file is owned by user @var{uname} (belongs to group @var{gname}).
740 A numeric ID is allowed.
745 True if the file's numeric user ID (group ID) is @var{n}. These tests
746 support ranges (@samp{+@var{n}} and @samp{-@var{n}}), unlike
747 @samp{-user} and @samp{-group}.
751 @deffnx Test -nogroup
752 True if no user corresponds to the file's numeric user ID (no group
753 corresponds to the numeric group ID). These cases usually mean that the
754 files belonged to users who have since been removed from the system.
755 You probably should change the ownership of such files to an existing
756 user or group, using the @code{chown} or @code{chgrp} program.
762 @xref{File Permissions}, for information on how file permissions are
763 structured and how to specify them.
765 @deffn Test -perm mode
767 file's permissions are exactly @var{mode} (which can be numeric or symbolic).
768 Symbolic modes use mode 0 as a point of departure.
769 If @var{mode} starts with @samp{-}, true if
770 @emph{all} of the permissions set in @var{mode} are set for the file;
771 permissions not set in @var{mode} are ignored.
772 If @var{mode} starts with @samp{+}, true if
773 @emph{any} of the permissions set in @var{mode} are set for the file;
774 permissions not set in @var{mode} are ignored.
780 To search for files based on their contents, you can use the @code{grep}
781 program. For example, to find out which C source files in the current
782 directory contain the string @samp{thing}, you can do:
788 If you also want to search for the string in files in subdirectories,
789 you can combine @code{grep} with @code{find} and @code{xargs}, like
793 find . -name '*.[ch]' | xargs grep -l thing
796 The @samp{-l} option causes @code{grep} to print only the names of files
797 that contain the string, rather than the lines that contain it. The
798 string argument (@samp{thing}) is actually a regular expression, so it
799 can contain metacharacters. This method can be refined a little by
800 using the @samp{-r} option to make @code{xargs} not run @code{grep} if
801 @code{find} produces no output, and using the @code{find} action
802 @samp{-print0} and the @code{xargs} option @samp{-0} to avoid
803 misinterpreting files whose names contain spaces:
806 find . -name '*.[ch]' -print0 | xargs -r -0 grep -l thing
809 For a fuller treatment of finding files whose contents match a pattern,
810 see the manual page for @code{grep}.
815 Here is how to control which directories @code{find} searches, and how
816 it searches them. These two options allow you to process a horizontal
817 slice of a directory tree.
819 @deffn Option -maxdepth levels
820 Descend at most @var{levels} (a non-negative integer) levels of
821 directories below the command line arguments. @samp{-maxdepth 0} means
822 only apply the tests and actions to the command line arguments.
825 @deffn Option -mindepth levels
826 Do not apply any tests or actions at levels less than @var{levels} (a
827 non-negative integer). @samp{-mindepth 1} means process all files
828 except the command line arguments.
832 Process each directory's contents before the directory itself. Doing
833 this is a good idea when producing lists of files to archive with
834 @code{cpio} or @code{tar}. If a directory does not have write
835 permission for its owner, its contents can still be restored from the
836 archive since the directory's permissions are restored after its contents.
840 If @samp{-depth} is not given, true; do not descend into the current
841 directory. If @samp{-depth} is given, false; no effect. @samp{-prune}
842 only affects tests and actions that come after it in the expression, not
843 those that come before.
845 For example, to skip the directory @file{src/emacs} and all files and
846 directories under it, and print the names of the other files found:
849 find . -path './src/emacs' -prune -o -print
853 @deffn Option -noleaf
854 Do not optimize by assuming that directories contain 2 fewer
855 subdirectories than their hard link count. This option is needed when
856 searching filesystems that do not follow the Unix directory-link
857 convention, such as CD-ROM or MS-DOS filesystems or AFS volume mount
858 points. Each directory on a normal Unix filesystem has at least 2 hard
859 links: its name and its @file{.} entry. Additionally, its
860 subdirectories (if any) each have a @file{..} entry linked to that
861 directory. When @code{find} is examining a directory, after it has
862 statted 2 fewer subdirectories than the directory's link count, it knows
863 that the rest of the entries in the directory are non-directories
864 (@dfn{leaf} files in the directory tree). If only the files' names need
865 to be examined, there is no need to stat them; this gives a significant
866 increase in search speed.
869 @deffn Option -ignore_readdir_race
870 If a file disappears after its name has been read from a directory but
871 before @code{find} gets around to examining the file with @code{stat},
872 don't issue an error message. If you don't specify this option, an
873 error message will be issued. This option can be useful in system
874 scripts (cron scripts, for example) that examine areas of the
875 filesystem that change frequently (mail queues, temporary directories,
876 and so forth), because this scenario is common for those sorts of
877 directories. Completely silencing error messages from @code{find} is
878 undesirable, so this option neatly solves the problem. There is no
879 way to search one part of the filesystem with this option on and part
880 of it with this option off, though.
883 @deffn Option -noignore_readdir_race
884 This option reverses the effect of the @samp{-ignore_readdir_race} option.
891 A @dfn{filesystem} is a section of a disk, either on the local host or
892 mounted from a remote host over a network. Searching network
893 filesystems can be slow, so it is common to make @code{find} avoid them.
895 There are two ways to avoid searching certain filesystems. One way is
896 to tell @code{find} to only search one filesystem:
899 @deffnx Option -mount
900 Don't descend directories on other filesystems. These options are synonyms.
903 The other way is to check the type of filesystem each file is on, and
904 not descend directories that are on undesirable filesystem types:
906 @deffn Test -fstype type
907 True if the file is on a filesystem of type @var{type}. The valid
908 filesystem types vary among different versions of Unix; an incomplete
909 list of filesystem types that are accepted on some version of Unix or
912 ufs 4.2 4.3 nfs tmp mfs S51K S52K
914 You can use @samp{-printf} with the @samp{%F} directive to see the types
915 of your filesystems. @xref{Print File Information}. @samp{-fstype} is
916 usually used with @samp{-prune} to avoid searching remote filesystems
917 (@pxref{Directories}).
920 @node Combining Primaries With Operators
921 @section Combining Primaries With Operators
923 Operators build a complex expression from tests and actions.
924 The operators are, in order of decreasing precedence:
927 @item @asis{( @var{expr} )}
929 Force precedence. True if @var{expr} is true.
931 @item @asis{! @var{expr}}
932 @itemx @asis{-not @var{expr}}
935 True if @var{expr} is false.
937 @item @asis{@var{expr1 expr2}}
938 @itemx @asis{@var{expr1} -a @var{expr2}}
939 @itemx @asis{@var{expr1} -and @var{expr2}}
942 And; @var{expr2} is not evaluated if @var{expr1} is false.
944 @item @asis{@var{expr1} -o @var{expr2}}
945 @itemx @asis{@var{expr1} -or @var{expr2}}
948 Or; @var{expr2} is not evaluated if @var{expr1} is true.
950 @item @asis{@var{expr1} , @var{expr2}}
952 List; both @var{expr1} and @var{expr2} are always evaluated. True if
953 @var{expr2} is true. The value of @var{expr1} is discarded. This
954 operator lets you do multiple independent operations on one traversal,
955 without depending on whether other operations succeeded.
958 @code{find} searches the directory tree rooted at each file name by
959 evaluating the expression from left to right, according to the rules of
960 precedence, until the outcome is known (the left hand side is false for
961 @samp{-and}, true for @samp{-or}), at which point @code{find} moves on
962 to the next file name.
964 There are two other tests that can be useful in complex expressions:
974 @node Actions, Common Tasks, Finding Files, Top
977 There are several ways you can print information about the files that
978 match the criteria you gave in the @code{find} expression. You can
979 print the information either to the standard output or to a file that
980 you name. You can also execute commands that have the file names as
981 arguments. You can use those commands as further filters to select files.
985 * Print File Information::
990 @node Print File Name
991 @section Print File Name
994 True; print the full file name on the standard output, followed by a
998 @deffn Action -fprint file
999 True; print the full file name into file @var{file}, followed by a
1000 newline. If @var{file} does not exist when @code{find} is run, it is
1001 created; if it does exist, it is truncated to 0 bytes. The file names
1002 @file{/dev/stdout} and @file{/dev/stderr} are handled specially; they
1003 refer to the standard output and standard error output, respectively.
1006 @node Print File Information
1007 @section Print File Information
1010 True; list the current file in @samp{ls -dils} format on the standard
1011 output. The output looks like this:
1014 204744 17 -rw-r--r-- 1 djm staff 17337 Nov 2 1992 ./lwall-quotes
1021 The inode number of the file. @xref{Hard Links}, for how to find files
1022 based on their inode number.
1025 the number of blocks in the file. The block counts are of 1K blocks,
1026 unless the environment variable @code{POSIXLY_CORRECT} is set, in which
1027 case 512-byte blocks are used. @xref{Size}, for how to find files based
1031 The file's type and permissions. The type is shown as a dash for a
1032 regular file; for other file types, a letter like for @samp{-type} is
1033 used (@pxref{Type}). The permissions are read, write, and execute for
1034 the file's owner, its group, and other users, respectively; a dash means
1035 the permission is not granted. @xref{File Permissions}, for more details
1036 about file permissions. @xref{Permissions}, for how to find files based
1037 on their permissions.
1040 The number of hard links to the file.
1043 The user who owns the file.
1049 The file's size in bytes.
1052 The date the file was last modified.
1055 The file's name. @samp{-ls} quotes non-printable characters in the file
1056 names using C-like backslash escapes.
1060 @deffn Action -fls file
1061 True; like @samp{-ls} but write to @var{file} like @samp{-fprint}
1062 (@pxref{Print File Name}).
1065 @deffn Action -printf format
1066 True; print @var{format} on the standard output, interpreting @samp{\}
1067 escapes and @samp{%} directives. Field widths and precisions can be
1068 specified as with the @code{printf} C function. Unlike @samp{-print},
1069 @samp{-printf} does not add a newline at the end of the string.
1072 @deffn Action -fprintf file format
1073 True; like @samp{-printf} but write to @var{file} like @samp{-fprint}
1074 (@pxref{Print File Name}).
1079 * Format Directives::
1086 The escapes that @samp{-printf} and @samp{-fprintf} recognize are:
1094 Stop printing from this format immediately and flush the output.
1106 A literal backslash (@samp{\}).
1108 The character whose ASCII code is NNN (octal).
1111 A @samp{\} character followed by any other character is treated as an
1112 ordinary character, so they both are printed, and a warning message is
1113 printed to the standard error output (because it was probably a typo).
1115 @node Format Directives
1116 @subsection Format Directives
1118 @samp{-printf} and @samp{-fprintf} support the following format
1119 directives to print information about the file being processed.
1120 The C @code{printf} function, field width and precision specifiers
1121 are supported, as applied to string (%s) types. I.E. you can specify
1122 "minimum field width"."maximum field width" for each directive.
1124 @samp{%%} is a literal percent sign. A @samp{%} character followed by
1125 an unrecognised character (i.e. not a known directive or printf field
1126 width and precision specifier), is discarded (but the unrecognised character
1127 is printed), and a warning message is printed to the standard error output
1128 (because it was probably a typo).
1132 * Ownership Directives::
1134 * Location Directives::
1138 @node Name Directives
1139 @subsubsection Name Directives
1145 File's name with any leading directories removed (only the last element).
1147 Leading directories of file's name (all but the last element and the
1150 File's name with the name of the command line argument under which
1151 it was found removed from the beginning.
1153 Command line argument under which file was found.
1156 @node Ownership Directives
1157 @subsubsection Ownership Directives
1161 File's group name, or numeric group ID if the group has no name.
1163 File's numeric group ID.
1165 File's user name, or numeric user ID if the user has no name.
1167 File's numeric user ID.
1169 File's permissions (in octal).
1172 @node Size Directives
1173 @subsubsection Size Directives
1177 Amount of disk space occupied by the file, measured in 1K blocks
1178 (rounded up). This can be less than the length of the file if
1179 it is a sparse file (that is, it has ``holes'').
1181 File's size in 512-byte blocks (rounded up). This also can be less
1182 than the length of the file, if the file is sparse.
1184 File's size in bytes.
1187 @node Location Directives
1188 @subsubsection Location Directives
1192 File's depth in the directory tree; files named on the command line
1195 Type of the filesystem the file is on; this value can be used for
1196 @samp{-fstype} (@pxref{Directories}).
1198 Object of symbolic link (empty string if file is not a symbolic link).
1200 File's inode number (in decimal).
1202 Number of hard links to file.
1205 @node Time Directives
1206 @subsubsection Time Directives
1208 Some of these directives use the C @code{ctime} function. Its output
1209 depends on the current locale, but it typically looks like
1212 Wed Nov 2 00:42:36 1994
1217 File's last access time in the format returned by the C @code{ctime} function.
1219 File's last access time in the format specified by @var{k}
1220 (@pxref{Time Formats}).
1222 File's last status change time in the format returned by the C @code{ctime}
1225 File's last status change time in the format specified by @var{k}
1226 (@pxref{Time Formats}).
1228 File's last modification time in the format returned by the C @code{ctime}
1231 File's last modification time in the format specified by @var{k}
1232 (@pxref{Time Formats}).
1236 @subsection Time Formats
1238 Below are the formats for the directives @samp{%A}, @samp{%C}, and
1239 @samp{%T}, which print the file's timestamps. Some of these formats
1240 might not be available on all systems, due to differences in the C
1241 @code{strftime} function between systems.
1246 * Combined Time Formats::
1249 @node Time Components
1250 @subsubsection Time Components
1252 The following format directives print single components of the time.
1266 time zone (e.g., EDT), or nothing if no time zone is determinable
1272 seconds since Jan. 1, 1970, 00:00 GMT.
1275 @node Date Components
1276 @subsubsection Date Components
1278 The following format directives print single components of the date.
1282 locale's abbreviated weekday name (Sun..Sat)
1284 locale's full weekday name, variable length (Sunday..Saturday)
1287 locale's abbreviated month name (Jan..Dec)
1289 locale's full month name, variable length (January..December)
1293 day of month (01..31)
1297 day of year (001..366)
1299 week number of year with Sunday as first day of week (00..53)
1301 week number of year with Monday as first day of week (00..53)
1305 last two digits of year (00..99)
1308 @node Combined Time Formats
1309 @subsubsection Combined Time Formats
1311 The following format directives print combinations of time and date
1316 time, 12-hour (hh:mm:ss [AP]M)
1318 time, 24-hour (hh:mm:ss)
1320 locale's time representation (H:M:S)
1322 locale's date and time (Sat Nov 04 12:02:33 EST 1989)
1326 locale's date representation (mm/dd/yy)
1330 @section Run Commands
1332 You can use the list of file names created by @code{find} or
1333 @code{locate} as arguments to other commands. In this way you can
1334 perform arbitrary actions on the files.
1343 @subsection Single File
1345 Here is how to run a command on one file at a time.
1347 @deffn Action -exec command ;
1348 Execute @var{command}; true if 0 status is returned. @code{find} takes
1349 all arguments after @samp{-exec} to be part of the command until an
1350 argument consisting of @samp{;} is reached. It replaces the string
1351 @samp{@{@}} by the current file name being processed everywhere it
1352 occurs in the command. Both of these constructions need to be escaped
1353 (with a @samp{\}) or quoted to protect them from expansion by the shell.
1354 The command is executed in the directory in which @code{find} was run.
1356 For example, to compare each C header file in the current directory with
1357 the file @file{/tmp/master}:
1360 find . -name '*.h' -exec diff -u '@{@}' /tmp/master ';'
1364 @node Multiple Files
1365 @subsection Multiple Files
1367 Sometimes you need to process files alone. But when you
1368 don't, it is faster to run a command on as many files as possible at a
1369 time, rather than once per file. Doing this saves on the time it takes
1370 to start up the command each time.
1372 To run a command on more than one file at once, use the @code{xargs}
1373 command, which is invoked like this:
1376 xargs @r{[}@var{option}@dots{}@r{]} @r{[}@var{command} @r{[}@var{initial-arguments}@r{]}@r{]}
1379 @code{xargs} reads arguments from the standard input, delimited by
1380 blanks (which can be protected with double or single quotes or a
1381 backslash) or newlines. It executes the @var{command} (default is
1382 @file{/bin/echo}) one or more times with any @var{initial-arguments}
1383 followed by arguments read from standard input. Blank lines on the
1384 standard input are ignored.
1386 Instead of blank-delimited names, it is safer to use @samp{find -print0}
1387 or @samp{find -fprint0} and process the output by giving the @samp{-0}
1388 or @samp{--null} option to GNU @code{xargs}, GNU @code{tar}, GNU
1389 @code{cpio}, or @code{perl}.
1391 You can use shell command substitution (backquotes) to process a list of
1392 arguments, like this:
1395 grep -l sprintf `find $HOME -name '*.c' -print`
1398 However, that method produces an error if the length of the @samp{.c}
1399 file names exceeds the operating system's command-line length limit.
1400 @code{xargs} avoids that problem by running the command as many times as
1401 necessary without exceeding the limit:
1404 find $HOME -name '*.c' -print | xargs grep -l sprintf
1407 However, if the command needs to have its standard input be a terminal
1408 (@code{less}, for example), you have to use the shell command
1409 substitution method.
1411 The @code{xargs} command will process all its input, building command
1412 lines and executing them, unless one of the commands exits with a
1413 status of 255 (this will cause xargs to issue an error message and
1414 stop) or it reads a line contains the end of file string specified
1415 with the @samp{--eof} option.
1418 * Unsafe File Name Handling::
1419 * Safe File Name Handling::
1420 * Limiting Command Size::
1421 * Interspersing File Names::
1424 @node Unsafe File Name Handling
1425 @subsubsection Unsafe File Name Handling
1427 Because file names can contain quotes, backslashes, blank characters,
1428 and even newlines, it is not safe to process them using @code{xargs} in its
1429 default mode of operation. But since most files' names do not contain
1430 blanks, this problem occurs only infrequently. If you are only
1431 searching through files that you know have safe names, then you need not
1432 be concerned about it.
1434 @c This example is adapted from:
1435 @c From: pfalstad@stone.Princeton.EDU (Paul John Falstad)
1436 @c Newsgroups: comp.unix.shell
1437 @c Subject: Re: Beware xargs security holes
1438 @c Date: 16 Oct 90 19:12:06 GMT
1440 In many applications, if @code{xargs} botches processing a file because
1441 its name contains special characters, some data might be lost. The
1442 importance of this problem depends on the importance of the data and
1443 whether anyone notices the loss soon enough to correct it. However,
1444 here is an extreme example of the problems that using blank-delimited
1445 names can cause. If the following command is run daily from
1446 @code{cron}, then any user can remove any file on the system:
1449 find / -name '#*' -atime +7 -print | xargs rm
1452 For example, you could do something like this:
1460 and then @code{cron} would delete @file{/vmunix}, if it ran
1461 @code{xargs} with @file{/} as its current directory.
1463 To delete other files, for example @file{/u/joeuser/.plan}, you could do
1471 eg$ mkdir u u/joeuser u/joeuser/.plan'
1473 eg$ echo > u/joeuser/.plan'
1476 eg$ find . -name '#*' -print | xargs echo
1477 ./# ./# /u/joeuser/.plan /#foo
1480 @node Safe File Name Handling
1481 @subsubsection Safe File Name Handling
1483 Here is how to make @code{find} output file names so that they can be
1484 used by other programs without being mangled or misinterpreted. You can
1485 process file names generated this way by giving the @samp{-0} or
1486 @samp{--null} option to GNU @code{xargs}, GNU @code{tar}, GNU
1487 @code{cpio}, or @code{perl}.
1489 @deffn Action -print0
1490 True; print the full file name on the standard output, followed by a
1494 @deffn Action -fprint0 file
1495 True; like @samp{-print0} but write to @var{file} like @samp{-fprint}
1496 (@pxref{Print File Name}).
1499 @node Limiting Command Size
1500 @subsubsection Limiting Command Size
1502 @code{xargs} gives you control over how many arguments it passes to the
1503 command each time it executes it. By default, it uses up to
1504 @code{ARG_MAX} - 2k, or 20k, whichever is smaller, characters per
1505 command. It uses as many lines and arguments as fit within that limit.
1506 The following options modify those values.
1509 @item --no-run-if-empty
1511 If the standard input does not contain any nonblanks, do not run the
1512 command. By default, the command is run once even if there is no input.
1514 @item --max-lines@r{[}=@var{max-lines}@r{]}
1515 @itemx -l@r{[}@var{max-lines}@r{]}
1516 Use at most @var{max-lines} nonblank input lines per command line;
1517 @var{max-lines} defaults to 1 if omitted. Trailing blanks cause an
1518 input line to be logically continued on the next input line, for the
1519 purpose of counting the lines. Implies @samp{-x}.
1521 @item --max-args=@var{max-args}
1522 @itemx -n @var{max-args}
1523 Use at most @var{max-args} arguments per command line. Fewer than
1524 @var{max-args} arguments will be used if the size (see the @samp{-s}
1525 option) is exceeded, unless the @samp{-x} option is given, in which case
1526 @code{xargs} will exit.
1528 @item --max-chars=@var{max-chars}
1529 @itemx -s @var{max-chars}
1530 Use at most @var{max-chars} characters per command line, including the
1531 command and initial arguments and the terminating nulls at the ends of
1532 the argument strings.
1534 @item --max-procs=@var{max-procs}
1535 @itemx -P @var{max-procs}
1536 Run up to @var{max-procs} processes at a time; the default is 1. If
1537 @var{max-procs} is 0, @code{xargs} will run as many processes as
1538 possible at a time. Use the @samp{-n}, @samp{-s}, or @samp{-l} option
1539 with @samp{-P}; otherwise chances are that the command will be run only
1543 @node Interspersing File Names
1544 @subsubsection Interspersing File Names
1546 @code{xargs} can insert the name of the file it is processing between
1547 arguments you give for the command. Unless you also give options to
1548 limit the command size (@pxref{Limiting Command Size}), this mode of
1549 operation is equivalent to @samp{find -exec} (@pxref{Single File}).
1552 @item --replace@r{[}=@var{replace-str}@r{]}
1553 @itemx -i@r{[}@var{replace-str}@r{]}
1554 Replace occurrences of @var{replace-str} in the initial arguments with
1555 names read from standard input. Also, unquoted blanks do not terminate
1556 arguments. If @var{replace-str} is omitted, it defaults to @samp{@{@}}
1557 (like for @samp{find -exec}). Implies @samp{-x} and @samp{-l 1}. As an
1558 example, to sort each file the @file{bills} directory, leaving the
1559 output in that file name with @file{.sorted} appended, you could do:
1562 find bills -type f | xargs -iXX sort -o XX.sorted XX
1566 The equivalent command using @samp{find -exec} is:
1569 find bills -type f -exec sort -o '@{@}.sorted' '@{@}' ';'
1574 @subsection Querying
1576 To ask the user whether to execute a command on a single file, you can
1577 use the @code{find} primary @samp{-ok} instead of @samp{-exec}:
1579 @deffn Action -ok command ;
1580 Like @samp{-exec} (@pxref{Single File}), but ask the user first (on
1581 the standard input); if the response does not start with @samp{y} or
1582 @samp{Y}, do not run the command, and return false.
1585 When processing multiple files with a single command, to query the user
1586 you give @code{xargs} the following option. When using this option, you
1587 might find it useful to control the number of files processed per
1588 invocation of the command (@pxref{Limiting Command Size}).
1593 Prompt the user about whether to run each command line and read a line
1594 from the terminal. Only run the command line if the response starts
1595 with @samp{y} or @samp{Y}. Implies @samp{-t}.
1599 @section Adding Tests
1601 You can test for file attributes that none of the @code{find} builtin
1602 tests check. To do this, use @code{xargs} to run a program that filters
1603 a list of files printed by @code{find}. If possible, use @code{find}
1604 builtin tests to pare down the list, so the program run by @code{xargs}
1605 has less work to do. The tests builtin to @code{find} will likely run
1606 faster than tests that other programs perform.
1608 For example, here is a way to print the names of all of the unstripped
1609 binaries in the @file{/usr/local} directory tree. Builtin tests avoid
1610 running @code{file} on files that are not regular files or are not
1614 find /usr/local -type f -perm +a=x | xargs file |
1615 grep 'not stripped' | cut -d: -f1
1619 The @code{cut} program removes everything after the file name from the
1620 output of @code{file}.
1622 @c Idea from Martin Weitzel.
1623 If you want to place a special test somewhere in the middle of a
1624 @code{find} expression, you can use @samp{-exec} to run a program that
1625 performs the test. Because @samp{-exec} evaluates to the exit status of
1626 the executed program, you can write a program (which can be a shell
1627 script) that tests for a special attribute and make it exit with a true
1628 (zero) or false (non-zero) status. It is a good idea to place such a
1629 special test @emph{after} the builtin tests, because it starts a new
1630 process which could be avoided if a builtin test evaluates to false.
1631 Use this method only when @code{xargs} is not flexible enough, because
1632 starting one or more new processes to test each file is slower than
1633 using @code{xargs} to start one process that tests many files.
1635 Here is a shell script called @code{unstripped} that checks whether its
1636 argument is an unstripped binary file:
1640 file $1 | grep 'not stripped' > /dev/null
1643 This script relies on the fact that the shell exits with the status of
1644 the last program it executed, in this case @code{grep}. @code{grep}
1645 exits with a true status if it found any matches, false if not. Here is
1646 an example of using the script (assuming it is in your search path). It
1647 lists the stripped executables in the file @file{sbins} and the
1648 unstripped ones in @file{ubins}.
1651 find /usr/local -type f -perm +a=x \
1652 \( -exec unstripped '@{@}' \; -fprint ubins -o -fprint sbins \)
1655 @node Common Tasks, Databases, Actions, Top
1656 @chapter Common Tasks
1658 The sections that follow contain some extended examples that both give a
1659 good idea of the power of these programs, and show you how to solve
1660 common real-world problems.
1663 * Viewing And Editing::
1666 * Strange File Names::
1667 * Fixing Permissions::
1668 * Classifying Files::
1671 @node Viewing And Editing
1672 @section Viewing And Editing
1674 To view a list of files that meet certain criteria, simply run your file
1675 viewing program with the file names as arguments. Shells substitute a
1676 command enclosed in backquotes with its output, so the whole command
1680 less `find /usr/include -name '*.h' | xargs grep -l mode_t`
1684 You can edit those files by giving an editor name instead of a file
1690 You can pass a list of files produced by @code{find} to a file archiving
1691 program. GNU @code{tar} and @code{cpio} can both read lists of file
1692 names from the standard input---either delimited by nulls (the safe way)
1693 or by blanks (the lazy, risky default way). To use null-delimited
1694 names, give them the @samp{--null} option. You can store a file archive
1695 in a file, write it on a tape, or send it over a network to extract on
1698 One common use of @code{find} to archive files is to send a list of the
1699 files in a directory tree to @code{cpio}. Use @samp{-depth} so if a
1700 directory does not have write permission for its owner, its contents can
1701 still be restored from the archive since the directory's permissions are
1702 restored after its contents. Here is an example of doing this using
1703 @code{cpio}; you could use a more complex @code{find} expression to
1704 archive only certain files.
1707 find . -depth -print0 |
1708 cpio --create --null --format=crc --file=/dev/nrst0
1711 You could restore that archive using this command:
1714 cpio --extract --null --make-dir --unconditional \
1715 --preserve --file=/dev/nrst0
1718 Here are the commands to do the same things using @code{tar}:
1721 find . -depth -print0 |
1722 tar --create --null --files-from=- --file=/dev/nrst0
1724 tar --extract --null --preserve-perm --same-owner \
1728 @c Idea from Rick Sladkey.
1729 Here is an example of copying a directory from one machine to another:
1732 find . -depth -print0 | cpio -0o -Hnewc |
1733 rsh @var{other-machine} "cd `pwd` && cpio -i0dum"
1737 @section Cleaning Up
1739 @c Idea from Jim Meyering.
1740 This section gives examples of removing unwanted files in various situations.
1741 Here is a command to remove the CVS backup files created when an update
1745 find . -name '.#*' -print0 | xargs -0r rm -f
1748 @c Idea from Franc,ois Pinard.
1749 You can run this command to clean out your clutter in @file{/tmp}. You
1750 might place it in the file your shell runs when you log out
1751 (@file{.bash_logout}, @file{.logout}, or @file{.zlogout}, depending on
1752 which shell you use).
1755 find /tmp -user $LOGNAME -type f -print0 | xargs -0 -r rm -f
1758 If your @code{find} command removes directories, you may find that
1759 you get a spurious error message when @code{find} tries to recurse
1760 into a directory that has now been removed. Using the @samp{-depth}
1761 option will normally resolve this problem.
1763 @c Idea from Noah Friedman.
1764 To remove old Emacs backup and auto-save files, you can use a command
1765 like the following. It is especially important in this case to use
1766 null-terminated file names because Emacs packages like the VM mailer
1767 often create temporary file names with spaces in them, like @file{#reply
1768 to David J. MacKenzie<1>#}.
1771 find ~ \( -name '*~' -o -name '#*#' \) -print0 |
1772 xargs --no-run-if-empty --null rm -vf
1775 Removing old files from @file{/tmp} is commonly done from @code{cron}:
1777 @c Idea from Kaveh Ghazi.
1779 find /tmp /var/tmp -not -type d -mtime +3 -print0 |
1780 xargs --null --no-run-if-empty rm -f
1782 find /tmp /var/tmp -depth -mindepth 1 -type d -empty -exec rmdir @{@} \;
1785 The second @code{find} command above uses @samp{-depth} so it cleans out
1786 empty directories depth-first, hoping that the parents become empty and
1787 can be removed too. It uses @samp{-mindepth} to avoid removing
1788 @file{/tmp} itself if it becomes totally empty.
1790 @node Strange File Names
1791 @section Strange File Names
1794 @c From: tmatimar@isgtec.com (Ted Timar)
1795 @c Newsgroups: comp.unix.questions,comp.unix.shell,comp.answers,news.answers
1796 @c Subject: Unix - Frequently Asked Questions (2/7) [Frequent posting]
1797 @c Subject: How do I remove a file with funny characters in the filename ?
1798 @c Date: Thu Mar 18 17:16:55 EST 1993
1799 @code{find} can help you remove or rename a file with strange characters
1800 in its name. People are sometimes stymied by files whose names contain
1801 characters such as spaces, tabs, control characters, or characters with
1802 the high bit set. The simplest way to remove such files is:
1805 rm -i @var{some*pattern*that*matches*the*problem*file}
1808 @code{rm} asks you whether to remove each file matching the given
1809 pattern. If you are using an old shell, this approach might not work if
1810 the file name contains a character with the high bit set; the shell may
1811 strip it off. A more reliable way is:
1814 find . -maxdepth 1 @var{tests} -ok rm '@{@}' \;
1818 where @var{tests} uniquely identify the file. The @samp{-maxdepth 1}
1819 option prevents @code{find} from wasting time searching for the file in
1820 any subdirectories; if there are no subdirectories, you may omit it. A
1821 good way to uniquely identify the problem file is to figure out its
1828 Suppose you have a file whose name contains control characters, and you
1829 have found that its inode number is 12345. This command prompts you for
1830 whether to remove it:
1833 find . -maxdepth 1 -inum 12345 -ok rm -f '@{@}' \;
1836 If you don't want to be asked, perhaps because the file name may contain
1837 a strange character sequence that will mess up your screen when printed,
1838 then use @samp{-exec} instead of @samp{-ok}.
1840 If you want to rename the file instead, you can use @code{mv} instead of
1844 find . -maxdepth 1 -inum 12345 -ok mv '@{@}' @var{new-file-name} \;
1847 @node Fixing Permissions
1848 @section Fixing Permissions
1850 Suppose you want to make sure that everyone can write to the directories in a
1851 certain directory tree. Here is a way to find directories lacking either
1852 user or group write permission (or both), and fix their permissions:
1855 find . -type d -not -perm -ug=w | xargs chmod ug+w
1859 You could also reverse the operations, if you want to make sure that
1860 directories do @emph{not} have world write permission.
1862 @node Classifying Files
1863 @section Classifying Files
1866 @c From: martin@mwtech.UUCP (Martin Weitzel)
1867 @c Newsgroups: comp.unix.wizards,comp.unix.questions
1868 @c Subject: Advanced usage of 'find' (Re: Unix security automating script)
1869 @c Date: 22 Mar 90 15:05:19 GMT
1870 If you want to classify a set of files into several groups based on
1871 different criteria, you can use the comma operator to perform multiple
1872 independent tests on the files. Here is an example:
1875 find / -type d \( -perm -o=w -fprint allwrite , \
1876 -perm -o=x -fprint allexec \)
1878 echo "Directories that can be written to by everyone:"
1881 echo "Directories with search permissions for everyone:"
1885 @code{find} has only to make one scan through the directory tree (which
1886 is one of the most time consuming parts of its work).
1888 @node Databases, File Permissions, Common Tasks, Top
1889 @chapter File Name Databases
1891 The file name databases used by @code{locate} contain lists of files
1892 that were in particular directory trees when the databases were last
1893 updated. The file name of the default database is determined when
1894 @code{locate} and @code{updatedb} are configured and installed. The
1895 frequency with which the databases are updated and the directories for
1896 which they contain entries depend on how often @code{updatedb} is run,
1897 and with which arguments.
1900 * Database Locations::
1901 * Database Formats::
1904 @node Database Locations
1905 @section Database Locations
1907 There can be multiple file name databases. Users can select which
1908 databases @code{locate} searches using an environment variable or a
1909 command line option. The system administrator can choose the file name
1910 of the default database, the frequency with which the databases are
1911 updated, and the directories for which they contain entries. File name
1912 databases are updated by running the @code{updatedb} program, typically
1915 In networked environments, it often makes sense to build a database at
1916 the root of each filesystem, containing the entries for that filesystem.
1917 @code{updatedb} is then run for each filesystem on the fileserver where
1918 that filesystem is on a local disk, to prevent thrashing the network.
1919 Here are the options to @code{updatedb} to select which directories each
1920 database contains entries for:
1923 @item --localpaths='@var{path}@dots{}'
1924 Non-network directories to put in the database.
1925 Default is @file{/}.
1927 @item --netpaths='@var{path}@dots{}'
1928 Network (NFS, AFS, RFS, etc.) directories to put in the database.
1929 The environment variable @code{NETPATHS} also sets this value.
1933 @item --prunepaths='@var{path}@dots{}'
1934 Directories to not put in the database, which would otherwise be.
1935 The environment variable @code{PRUNEPATHS} also sets this value.
1936 Default is @file{/tmp /usr/tmp /var/tmp /afs}.
1938 @item --prunefs='@var{path}@dots{}'
1939 File systems to not put in the database, which would otherwise be.
1940 Note that files are pruned when a file system is reached;
1941 Any file system mounted under an undesired file system will be
1943 The environment variable @code{PRUNEFS} also sets this value.
1944 Default is @file{nfs NFS proc}.
1946 @item --output=@var{dbfile}
1947 The database file to build.
1948 Default is system-dependent, but typically @file{/usr/local/var/locatedb}.
1950 @item --localuser=@var{user}
1951 The user to search the non-network directories as, using @code{su}.
1952 Default is to search the non-network directories as the current user.
1953 You can also use the environment variable @code{LOCALUSER} to set this user.
1955 @item --netuser=@var{user}
1956 The user to search network directories as, using @code{su}.
1957 Default is @code{daemon}.
1958 You can also use the environment variable @code{NETUSER} to set this user.
1961 @node Database Formats
1962 @section Database Formats
1964 The file name databases contain lists of files that were in particular
1965 directory trees when the databases were last updated. The file name
1966 database format changed starting with GNU @code{locate} version 4.0 to
1967 allow machines with different byte orderings to share the databases. The
1968 new GNU @code{locate} can read both the old and new database formats.
1969 However, old versions of @code{locate} and @code{find} produce incorrect
1970 results if given a new-format database.
1973 * New Database Format::
1975 * Old Database Format::
1978 @node New Database Format
1979 @subsection New Database Format
1981 @code{updatedb} runs a program called @code{frcode} to
1982 @dfn{front-compress} the list of file names, which reduces the database
1983 size by a factor of 4 to 5. Front-compression (also known as
1984 incremental encoding) works as follows.
1986 The database entries are a sorted list (case-insensitively, for users'
1987 convenience). Since the list is sorted, each entry is likely to share a
1988 prefix (initial string) with the previous entry. Each database entry
1989 begins with an offset-differential count byte, which is the additional
1990 number of characters of prefix of the preceding entry to use beyond the
1991 number that the preceding entry is using of its predecessor. (The
1992 counts can be negative.) Following the count is a null-terminated ASCII
1993 remainder---the part of the name that follows the shared prefix.
1995 If the offset-differential count is larger than can be stored in a byte
1996 (+/-127), the byte has the value 0x80 and the count follows in a 2-byte
1997 word, with the high byte first (network byte order).
1999 Every database begins with a dummy entry for a file called
2000 @file{LOCATE02}, which @code{locate} checks for to ensure that the
2001 database file has the correct format; it ignores the entry in doing the
2004 Databases can not be concatenated together, even if the first (dummy)
2005 entry is trimmed from all but the first database. This is because the
2006 offset-differential count in the first entry of the second and following
2007 databases will be wrong.
2009 @node Sample Database
2010 @subsection Sample Database
2012 Sample input to @code{frcode}:
2013 @c with nulls changed to newlines:
2017 /usr/src/cmd/aardvark.c
2018 /usr/src/cmd/armadillo.c
2022 Length of the longest prefix of the preceding entry to share:
2031 Output from @code{frcode}, with trailing nulls changed to newlines
2032 and count bytes made printable:
2042 (6 = 14 - 8, and -9 = 5 - 14)
2044 @node Old Database Format
2045 @subsection Old Database Format
2047 The old database format is used by Unix @code{locate} and @code{find}
2048 programs and earlier releases of the GNU ones. @code{updatedb} produces
2049 this format if given the @samp{--old-format} option.
2051 @code{updatedb} runs programs called @code{bigram} and @code{code} to
2052 produce old-format databases. The old format differs from the new one
2053 in the following ways. Instead of each entry starting with an
2054 offset-differential count byte and ending with a null, byte values from
2055 0 through 28 indicate offset-differential counts from -14 through 14.
2056 The byte value indicating that a long offset-differential count follows
2057 is 0x1e (30), not 0x80. The long counts are stored in host byte order,
2058 which is not necessarily network byte order, and host integer word size,
2059 which is usually 4 bytes. They also represent a count 14 less than
2060 their value. The database lines have no termination byte; the start of
2061 the next line is indicated by its first byte having a value <= 30.
2063 In addition, instead of starting with a dummy entry, the old database
2064 format starts with a 256 byte table containing the 128 most common
2065 bigrams in the file list. A bigram is a pair of adjacent bytes. Bytes
2066 in the database that have the high bit set are indexes (with the high
2067 bit cleared) into the bigram table. The bigram and offset-differential
2068 count coding makes these databases 20-25% smaller than the new format,
2069 but makes them not 8-bit clean. Any byte in a file name that is in the
2070 ranges used for the special codes is replaced in the database by a
2071 question mark, which not coincidentally is the shell wildcard to match a
2074 The old format therefore can not faithfully store entries with non-ASCII
2075 characters. It therefore should not be used in internationalized
2078 @node File Permissions, Reference, Databases, Top
2079 @chapter File Permissions
2083 @node Reference, Primary Index, File Permissions, Top
2086 Below are summaries of the command line syntax for the programs
2087 discussed in this manual.
2092 * Invoking updatedb::
2096 @node Invoking find, Invoking locate, , Reference
2097 @section Invoking @code{find}
2100 find @r{[}@var{file}@dots{}@r{]} @r{[}@var{expression}@r{]}
2103 @code{find} searches the directory tree rooted at each file name
2104 @var{file} by evaluating the @var{expression} on each file it finds in
2107 @code{find} considers the first argument that begins with @samp{-},
2108 @samp{(}, @samp{)}, @samp{,}, or @samp{!} to be the beginning of the
2109 expression; any arguments before it are paths to search, and any
2110 arguments after it are the rest of the expression. If no paths are
2111 given, the current directory is used. If no expression is given, the
2112 expression @samp{-print} is used.
2114 @code{find} exits with status 0 if all files are processed successfully,
2115 greater than 0 if errors occur.
2117 @xref{Primary Index}, for a summary of all of the tests, actions, and
2118 options that the expression can contain.
2120 @code{find} also recognizes two options for administrative use:
2124 Print a summary of the command-line argument format and exit.
2126 Print the version number of @code{find} and exit.
2129 @node Invoking locate, Invoking updatedb, Invoking find, Reference
2130 @section Invoking @code{locate}
2133 locate @r{[}@var{option}@dots{}@r{]} @var{pattern}@dots{}
2137 @item --database=@var{path}
2138 @itemx -d @var{path}
2139 Instead of searching the default file name database, search the file
2140 name databases in @var{path}, which is a colon-separated list of
2141 database file names. You can also use the environment variable
2142 @code{LOCATE_PATH} to set the list of database files to search. The
2143 option overrides the environment variable if both are used.
2147 Only print out such names which currently exist (instead of such names
2148 which existed when the database was created).
2149 Note that this may slow down the program a lot, if there are many matches
2154 Ignore case distinctions in both the pattern and the file names.
2157 Print a summary of the options to @code{locate} and exit.
2160 Print the version number of @code{locate} and exit.
2163 @node Invoking updatedb, Invoking xargs, Invoking locate, Reference
2164 @section Invoking @code{updatedb}
2167 updatedb @r{[}@var{option}@dots{}@r{]}
2171 @item --localpaths='@var{path}@dots{}'
2172 Non-network directories to put in the database.
2173 Default is @file{/}.
2175 @item --netpaths='@var{path}@dots{}'
2176 Network (NFS, AFS, RFS, etc.) directories to put in the database.
2177 The environment variable @code{NETPATHS} also sets this value.
2180 @item --prunepaths='@var{path}@dots{}'
2181 Directories to not put in the database, which would otherwise be.
2182 The environment variable @code{PRUNEPATHS} also sets this value.
2183 Default is @file{/tmp /usr/tmp /var/tmp /afs}.
2185 @item --prunefs='@var{path}@dots{}'
2186 File systems to not put in the database, which would otherwise be.
2187 Note that files are pruned when a file system is reached;
2188 Any file system mounted under an undesired file system will be
2190 The environment variable @code{PRUNEFS} also sets this value.
2191 Default is @file{nfs NFS proc}.
2193 @item --output=@var{dbfile}
2194 The database file to build.
2195 Default is system-dependent, but typically @file{/usr/local/var/locatedb}.
2197 @item --localuser=@var{user}
2198 The user to search the non-network directories as, using @code{su}.
2199 Default is to search the non-network directories as the current user.
2200 You can also use the environment variable @code{LOCALUSER} to set this user.
2202 @item --netuser=@var{user}
2203 The user to search network directories as, using @code{su}(1).
2204 Default is @code{daemon}.
2205 You can also use the environment variable @code{NETUSER} to set this user.
2208 @node Invoking xargs, , Invoking updatedb, Reference
2209 @section Invoking @code{xargs}
2212 xargs @r{[}@var{option}@dots{}@r{]} @r{[}@var{command} @r{[}@var{initial-arguments}@r{]}@r{]}
2215 @code{xargs} exits with the following status:
2221 if any invocation of the command exited with status 1-125
2223 if the command exited with status 255
2225 if the command is killed by a signal
2227 if the command cannot be run
2229 if the command is not found
2231 if some other error occurred.
2237 Input filenames are terminated by a null character instead of by
2238 whitespace, and the quotes and backslash are not special (every
2239 character is taken literally). Disables the end of file string, which
2240 is treated like any other argument.
2242 @item --eof@r{[}=@var{eof-str}@r{]}
2243 @itemx -e@r{[}@var{eof-str}@r{]}
2244 Set the end of file string to @var{eof-str}. If the end of file string
2245 occurs as a line of input, the rest of the input is ignored. If
2246 @var{eof-str} is omitted, there is no end of file string. If this
2247 option is not given, the end of file string defaults to @samp{_}.
2250 Print a summary of the options to @code{xargs} and exit.
2252 @item --replace@r{[}=@var{replace-str}@r{]}
2253 @itemx -i@r{[}@var{replace-str}@r{]}
2254 Replace occurrences of @var{replace-str} in the initial arguments with
2255 names read from standard input. Also, unquoted blanks do not terminate
2256 arguments. If @var{replace-str} is omitted, it defaults to @samp{@{@}}
2257 (like for @samp{find -exec}). Implies @samp{-x} and @samp{-l 1}.
2259 @item --max-lines@r{[}=@var{max-lines}@r{]}
2260 @itemx -l@r{[}@var{max-lines}@r{]}
2261 Use at most @var{max-lines} nonblank input lines per command line;
2262 @var{max-lines} defaults to 1 if omitted. Trailing blanks cause an
2263 input line to be logically continued on the next input line, for the
2264 purpose of counting the lines. Implies @samp{-x}.
2266 @item --max-args=@var{max-args}
2267 @itemx -n @var{max-args}
2268 Use at most @var{max-args} arguments per command line. Fewer than
2269 @var{max-args} arguments will be used if the size (see the @samp{-s}
2270 option) is exceeded, unless the @samp{-x} option is given, in which case
2271 @code{xargs} will exit.
2275 Prompt the user about whether to run each command line and read a line
2276 from the terminal. Only run the command line if the response starts
2277 with @samp{y} or @samp{Y}. Implies @samp{-t}.
2279 @item --no-run-if-empty
2281 If the standard input does not contain any nonblanks, do not run the
2282 command. By default, the command is run once even if there is no input.
2284 @item --max-chars=@var{max-chars}
2285 @itemx -s @var{max-chars}
2286 Use at most @var{max-chars} characters per command line, including the
2287 command and initial arguments and the terminating nulls at the ends of
2288 the argument strings.
2292 Print the command line on the standard error output before executing
2296 Print the version number of @code{xargs} and exit.
2300 Exit if the size (see the @samp{-s} option) is exceeded.
2303 @item --max-procs=@var{max-procs}
2304 @itemx -P @var{max-procs}
2305 Run up to @var{max-procs} processes at a time; the default is 1. If
2306 @var{max-procs} is 0, @code{xargs} will run as many processes as
2310 @node Primary Index, , Reference, Top
2311 @unnumbered @code{find} Primary Index
2313 This is a list of all of the primaries (tests, actions, and options)
2314 that make up @code{find} expressions for selecting files. @xref{find
2315 Expressions}, for more information on expressions.
2322 @comment texi related words used by Emacs' spell checker ispell.el
2324 @comment LocalWords: texinfo setfilename settitle setchapternewpage
2325 @comment LocalWords: iftex finalout ifinfo DIR titlepage vskip pt
2326 @comment LocalWords: filll dir samp dfn noindent xref pxref
2327 @comment LocalWords: var deffn texi deffnx itemx emph asis
2328 @comment LocalWords: findex smallexample subsubsection cindex
2330 @comment other words used by Emacs' spell checker ispell.el
2331 @comment LocalWords: README fred updatedb xargs Plett Rendell akefile
2332 @comment LocalWords: args grep Filesystems fo foo fOo wildcards iname
2333 @comment LocalWords: ipath regex iregex expr fubar regexps
2334 @comment LocalWords: metacharacters macs sr sc inode lname ilname
2335 @comment LocalWords: sysdep noleaf ls inum xdev filesystems usr atime
2336 @comment LocalWords: ctime mtime amin cmin mmin al daystart Sladkey rm
2337 @comment LocalWords: anewer cnewer bckw rf xtype uname gname uid gid
2338 @comment LocalWords: nouser nogroup chown chgrp perm ch maxdepth
2339 @comment LocalWords: mindepth cpio src CD AFS statted stat fstype ufs
2340 @comment LocalWords: nfs tmp mfs printf fprint dils rw djm Nov lwall
2341 @comment LocalWords: POSIXLY fls fprintf strftime locale's EDT GMT AP
2342 @comment LocalWords: EST diff perl backquotes sprintf Falstad Oct cron
2343 @comment LocalWords: eg vmunix mkdir afs allexec allwrite ARG bigram
2344 @comment LocalWords: bigrams cd chmod comp crc CVS dbfile dum eof
2345 @comment LocalWords: fileserver filesystem fn frcode Ghazi Hnewc iXX
2346 @comment LocalWords: joeuser Kaveh localpaths localuser LOGNAME
2347 @comment LocalWords: Meyering mv netpaths netuser nonblank nonblanks
2348 @comment LocalWords: ois ok Pinard printindex proc procs prunefs
2349 @comment LocalWords: prunepaths pwd RFS rmadillo rmdir rsh sbins str
2350 @comment LocalWords: su Timar ubins ug unstripped vf VM Weitzel
2351 @comment LocalWords: wildcard zlogout