1 This is find.info, produced by makeinfo version 4.0 from find.texi.
4 * Finding Files: (find). Listing and operating on files
5 that match certain criteria.
8 This file documents the GNU utilities for finding files that match
9 certain criteria and performing various operations on them.
11 Copyright (C) 1994 Free Software Foundation, Inc.
13 Permission is granted to make and distribute verbatim copies of this
14 manual provided the copyright notice and this permission notice are
15 preserved on all copies.
17 Permission is granted to copy and distribute modified versions of
18 this manual under the conditions for verbatim copying, provided that
19 the entire resulting derived work is distributed under the terms of a
20 permission notice identical to this one.
22 Permission is granted to copy and distribute translations of this
23 manual into another language, under the above conditions for modified
24 versions, except that this permission notice may be stated in a
25 translation approved by the Foundation.
28 File: find.info, Node: Top, Next: Introduction, Up: (dir)
30 This file documents the GNU utilities for finding files that match
31 certain criteria and performing various actions on them. This is
32 edition 4.1.5, for `find' version 4.1.5.
36 * Introduction:: Summary of the tasks this manual describes.
37 * Finding Files:: Finding files that match certain criteria.
38 * Actions:: Doing things to files you have found.
39 * Common Tasks:: Solutions to common real-world problems.
40 * Databases:: Maintaining file name databases.
41 * File Permissions:: How to control access to files.
42 * Reference:: Summary of how to invoke the programs.
43 * Primary Index:: The components of `find' expressions.
46 File: find.info, Node: Introduction, Next: Finding Files, Prev: Top, Up: Top
51 This manual shows how to find files that meet criteria you specify,
52 and how to perform various actions on the files that you find. The
53 principal programs that you use to perform these tasks are `find',
54 `locate', and `xargs'. Some of the examples in this manual use
55 capabilities specific to the GNU versions of those programs.
57 GNU `find' was originally written by Eric Decker, with enhancements
58 by David MacKenzie, Jay Plett, and Tim Wood. GNU `xargs' was
59 originally written by Mike Rendell, with enhancements by David
60 MacKenzie. GNU `locate' and its associated utilities were originally
61 written by James Woods, with enhancements by David MacKenzie. The idea
62 for `find -print0' and `xargs -0' came from Dan Bernstein. Many other
63 people have contributed bug fixes, small improvements, and helpful
66 Mail suggestions and bug reports for these programs to
67 `bug-findutils@gnu.org'. Please include the version number, which you
68 can get by running `find --version'.
77 File: find.info, Node: Scope, Next: Overview, Up: Introduction
82 For brevity, the word "file" in this manual means a regular file, a
83 directory, a symbolic link, or any other kind of node that has a
84 directory entry. A directory entry is also called a "file name". A
85 file name may contain some, all, or none of the directories in a path
86 that leads to the file. These are all examples of what this manual
93 /usr/local/include/termcap.h
95 A "directory tree" is a directory and the files it contains, all of
96 its subdirectories and the files they contain, etc. It can also be a
97 single non-directory file.
99 These programs enable you to find the files in one or more directory
102 * have names that contain certain text or match a certain pattern;
104 * are links to certain files;
106 * were last used during a certain period of time;
108 * are within a certain size range;
110 * are of a certain type (regular file, directory, symbolic link,
113 * are owned by a certain user or group;
115 * have certain access permissions;
117 * contain text that matches a certain pattern;
119 * are within a certain depth in the directory tree;
121 * or some combination of the above.
123 Once you have found the files you're looking for (or files that are
124 potentially the ones you're looking for), you can do more to them than
125 simply list their names. You can get any combination of the files'
126 attributes, or process the files in many ways, either individually or in
127 groups of various sizes. Actions that you might want to perform on the
128 files you have found include, but are not limited to:
132 * store in an archive
136 * change access permissions
138 * classify into groups
140 This manual describes how to perform each of those tasks, and more.
143 File: find.info, Node: Overview, Next: find Expressions, Prev: Scope, Up: Introduction
148 The principal programs used for making lists of files that match
149 given criteria and running commands on them are `find', `locate', and
150 `xargs'. An additional command, `updatedb', is used by system
151 administrators to create databases for `locate' to use.
153 `find' searches for files in a directory hierarchy and prints
154 information about the files it found. It is run like this:
156 find [FILE...] [EXPRESSION]
158 Here is a typical use of `find'. This example prints the names of all
159 files in the directory tree rooted in `/usr/src' whose name ends with
160 `.c' and that are larger than 100 Kilobytes.
161 find /usr/src -name '*.c' -size +100k -print
163 `locate' searches special file name databases for file names that
164 match patterns. The system administrator runs the `updatedb' program
165 to create the databases. `locate' is run like this:
167 locate [OPTION...] PATTERN...
169 This example prints the names of all files in the default file name
170 database whose name ends with `Makefile' or `makefile'. Which file
171 names are stored in the database depends on how the system
172 administrator ran `updatedb'.
173 locate '*[Mm]akefile'
175 The name `xargs', pronounced EX-args, means "combine arguments."
176 `xargs' builds and executes command lines by gathering together
177 arguments it reads on the standard input. Most often, these arguments
178 are lists of file names generated by `find'. `xargs' is run like this:
180 xargs [OPTION...] [COMMAND [INITIAL-ARGUMENTS]]
182 The following command searches the files listed in the file `file-list'
183 and prints all of the lines in them that contain the word `typedef'.
184 xargs grep typedef < file-list
187 File: find.info, Node: find Expressions, Prev: Overview, Up: Introduction
192 The expression that `find' uses to select files consists of one or
193 more "primaries", each of which is a separate command line argument to
194 `find'. `find' evaluates the expression each time it processes a file.
195 An expression can contain any of the following types of primaries:
198 affect overall operation rather than the processing of a specific
202 return a true or false value, depending on the file's attributes;
205 have side effects and return a true or false value; and
208 connect the other arguments and affect when and whether they are
211 You can omit the operator between two primaries; it defaults to
212 `-and'. *Note Combining Primaries With Operators::, for ways to
213 connect primaries into more complex expressions. If the expression
214 contains no actions other than `-prune', `-print' is performed on all
215 files for which the entire expression is true (*note Print File Name::).
217 Options take effect immediately, rather than being evaluated for each
218 file when their place in the expression is reached. Therefore, for
219 clarity, it is best to place them at the beginning of the expression.
221 Many of the primaries take arguments, which immediately follow them
222 in the next command line argument to `find'. Some arguments are file
223 names, patterns, or other strings; others are numbers. Numeric
224 arguments can be specified as
236 File: find.info, Node: Finding Files, Next: Actions, Prev: Introduction, Up: Top
241 By default, `find' prints to the standard output the names of the
242 files that match the given criteria. *Note Actions::, for how to get
243 more information about the matching files.
257 * Combining Primaries With Operators::
260 File: find.info, Node: Name, Next: Links, Up: Finding Files
265 Here are ways to search for files whose name matches a certain
266 pattern. *Note Shell Pattern Matching::, for a description of the
267 PATTERN arguments to these tests.
269 Each of these tests has a case-sensitive version and a
270 case-insensitive version, whose name begins with `i'. In a
271 case-insensitive comparison, the patterns `fo*' and `F??' match the
272 file names `Foo', `FOO', `foo', `fOo', etc.
276 * Base Name Patterns::
277 * Full Name Patterns::
278 * Fast Full Name Search::
279 * Shell Pattern Matching:: Wildcards used by these programs.
282 File: find.info, Node: Base Name Patterns, Next: Full Name Patterns, Up: Name
287 - Test: -name pattern
288 - Test: -iname pattern
289 True if the base of the file name (the path with the leading
290 directories removed) matches shell pattern PATTERN. For `-iname',
291 the match is case-insensitive. To ignore a whole directory tree,
292 use `-prune' (*note Directories::). As an example, to find Texinfo
293 source files in `/usr/local/doc':
295 find /usr/local/doc -name '*.texi'
298 File: find.info, Node: Full Name Patterns, Next: Fast Full Name Search, Prev: Base Name Patterns, Up: Name
303 - Test: -path pattern
304 - Test: -ipath pattern
305 True if the entire file name, starting with the command line
306 argument under which the file was found, matches shell pattern
307 PATTERN. For `-ipath', the match is case-insensitive. To ignore
308 a whole directory tree, use `-prune' rather than checking every
309 file in the tree (*note Directories::).
313 True if the entire file name matches regular expression EXPR.
314 This is a match on the whole path, not a search. For example, to
315 match a file named `./fubar3', you can use the regular expression
316 `.*bar.' or `.*b.*3', but not `b.*r3'. *Note Syntax of Regular
317 Expressions: (emacs)Regexps, for a description of the syntax of
318 regular expressions. For `-iregex', the match is case-insensitive.
321 File: find.info, Node: Fast Full Name Search, Next: Shell Pattern Matching, Prev: Full Name Patterns, Up: Name
323 Fast Full Name Search
324 ---------------------
326 To search for files by name without having to actually scan the
327 directories on the disk (which can be slow), you can use the `locate'
328 program. For each shell pattern you give it, `locate' searches one or
329 more databases of file names and displays the file names that contain
330 the pattern. *Note Shell Pattern Matching::, for details about shell
333 If a pattern is a plain string--it contains no
334 metacharacters--`locate' displays all file names in the database that
335 contain that string. If a pattern contains metacharacters, `locate'
336 only displays file names that match the pattern exactly. As a result,
337 patterns that contain metacharacters should usually begin with a `*',
338 and will most often end with one as well. The exceptions are patterns
339 that are intended to explicitly match the beginning or end of a file
345 is almost equivalent to
346 find DIRECTORIES -name PATTERN
348 where DIRECTORIES are the directories for which the file name
349 databases contain information. The differences are that the `locate'
350 information might be out of date, and that `locate' handles wildcards
351 in the pattern slightly differently than `find' (*note Shell Pattern
354 The file name databases contain lists of files that were on the
355 system when the databases were last updated. The system administrator
356 can choose the file name of the default database, the frequency with
357 which the databases are updated, and the directories for which they
360 Here is how to select which file name databases `locate' searches.
361 The default is system-dependent.
365 Instead of searching the default file name database, search the
366 file name databases in PATH, which is a colon-separated list of
367 database file names. You can also use the environment variable
368 `LOCATE_PATH' to set the list of database files to search. The
369 option overrides the environment variable if both are used.
372 File: find.info, Node: Shell Pattern Matching, Prev: Fast Full Name Search, Up: Name
374 Shell Pattern Matching
375 ----------------------
377 `find' and `locate' can compare file names, or parts of file names,
378 to shell patterns. A "shell pattern" is a string that may contain the
379 following special characters, which are known as "wildcards" or
382 You must quote patterns that contain metacharacters to prevent the
383 shell from expanding them itself. Double and single quotes both work;
384 so does escaping with a backslash.
387 Matches any zero or more characters.
390 Matches any one character.
393 Matches exactly one character that is a member of the string
394 STRING. This is called a "character class". As a shorthand,
395 STRING may contain ranges, which consist of two characters with a
396 dash between them. For example, the class `[a-z0-9_]' matches a
397 lowercase letter, a number, or an underscore. You can negate a
398 class by placing a `!' or `^' immediately after the opening
399 bracket. Thus, `[^A-Z@]' matches any character except an
400 uppercase letter or an at sign.
403 Removes the special meaning of the character that follows it. This
404 works even in character classes.
406 In the `find' tests that do shell pattern matching (`-name',
407 `-path', etc.), wildcards in the pattern do not match a `.' at the
408 beginning of a file name. This is not the case for `locate'. Thus,
409 `find -name '*macs'' does not match a file named `.emacs', but `locate
412 Slash characters have no special significance in the shell pattern
413 matching that `find' and `locate' do, unlike in the shell, in which
414 wildcards do not match them. Therefore, a pattern `foo*bar' can match
415 a file name `foo3/bar', and a pattern `./sr*sc' can match a file name
419 File: find.info, Node: Links, Next: Time, Prev: Name, Up: Finding Files
424 There are two ways that files can be linked together. "Symbolic
425 links" are a special type of file whose contents are a portion of the
426 name of another file. "Hard links" are multiple directory entries for
427 one file; the file names all have the same index node ("inode") number
436 File: find.info, Node: Symbolic Links, Next: Hard Links, Up: Links
441 - Test: -lname pattern
442 - Test: -ilname pattern
443 True if the file is a symbolic link whose contents match shell
444 pattern PATTERN. For `-ilname', the match is case-insensitive.
445 *Note Shell Pattern Matching::, for details about the PATTERN
446 argument. So, to list any symbolic links to `sysdep.c' in the
447 current directory and its subdirectories, you can do:
449 find . -lname '*sysdep.c'
452 Dereference symbolic links. The following differences in behavior
453 occur when this option is given:
455 * `find' follows symbolic links to directories when searching
458 * `-lname' and `-ilname' always return false.
460 * `-type' reports the types of the files that symbolic links
463 * Implies `-noleaf' (*note Directories::).
466 File: find.info, Node: Hard Links, Prev: Symbolic Links, Up: Links
471 To find hard links, first get the inode number of the file whose
472 links you want to find. You can learn a file's inode number and the
473 number of links to it by running `ls -i' or `find -ls'. If the file has
474 more than one link, you can search for the other links by passing that
475 inode number to `-inum'. Add the `-xdev' option if you are starting
476 the search at a directory that has other filesystems mounted on it,
477 such as `/usr' on many systems. Doing this saves needless searching,
478 since hard links to a file must be on the same filesystem. *Note
482 File has inode number N.
484 You can also search for files that have a certain number of links,
485 with `-links'. Directories normally have at least two hard links; their
486 `.' entry is the second one. If they have subdirectories, each of
487 those also has a hard link called `..' to its parent directory.
490 File has N hard links.
493 File: find.info, Node: Time, Next: Size, Prev: Links, Up: Finding Files
498 Each file has three time stamps, which record the last time that
499 certain operations were performed on the file:
501 1. access (read the file's contents)
503 2. change the status (modify the file or its attributes)
505 3. modify (change the file's contents)
507 You can search for files whose time stamps are within a certain age
508 range, or compare them to other time stamps.
513 * Comparing Timestamps::
516 File: find.info, Node: Age Ranges, Next: Comparing Timestamps, Up: Time
521 These tests are mainly useful with ranges (`+N' and `-N').
526 True if the file was last accessed (or its status changed, or it
527 was modified) N*24 hours ago.
532 True if the file was last accessed (or its status changed, or it
533 was modified) N minutes ago. These tests provide finer
534 granularity of measurement than `-atime' et al. For example, to
535 list files in `/u/bill' that were last read from 2 to 6 minutes
538 find /u/bill -amin +2 -amin -6
541 Measure times from the beginning of today rather than from 24
542 hours ago. So, to list the regular files in your home directory
543 that were modified yesterday, do
545 find ~ -daystart -type f -mtime 1
548 File: find.info, Node: Comparing Timestamps, Prev: Age Ranges, Up: Time
553 As an alternative to comparing timestamps to the current time, you
554 can compare them to another file's timestamp. That file's timestamp
555 could be updated by another program when some event occurs. Or you
556 could set it to a particular fixed date using the `touch' command. For
557 example, to list files in `/usr' modified after February 1 of the
560 touch -t 02010000 /tmp/stamp$$
561 find /usr -newer /tmp/stamp$$
567 True if the file was last accessed (or its status changed, or it
568 was modified) more recently than FILE was modified. These tests
569 are affected by `-follow' only if `-follow' comes before them on
570 the command line. *Note Symbolic Links::, for more information on
571 `-follow'. As an example, to list any files modified since
572 `/bin/sh' was last modified:
574 find . -newer /bin/sh
577 True if the file was last accessed N days after its status was
578 last changed. Useful for finding files that are not being used,
579 and could perhaps be archived or removed to save disk space.
582 File: find.info, Node: Size, Next: Type, Prev: Time, Up: Finding Files
587 - Test: -size n[bckw]
588 True if the file uses N units of space, rounding up. The units
589 are 512-byte blocks by default, but they can be changed by adding a
590 one-character suffix to N:
599 kilobytes (1024 bytes)
604 The size does not count indirect blocks, but it does count blocks
605 in sparse files that are not actually allocated.
608 True if the file is empty and is either a regular file or a
609 directory. This might make it a good candidate for deletion.
610 This test is useful with `-depth' (*note Directories::) and `-exec
611 rm -rf '{}' ';'' (*note Single File::).
614 File: find.info, Node: Type, Next: Owner, Prev: Size, Up: Finding Files
620 True if the file is of type C:
623 block (buffered) special
626 character (unbuffered) special
644 The same as `-type' unless the file is a symbolic link. For
645 symbolic links: if `-follow' has not been given, true if the file
646 is a link to a file of type C; if `-follow' has been given, true
647 if C is `l'. In other words, for symbolic links, `-xtype' checks
648 the type of the file that `-type' does not check. *Note Symbolic
649 Links::, for more information on `-follow'.
652 File: find.info, Node: Owner, Next: Permissions, Prev: Type, Up: Finding Files
659 True if the file is owned by user UNAME (belongs to group GNAME).
660 A numeric ID is allowed.
664 True if the file's numeric user ID (group ID) is N. These tests
665 support ranges (`+N' and `-N'), unlike `-user' and `-group'.
669 True if no user corresponds to the file's numeric user ID (no group
670 corresponds to the numeric group ID). These cases usually mean
671 that the files belonged to users who have since been removed from
672 the system. You probably should change the ownership of such
673 files to an existing user or group, using the `chown' or `chgrp'
677 File: find.info, Node: Permissions, Next: Contents, Prev: Owner, Up: Finding Files
682 *Note File Permissions::, for information on how file permissions are
683 structured and how to specify them.
686 True if the file's permissions are exactly MODE (which can be
687 numeric or symbolic). Symbolic modes use mode 0 as a point of
688 departure. If MODE starts with `-', true if _all_ of the
689 permissions set in MODE are set for the file; permissions not set
690 in MODE are ignored. If MODE starts with `+', true if _any_ of
691 the permissions set in MODE are set for the file; permissions not
692 set in MODE are ignored.
695 File: find.info, Node: Contents, Next: Directories, Prev: Permissions, Up: Finding Files
700 To search for files based on their contents, you can use the `grep'
701 program. For example, to find out which C source files in the current
702 directory contain the string `thing', you can do:
706 If you also want to search for the string in files in subdirectories,
707 you can combine `grep' with `find' and `xargs', like this:
709 find . -name '*.[ch]' | xargs grep -l thing
711 The `-l' option causes `grep' to print only the names of files that
712 contain the string, rather than the lines that contain it. The string
713 argument (`thing') is actually a regular expression, so it can contain
714 metacharacters. This method can be refined a little by using the `-r'
715 option to make `xargs' not run `grep' if `find' produces no output, and
716 using the `find' action `-print0' and the `xargs' option `-0' to avoid
717 misinterpreting files whose names contain spaces:
719 find . -name '*.[ch]' -print0 | xargs -r -0 grep -l thing
721 For a fuller treatment of finding files whose contents match a
722 pattern, see the manual page for `grep'.
725 File: find.info, Node: Directories, Next: Filesystems, Prev: Contents, Up: Finding Files
730 Here is how to control which directories `find' searches, and how it
731 searches them. These two options allow you to process a horizontal
732 slice of a directory tree.
734 - Option: -maxdepth levels
735 Descend at most LEVELS (a non-negative integer) levels of
736 directories below the command line arguments. `-maxdepth 0' means
737 only apply the tests and actions to the command line arguments.
739 - Option: -mindepth levels
740 Do not apply any tests or actions at levels less than LEVELS (a
741 non-negative integer). `-mindepth 1' means process all files
742 except the command line arguments.
745 Process each directory's contents before the directory itself.
746 Doing this is a good idea when producing lists of files to archive
747 with `cpio' or `tar'. If a directory does not have write
748 permission for its owner, its contents can still be restored from
749 the archive since the directory's permissions are restored after
753 If `-depth' is not given, true; do not descend the current
754 directory. If `-depth' is given, false; no effect. `-prune' only
755 affects tests and actions that come after it in the expression, not
756 those that come before.
758 For example, to skip the directory `src/emacs' and all files and
759 directories under it, and print the names of the other files found:
761 find . -path './src/emacs' -prune -o -print
764 Do not optimize by assuming that directories contain 2 fewer
765 subdirectories than their hard link count. This option is needed
766 when searching filesystems that do not follow the Unix
767 directory-link convention, such as CD-ROM or MS-DOS filesystems or
768 AFS volume mount points. Each directory on a normal Unix
769 filesystem has at least 2 hard links: its name and its `.' entry.
770 Additionally, its subdirectories (if any) each have a `..' entry
771 linked to that directory. When `find' is examining a directory,
772 after it has statted 2 fewer subdirectories than the directory's
773 link count, it knows that the rest of the entries in the directory
774 are non-directories ("leaf" files in the directory tree). If only
775 the files' names need to be examined, there is no need to stat
776 them; this gives a significant increase in search speed.
779 File: find.info, Node: Filesystems, Next: Combining Primaries With Operators, Prev: Directories, Up: Finding Files
784 A "filesystem" is a section of a disk, either on the local host or
785 mounted from a remote host over a network. Searching network
786 filesystems can be slow, so it is common to make `find' avoid them.
788 There are two ways to avoid searching certain filesystems. One way
789 is to tell `find' to only search one filesystem:
793 Don't descend directories on other filesystems. These options are
796 The other way is to check the type of filesystem each file is on, and
797 not descend directories that are on undesirable filesystem types:
800 True if the file is on a filesystem of type TYPE. The valid
801 filesystem types vary among different versions of Unix; an
802 incomplete list of filesystem types that are accepted on some
803 version of Unix or another is:
804 ufs 4.2 4.3 nfs tmp mfs S51K S52K
805 You can use `-printf' with the `%F' directive to see the types of
806 your filesystems. *Note Print File Information::. `-fstype' is
807 usually used with `-prune' to avoid searching remote filesystems
808 (*note Directories::).
811 File: find.info, Node: Combining Primaries With Operators, Prev: Filesystems, Up: Finding Files
813 Combining Primaries With Operators
814 ==================================
816 Operators build a complex expression from tests and actions. The
817 operators are, in order of decreasing precedence:
820 Force precedence. True if EXPR is true.
824 True if EXPR is false.
829 And; EXPR2 is not evaluated if EXPR1 is false.
833 Or; EXPR2 is not evaluated if EXPR1 is true.
836 List; both EXPR1 and EXPR2 are always evaluated. True if EXPR2 is
837 true. The value of EXPR1 is discarded. This operator lets you do
838 multiple independent operations on one traversal, without
839 depending on whether other operations succeeded.
841 `find' searches the directory tree rooted at each file name by
842 evaluating the expression from left to right, according to the rules of
843 precedence, until the outcome is known (the left hand side is false for
844 `-and', true for `-or'), at which point `find' moves on to the next
847 There are two other tests that can be useful in complex expressions:
856 File: find.info, Node: Actions, Next: Common Tasks, Prev: Finding Files, Up: Top
861 There are several ways you can print information about the files that
862 match the criteria you gave in the `find' expression. You can print
863 the information either to the standard output or to a file that you
864 name. You can also execute commands that have the file names as
865 arguments. You can use those commands as further filters to select
871 * Print File Information::
876 File: find.info, Node: Print File Name, Next: Print File Information, Up: Actions
882 True; print the full file name on the standard output, followed by
885 - Action: -fprint file
886 True; print the full file name into file FILE, followed by a
887 newline. If FILE does not exist when `find' is run, it is
888 created; if it does exist, it is truncated to 0 bytes. The file
889 names `/dev/stdout' and `/dev/stderr' are handled specially; they
890 refer to the standard output and standard error output,
894 File: find.info, Node: Print File Information, Next: Run Commands, Prev: Print File Name, Up: Actions
896 Print File Information
897 ======================
900 True; list the current file in `ls -dils' format on the standard
901 output. The output looks like this:
903 204744 17 -rw-r--r-- 1 djm staff 17337 Nov 2 1992 ./lwall-quotes
907 1. The inode number of the file. *Note Hard Links::, for how to
908 find files based on their inode number.
910 2. the number of blocks in the file. The block counts are of 1K
911 blocks, unless the environment variable `POSIXLY_CORRECT' is
912 set, in which case 512-byte blocks are used. *Note Size::,
913 for how to find files based on their size.
915 3. The file's type and permissions. The type is shown as a dash
916 for a regular file; for other file types, a letter like for
917 `-type' is used (*note Type::). The permissions are read,
918 write, and execute for the file's owner, its group, and other
919 users, respectively; a dash means the permission is not
920 granted. *Note File Permissions::, for more details about
921 file permissions. *Note Permissions::, for how to find files
922 based on their permissions.
924 4. The number of hard links to the file.
926 5. The user who owns the file.
930 7. The file's size in bytes.
932 8. The date the file was last modified.
934 9. The file's name. `-ls' quotes non-printable characters in
935 the file names using C-like backslash escapes.
938 True; like `-ls' but write to FILE like `-fprint' (*note Print
941 - Action: -printf format
942 True; print FORMAT on the standard output, interpreting `\'
943 escapes and `%' directives. Field widths and precisions can be
944 specified as with the `printf' C function. Unlike `-print',
945 `-printf' does not add a newline at the end of the string.
947 - Action: -fprintf file format
948 True; like `-printf' but write to FILE like `-fprint' (*note Print
954 * Format Directives::
958 File: find.info, Node: Escapes, Next: Format Directives, Up: Print File Information
963 The escapes that `-printf' and `-fprintf' recognize are:
972 Stop printing from this format immediately and flush the output.
990 A literal backslash (`\').
992 A `\' character followed by any other character is treated as an
993 ordinary character, so they both are printed, and a warning message is
994 printed to the standard error output (because it was probably a typo).
997 File: find.info, Node: Format Directives, Next: Time Formats, Prev: Escapes, Up: Print File Information
1002 `-printf' and `-fprintf' support the following format directives to
1003 print information about the file being processed. Unlike the C
1004 `printf' function, they do not support field width specifiers.
1006 `%%' is a literal percent sign. A `%' character followed by any
1007 other character is discarded (but the other character is printed), and
1008 a warning message is printed to the standard error output (because it
1009 was probably a typo).
1014 * Ownership Directives::
1016 * Location Directives::
1020 File: find.info, Node: Name Directives, Next: Ownership Directives, Up: Format Directives
1029 File's name with any leading directories removed (only the last
1033 Leading directories of file's name (all but the last element and
1034 the slash before it).
1037 File's name with the name of the command line argument under which
1038 it was found removed from the beginning.
1041 Command line argument under which file was found.
1044 File: find.info, Node: Ownership Directives, Next: Size Directives, Prev: Name Directives, Up: Format Directives
1046 Ownership Directives
1047 ....................
1050 File's group name, or numeric group ID if the group has no name.
1053 File's numeric group ID.
1056 File's user name, or numeric user ID if the user has no name.
1059 File's numeric user ID.
1062 File's permissions (in octal).
1065 File: find.info, Node: Size Directives, Next: Location Directives, Prev: Ownership Directives, Up: Format Directives
1071 File's size in 1K blocks (rounded up).
1074 File's size in 512-byte blocks (rounded up).
1077 File's size in bytes.
1080 File: find.info, Node: Location Directives, Next: Time Directives, Prev: Size Directives, Up: Format Directives
1086 File's depth in the directory tree; files named on the command line
1090 Type of the filesystem the file is on; this value can be used for
1091 `-fstype' (*note Directories::).
1094 Object of symbolic link (empty string if file is not a symbolic
1098 File's inode number (in decimal).
1101 Number of hard links to file.
1104 File: find.info, Node: Time Directives, Prev: Location Directives, Up: Format Directives
1109 Some of these directives use the C `ctime' function. Its output
1110 depends on the current locale, but it typically looks like
1112 Wed Nov 2 00:42:36 1994
1115 File's last access time in the format returned by the C `ctime'
1119 File's last access time in the format specified by K (*note Time
1123 File's last status change time in the format returned by the C
1127 File's last status change time in the format specified by K (*note
1131 File's last modification time in the format returned by the C
1135 File's last modification time in the format specified by K (*note
1139 File: find.info, Node: Time Formats, Prev: Format Directives, Up: Print File Information
1144 Below are the formats for the directives `%A', `%C', and `%T', which
1145 print the file's timestamps. Some of these formats might not be
1146 available on all systems, due to differences in the C `strftime'
1147 function between systems.
1153 * Combined Time Formats::
1156 File: find.info, Node: Time Components, Next: Date Components, Up: Time Formats
1161 The following format directives print single components of the time.
1179 time zone (e.g., EDT), or nothing if no time zone is determinable
1188 seconds since Jan. 1, 1970, 00:00 GMT.
1191 File: find.info, Node: Date Components, Next: Combined Time Formats, Prev: Time Components, Up: Time Formats
1196 The following format directives print single components of the date.
1199 locale's abbreviated weekday name (Sun..Sat)
1202 locale's full weekday name, variable length (Sunday..Saturday)
1206 locale's abbreviated month name (Jan..Dec)
1209 locale's full month name, variable length (January..December)
1215 day of month (01..31)
1221 day of year (001..366)
1224 week number of year with Sunday as first day of week (00..53)
1227 week number of year with Monday as first day of week (00..53)
1233 last two digits of year (00..99)
1236 File: find.info, Node: Combined Time Formats, Prev: Date Components, Up: Time Formats
1238 Combined Time Formats
1239 .....................
1241 The following format directives print combinations of time and date
1245 time, 12-hour (hh:mm:ss [AP]M)
1248 time, 24-hour (hh:mm:ss)
1251 locale's time representation (H:M:S)
1254 locale's date and time (Sat Nov 04 12:02:33 EST 1989)
1260 locale's date representation (mm/dd/yy)
1263 File: find.info, Node: Run Commands, Next: Adding Tests, Prev: Print File Information, Up: Actions
1268 You can use the list of file names created by `find' or `locate' as
1269 arguments to other commands. In this way you can perform arbitrary
1270 actions on the files.
1279 File: find.info, Node: Single File, Next: Multiple Files, Up: Run Commands
1284 Here is how to run a command on one file at a time.
1286 - Action: -exec command ;
1287 Execute COMMAND; true if 0 status is returned. `find' takes all
1288 arguments after `-exec' to be part of the command until an
1289 argument consisting of `;' is reached. It replaces the string
1290 `{}' by the current file name being processed everywhere it occurs
1291 in the command. Both of these constructions need to be escaped
1292 (with a `\') or quoted to protect them from expansion by the shell.
1293 The command is executed in the directory in which `find' was run.
1295 For example, to compare each C header file in the current
1296 directory with the file `/tmp/master':
1298 find . -name '*.h' -exec diff -u '{}' /tmp/master ';'
1301 File: find.info, Node: Multiple Files, Next: Querying, Prev: Single File, Up: Run Commands
1306 Sometimes you need to process files alone. But when you don't, it
1307 is faster to run a command on as many files as possible at a time,
1308 rather than once per file. Doing this saves on the time it takes to
1309 start up the command each time.
1311 To run a command on more than one file at once, use the `xargs'
1312 command, which is invoked like this:
1314 xargs [OPTION...] [COMMAND [INITIAL-ARGUMENTS]]
1316 `xargs' reads arguments from the standard input, delimited by blanks
1317 (which can be protected with double or single quotes or a backslash) or
1318 newlines. It executes the COMMAND (default is `/bin/echo') one or more
1319 times with any INITIAL-ARGUMENTS followed by arguments read from
1320 standard input. Blank lines on the standard input are ignored.
1322 Instead of blank-delimited names, it is safer to use `find -print0'
1323 or `find -fprint0' and process the output by giving the `-0' or
1324 `--null' option to GNU `xargs', GNU `tar', GNU `cpio', or `perl'.
1326 You can use shell command substitution (backquotes) to process a
1327 list of arguments, like this:
1329 grep -l sprintf `find $HOME -name '*.c' -print`
1331 However, that method produces an error if the length of the `.c'
1332 file names exceeds the operating system's command-line length limit.
1333 `xargs' avoids that problem by running the command as many times as
1334 necessary without exceeding the limit:
1336 find $HOME -name '*.c' -print | xargs grep -l sprintf
1338 However, if the command needs to have its standard input be a
1339 terminal (`less', for example), you have to use the shell command
1340 substitution method.
1344 * Unsafe File Name Handling::
1345 * Safe File Name Handling::
1346 * Limiting Command Size::
1347 * Interspersing File Names::
1350 File: find.info, Node: Unsafe File Name Handling, Next: Safe File Name Handling, Up: Multiple Files
1352 Unsafe File Name Handling
1353 .........................
1355 Because file names can contain quotes, backslashes, blank characters,
1356 and even newlines, it is not safe to process them using `xargs' in its
1357 default mode of operation. But since most files' names do not contain
1358 blanks, this problem occurs only infrequently. If you are only
1359 searching through files that you know have safe names, then you need not
1360 be concerned about it.
1362 In many applications, if `xargs' botches processing a file because
1363 its name contains special characters, some data might be lost. The
1364 importance of this problem depends on the importance of the data and
1365 whether anyone notices the loss soon enough to correct it. However,
1366 here is an extreme example of the problems that using blank-delimited
1367 names can cause. If the following command is run daily from `cron',
1368 then any user can remove any file on the system:
1370 find / -name '#*' -atime +7 -print | xargs rm
1372 For example, you could do something like this:
1377 and then `cron' would delete `/vmunix', if it ran `xargs' with `/' as
1378 its current directory.
1380 To delete other files, for example `/u/joeuser/.plan', you could do
1387 eg$ mkdir u u/joeuser u/joeuser/.plan'
1389 eg$ echo > u/joeuser/.plan'
1392 eg$ find . -name '#*' -print | xargs echo
1393 ./# ./# /u/joeuser/.plan /#foo
1396 File: find.info, Node: Safe File Name Handling, Next: Limiting Command Size, Prev: Unsafe File Name Handling, Up: Multiple Files
1398 Safe File Name Handling
1399 .......................
1401 Here is how to make `find' output file names so that they can be
1402 used by other programs without being mangled or misinterpreted. You can
1403 process file names generated this way by giving the `-0' or `--null'
1404 option to GNU `xargs', GNU `tar', GNU `cpio', or `perl'.
1407 True; print the full file name on the standard output, followed by
1410 - Action: -fprint0 file
1411 True; like `-print0' but write to FILE like `-fprint' (*note Print
1415 File: find.info, Node: Limiting Command Size, Next: Interspersing File Names, Prev: Safe File Name Handling, Up: Multiple Files
1417 Limiting Command Size
1418 .....................
1420 `xargs' gives you control over how many arguments it passes to the
1421 command each time it executes it. By default, it uses up to `ARG_MAX'
1422 - 2k, or 20k, whichever is smaller, characters per command. It uses as
1423 many lines and arguments as fit within that limit. The following
1424 options modify those values.
1428 If the standard input does not contain any nonblanks, do not run
1429 the command. By default, the command is run once even if there is
1432 `--max-lines[=MAX-LINES]'
1434 Use at most MAX-LINES nonblank input lines per command line;
1435 MAX-LINES defaults to 1 if omitted. Trailing blanks cause an
1436 input line to be logically continued on the next input line, for
1437 the purpose of counting the lines. Implies `-x'.
1439 `--max-args=MAX-ARGS'
1441 Use at most MAX-ARGS arguments per command line. Fewer than
1442 MAX-ARGS arguments will be used if the size (see the `-s' option)
1443 is exceeded, unless the `-x' option is given, in which case
1446 `--max-chars=MAX-CHARS'
1448 Use at most MAX-CHARS characters per command line, including the
1449 command and initial arguments and the terminating nulls at the
1450 ends of the argument strings.
1452 `--max-procs=MAX-PROCS'
1454 Run up to MAX-PROCS processes at a time; the default is 1. If
1455 MAX-PROCS is 0, `xargs' will run as many processes as possible at
1456 a time. Use the `-n', `-s', or `-l' option with `-P'; otherwise
1457 chances are that the command will be run only once.
1460 File: find.info, Node: Interspersing File Names, Prev: Limiting Command Size, Up: Multiple Files
1462 Interspersing File Names
1463 ........................
1465 `xargs' can insert the name of the file it is processing between
1466 arguments you give for the command. Unless you also give options to
1467 limit the command size (*note Limiting Command Size::), this mode of
1468 operation is equivalent to `find -exec' (*note Single File::).
1470 `--replace[=REPLACE-STR]'
1472 Replace occurrences of REPLACE-STR in the initial arguments with
1473 names read from standard input. Also, unquoted blanks do not
1474 terminate arguments. If REPLACE-STR is omitted, it defaults to
1475 `{}' (like for `find -exec'). Implies `-x' and `-l 1'. As an
1476 example, to sort each file the `bills' directory, leaving the
1477 output in that file name with `.sorted' appended, you could do:
1479 find bills -type f | xargs -iXX sort -o XX.sorted XX
1481 The equivalent command using `find -exec' is:
1483 find bills -type f -exec sort -o '{}.sorted' '{}' ';'
1486 File: find.info, Node: Querying, Prev: Multiple Files, Up: Run Commands
1491 To ask the user whether to execute a command on a single file, you
1492 can use the `find' primary `-ok' instead of `-exec':
1494 - Action: -ok command ;
1495 Like `-exec' (*note Single File::), but ask the user first (on the
1496 standard input); if the response does not start with `y' or `Y',
1497 do not run the command, and return false.
1499 When processing multiple files with a single command, to query the
1500 user you give `xargs' the following option. When using this option, you
1501 might find it useful to control the number of files processed per
1502 invocation of the command (*note Limiting Command Size::).
1506 Prompt the user about whether to run each command line and read a
1507 line from the terminal. Only run the command line if the response
1508 starts with `y' or `Y'. Implies `-t'.
1511 File: find.info, Node: Adding Tests, Prev: Run Commands, Up: Actions
1516 You can test for file attributes that none of the `find' builtin
1517 tests check. To do this, use `xargs' to run a program that filters a
1518 list of files printed by `find'. If possible, use `find' builtin tests
1519 to pare down the list, so the program run by `xargs' has less work to
1520 do. The tests builtin to `find' will likely run faster than tests that
1521 other programs perform.
1523 For example, here is a way to print the names of all of the
1524 unstripped binaries in the `/usr/local' directory tree. Builtin tests
1525 avoid running `file' on files that are not regular files or are not
1528 find /usr/local -type f -perm +a=x | xargs file |
1529 grep 'not stripped' | cut -d: -f1
1531 The `cut' program removes everything after the file name from the
1534 If you want to place a special test somewhere in the middle of a
1535 `find' expression, you can use `-exec' to run a program that performs
1536 the test. Because `-exec' evaluates to the exit status of the executed
1537 program, you can write a program (which can be a shell script) that
1538 tests for a special attribute and make it exit with a true (zero) or
1539 false (non-zero) status. It is a good idea to place such a special
1540 test _after_ the builtin tests, because it starts a new process which
1541 could be avoided if a builtin test evaluates to false. Use this method
1542 only when `xargs' is not flexible enough, because starting one or more
1543 new processes to test each file is slower than using `xargs' to start
1544 one process that tests many files.
1546 Here is a shell script called `unstripped' that checks whether its
1547 argument is an unstripped binary file:
1550 file $1 | grep 'not stripped' > /dev/null
1552 This script relies on the fact that the shell exits with the status
1553 of the last program it executed, in this case `grep'. `grep' exits
1554 with a true status if it found any matches, false if not. Here is an
1555 example of using the script (assuming it is in your search path). It
1556 lists the stripped executables in the file `sbins' and the unstripped
1559 find /usr/local -type f -perm +a=x \
1560 \( -exec unstripped '{}' \; -fprint ubins -o -fprint sbins \)
1563 File: find.info, Node: Common Tasks, Next: Databases, Prev: Actions, Up: Top
1568 The sections that follow contain some extended examples that both
1569 give a good idea of the power of these programs, and show you how to
1570 solve common real-world problems.
1574 * Viewing And Editing::
1577 * Strange File Names::
1578 * Fixing Permissions::
1579 * Classifying Files::