summaryrefslogtreecommitdiff
path: root/doc/find.info-1
diff options
context:
space:
mode:
Diffstat (limited to 'doc/find.info-1')
-rw-r--r--doc/find.info-11581
1 files changed, 1581 insertions, 0 deletions
diff --git a/doc/find.info-1 b/doc/find.info-1
new file mode 100644
index 00000000..dc78df66
--- /dev/null
+++ b/doc/find.info-1
@@ -0,0 +1,1581 @@
+This is Info file find.info, produced by Makeinfo-1.55 from the input
+file find.texi.
+
+START-INFO-DIR-ENTRY
+* Finding Files: (find). Listing and operating on files
+ that match certain criteria.
+END-INFO-DIR-ENTRY
+
+ This file documents the GNU utilities for finding files that match
+certain criteria and performing various operations on them.
+
+ Copyright (C) 1994 Free Software Foundation, Inc.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that
+the entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Foundation.
+
+
+File: find.info, Node: Top, Next: Introduction, Up: (dir)
+
+ This file documents the GNU utilities for finding files that match
+certain criteria and performing various actions on them. This is
+edition 1.1, for `find' version 4.1.
+
+* Menu:
+
+* Introduction:: Summary of the tasks this manual describes.
+* Finding Files:: Finding files that match certain criteria.
+* Actions:: Doing things to files you have found.
+* Common Tasks:: Solutions to common real-world problems.
+* Databases:: Maintaining file name databases.
+* File Permissions:: How to control access to files.
+* Reference:: Summary of how to invoke the programs.
+* Primary Index:: The components of `find' expressions.
+
+
+File: find.info, Node: Introduction, Next: Finding Files, Prev: Top, Up: Top
+
+Introduction
+************
+
+ This manual shows how to find files that meet criteria you specify,
+and how to perform various actions on the files that you find. The
+principal programs that you use to perform these tasks are `find',
+`locate', and `xargs'. Some of the examples in this manual use
+capabilities specific to the GNU versions of those programs.
+
+ GNU `find' was originally written by Eric Decker, with enhancements
+by David MacKenzie, Jay Plett, and Tim Wood. GNU `xargs' was
+originally written by Mike Rendell, with enhancements by David
+MacKenzie. GNU `locate' and its associated utilities were originally
+written by James Woods, with enhancements by David MacKenzie. The idea
+for `find -print0' and `xargs -0' came from Dan Bernstein. Many other
+people have contributed bug fixes, small improvements, and helpful
+suggestions. Thanks!
+
+ Mail suggestions and bug reports for these programs to
+`bug-gnu-utils@prep.ai.mit.edu'. Please include the version number,
+which you can get by running `find --version'.
+
+* Menu:
+
+* Scope::
+* Overview::
+* find Expressions::
+
+
+File: find.info, Node: Scope, Next: Overview, Up: Introduction
+
+Scope
+=====
+
+ For brevity, the word "file" in this manual means a regular file, a
+directory, a symbolic link, or any other kind of node that has a
+directory entry. A directory entry is also called a "file name". A
+file name may contain some, all, or none of the directories in a path
+that leads to the file. These are all examples of what this manual
+calls "file names":
+
+ parser.c
+ README
+ ./budget/may-94.sc
+ fred/.cshrc
+ /usr/local/include/termcap.h
+
+ A "directory tree" is a directory and the files it contains, all of
+its subdirectories and the files they contain, etc. It can also be a
+single non-directory file.
+
+ These programs enable you to find the files in one or more directory
+trees that:
+
+ * have names that contain certain text or match a certain pattern;
+
+ * are links to certain files;
+
+ * were last used during a certain period of time;
+
+ * are within a certain size range;
+
+ * are of a certain type (regular file, directory, symbolic link,
+ etc.);
+
+ * are owned by a certain user or group;
+
+ * have certain access permissions;
+
+ * contain text that matches a certain pattern;
+
+ * are within a certain depth in the directory tree;
+
+ * or some combination of the above.
+
+ Once you have found the files you're looking for (or files that are
+potentially the ones you're looking for), you can do more to them than
+simply list their names. You can get any combination of the files'
+attributes, or process the files in many ways, either individually or in
+groups of various sizes. Actions that you might want to perform on the
+files you have found include, but are not limited to:
+
+ * view or edit
+
+ * store in an archive
+
+ * remove or rename
+
+ * change access permissions
+
+ * classify into groups
+
+ This manual describes how to perform each of those tasks, and more.
+
+
+File: find.info, Node: Overview, Next: find Expressions, Prev: Scope, Up: Introduction
+
+Overview
+========
+
+ The principal programs used for making lists of files that match
+given criteria and running commands on them are `find', `locate', and
+`xargs'. An additional command, `updatedb', is used by system
+administrators to create databases for `locate' to use.
+
+ `find' searches for files in a directory hierarchy and prints
+information about the files it found. It is run like this:
+
+ find [FILE...] [EXPRESSION]
+
+Here is a typical use of `find'. This example prints the names of all
+files in the directory tree rooted in `/usr/src' whose name ends with
+`.c' and that are larger than 100 Kilobytes.
+ find /usr/src -name '*.c' -size +100k -print
+
+ `locate' searches special file name databases for file names that
+match patterns. The system administrator runs the `updatedb' program
+to create the databases. `locate' is run like this:
+
+ locate [OPTION...] PATTERN...
+
+This example prints the names of all files in the default file name
+database whose name ends with `Makefile' or `makefile'. Which file
+names are stored in the database depends on how the system
+administrator ran `updatedb'.
+ locate '*[Mm]akefile'
+
+ The name `xargs', pronounced EX-args, means "combine arguments."
+`xargs' builds and executes command lines by gathering together
+arguments it reads on the standard input. Most often, these arguments
+are lists of file names generated by `find'. `xargs' is run like this:
+
+ xargs [OPTION...] [COMMAND [INITIAL-ARGUMENTS]]
+
+The following command searches the files listed in the file `file-list'
+and prints all of the lines in them that contain the word `typedef'.
+ xargs grep typedef < file-list
+
+
+File: find.info, Node: find Expressions, Prev: Overview, Up: Introduction
+
+`find' Expressions
+==================
+
+ The expression that `find' uses to select files consists of one or
+more "primaries", each of which is a separate command line argument to
+`find'. `find' evaluates the expression each time it processes a file.
+An expression can contain any of the following types of primaries:
+
+"options"
+ affect overall operation rather than the processing of a specific
+ file;
+
+"tests"
+ return a true or false value, depending on the file's attributes;
+
+"actions"
+ have side effects and return a true or false value; and
+
+"operators"
+ connect the other arguments and affect when and whether they are
+ evaluated.
+
+ You can omit the operator between two primaries; it defaults to
+`-and'. *Note Combining Primaries With Operators::, for ways to
+connect primaries into more complex expressions. If the expression
+contains no actions other than `-prune', `-print' is performed on all
+files for which the entire expression is true (*note Print File
+Name::.).
+
+ Options take effect immediately, rather than being evaluated for each
+file when their place in the expression is reached. Therefore, for
+clarity, it is best to place them at the beginning of the expression.
+
+ Many of the primaries take arguments, which immediately follow them
+in the next command line argument to `find'. Some arguments are file
+names, patterns, or other strings; others are numbers. Numeric
+arguments can be specified as
+
+`+N'
+ for greater than N,
+
+`-N'
+ for less than N,
+
+`N'
+ for exactly N.
+
+
+File: find.info, Node: Finding Files, Next: Actions, Prev: Introduction, Up: Top
+
+Finding Files
+*************
+
+ By default, `find' prints to the standard output the names of the
+files that match the given criteria. *Note Actions::, for how to get
+more information about the matching files.
+
+* Menu:
+
+* Name::
+* Links::
+* Time::
+* Size::
+* Type::
+* Owner::
+* Permissions::
+* Contents::
+* Directories::
+* Filesystems::
+* Combining Primaries With Operators::
+
+
+File: find.info, Node: Name, Next: Links, Up: Finding Files
+
+Name
+====
+
+ Here are ways to search for files whose name matches a certain
+pattern. *Note Shell Pattern Matching::, for a description of the
+PATTERN arguments to these tests.
+
+ Each of these tests has a case-sensitive version and a
+case-insensitive version, whose name begins with `i'. In a
+case-insensitive comparison, the patterns `fo*' and `F??' match the
+file names `Foo', `FOO', `foo', `fOo', etc.
+
+* Menu:
+
+* Base Name Patterns::
+* Full Name Patterns::
+* Fast Full Name Search::
+* Shell Pattern Matching:: Wildcards used by these programs.
+
+
+File: find.info, Node: Base Name Patterns, Next: Full Name Patterns, Up: Name
+
+Base Name Patterns
+------------------
+
+ - Test: -name PATTERN
+ - Test: -iname PATTERN
+ True if the base of the file name (the path with the leading
+ directories removed) matches shell pattern PATTERN. For `-iname',
+ the match is case-insensitive. To ignore a whole directory tree,
+ use `-prune' (*note Directories::.). As an example, to find
+ Texinfo source files in `/usr/local/doc':
+
+ find /usr/local/doc -name '*.texi'
+
+
+File: find.info, Node: Full Name Patterns, Next: Fast Full Name Search, Prev: Base Name Patterns, Up: Name
+
+Full Name Patterns
+------------------
+
+ - Test: -path PATTERN
+ - Test: -ipath PATTERN
+ True if the entire file name, starting with the command line
+ argument under which the file was found, matches shell pattern
+ PATTERN. For `-ipath', the match is case-insensitive. To ignore
+ a whole directory tree, use `-prune' rather than checking every
+ file in the tree (*note Directories::.).
+
+ - Test: -regex EXPR
+ - Test: -iregex EXPR
+ True if the entire file name matches regular expression EXPR.
+ This is a match on the whole path, not a search. For example, to
+ match a file named `./fubar3', you can use the regular expression
+ `.*bar.' or `.*b.*3', but not `b.*r3'. *Note Syntax of Regular
+ Expressions: (emacs)Regexps, for a description of the syntax of
+ regular expressions. For `-iregex', the match is case-insensitive.
+
+
+File: find.info, Node: Fast Full Name Search, Next: Shell Pattern Matching, Prev: Full Name Patterns, Up: Name
+
+Fast Full Name Search
+---------------------
+
+ To search for files by name without having to actually scan the
+directories on the disk (which can be slow), you can use the `locate'
+program. For each shell pattern you give it, `locate' searches one or
+more databases of file names and displays the file names that contain
+the pattern. *Note Shell Pattern Matching::, for details about shell
+patterns.
+
+ If a pattern is a plain string--it contains no
+metacharacters--`locate' displays all file names in the database that
+contain that string. If a pattern contains metacharacters, `locate'
+only displays file names that match the pattern exactly. As a result,
+patterns that contain metacharacters should usually begin with a `*',
+and will most often end with one as well. The exceptions are patterns
+that are intended to explicitly match the beginning or end of a file
+name.
+
+ The command
+ locate PATTERN
+
+ is almost equivalent to
+ find DIRECTORIES -name PATTERN
+
+ where DIRECTORIES are the directories for which the file name
+databases contain information. The differences are that the `locate'
+information might be out of date, and that `locate' handles wildcards
+in the pattern slightly differently than `find' (*note Shell Pattern
+Matching::.).
+
+ The file name databases contain lists of files that were on the
+system when the databases were last updated. The system administrator
+can choose the file name of the default database, the frequency with
+which the databases are updated, and the directories for which they
+contain entries.
+
+ Here is how to select which file name databases `locate' searches.
+The default is system-dependent.
+
+`--database=PATH'
+`-d PATH'
+ Instead of searching the default file name database, search the
+ file name databases in PATH, which is a colon-separated list of
+ database file names. You can also use the environment variable
+ `LOCATE_PATH' to set the list of database files to search. The
+ option overrides the environment variable if both are used.
+
+
+File: find.info, Node: Shell Pattern Matching, Prev: Fast Full Name Search, Up: Name
+
+Shell Pattern Matching
+----------------------
+
+ `find' and `locate' can compare file names, or parts of file names,
+to shell patterns. A "shell pattern" is a string that may contain the
+following special characters, which are known as "wildcards" or
+"metacharacters".
+
+ You must quote patterns that contain metacharacters to prevent the
+shell from expanding them itself. Double and single quotes both work;
+so does escaping with a backslash.
+
+`*'
+ Matches any zero or more characters.
+
+`?'
+ Matches any one character.
+
+`[STRING]'
+ Matches exactly one character that is a member of the string
+ STRING. This is called a "character class". As a shorthand,
+ STRING may contain ranges, which consist of two characters with a
+ dash between them. For example, the class `[a-z0-9_]' matches a
+ lowercase letter, a number, or an underscore. You can negate a
+ class by placing a `!' or `^' immediately after the opening
+ bracket. Thus, `[^A-Z@]' matches any character except an
+ uppercase letter or an at sign.
+
+`\'
+ Removes the special meaning of the character that follows it. This
+ works even in character classes.
+
+ In the `find' tests that do shell pattern matching (`-name',
+`-path', etc.), wildcards in the pattern do not match a `.' at the
+beginning of a file name. This is not the case for `locate'. Thus,
+`find -name '*macs'' does not match a file named `.emacs', but `locate
+'*macs'' does.
+
+ Slash characters have no special significance in the shell pattern
+matching that `find' and `locate' do, unlike in the shell, in which
+wildcards do not match them. Therefore, a pattern `foo*bar' can match
+a file name `foo3/bar', and a pattern `./sr*sc' can match a file name
+`./src/misc'.
+
+
+File: find.info, Node: Links, Next: Time, Prev: Name, Up: Finding Files
+
+Links
+=====
+
+ There are two ways that files can be linked together. "Symbolic
+links" are a special type of file whose contents are a portion of the
+name of another file. "Hard links" are multiple directory entries for
+one file; the file names all have the same index node ("inode") number
+on the disk.
+
+* Menu:
+
+* Symbolic Links::
+* Hard Links::
+
+
+File: find.info, Node: Symbolic Links, Next: Hard Links, Up: Links
+
+Symbolic Links
+--------------
+
+ - Test: -lname PATTERN
+ - Test: -ilname PATTERN
+ True if the file is a symbolic link whose contents match shell
+ pattern PATTERN. For `-ilname', the match is case-insensitive.
+ *Note Shell Pattern Matching::, for details about the PATTERN
+ argument. So, to list any symbolic links to `sysdep.c' in the
+ current directory and its subdirectories, you can do:
+
+ find . -lname '*sysdep.c'
+
+ - Option: -follow
+ Dereference symbolic links. The following differences in behavior
+ occur when this option is given:
+
+ * `find' follows symbolic links to directories when searching
+ directory trees.
+
+ * `-lname' and `-ilname' always return false.
+
+ * `-type' reports the types of the files that symbolic links
+ point to.
+
+ * Implies `-noleaf' (*note Directories::.).
+
+
+File: find.info, Node: Hard Links, Prev: Symbolic Links, Up: Links
+
+Hard Links
+----------
+
+ To find hard links, first get the inode number of the file whose
+links you want to find. You can learn a file's inode number and the
+number of links to it by running `ls -i' or `find -ls'. If the file has
+more than one link, you can search for the other links by passing that
+inode number to `-inum'. Add the `-xdev' option if you are starting
+the search at a directory that has other filesystems mounted on it,
+such as `/usr' on many systems. Doing this saves needless searching,
+since hard links to a file must be on the same filesystem. *Note
+Filesystems::.
+
+ - Test: -inum N
+ File has inode number N.
+
+ You can also search for files that have a certain number of links,
+with `-links'. Directories normally have at least two hard links; their
+`.' entry is the second one. If they have subdirectories, each of
+those also has a hard link called `..' to its parent directory.
+
+ - Test: -links N
+ File has N hard links.
+
+
+File: find.info, Node: Time, Next: Size, Prev: Links, Up: Finding Files
+
+Time
+====
+
+ Each file has three time stamps, which record the last time that
+certain operations were performed on the file:
+
+ 1. access (read the file's contents)
+
+ 2. change the status (modify the file or its attributes)
+
+ 3. modify (change the file's contents)
+
+ You can search for files whose time stamps are within a certain age
+range, or compare them to other time stamps.
+
+* Menu:
+
+* Age Ranges::
+* Comparing Timestamps::
+
+
+File: find.info, Node: Age Ranges, Next: Comparing Timestamps, Up: Time
+
+Age Ranges
+----------
+
+ These tests are mainly useful with ranges (`+N' and `-N').
+
+ - Test: -atime N
+ - Test: -ctime N
+ - Test: -mtime N
+ True if the file was last accessed (or its status changed, or it
+ was modified) N*24 hours ago.
+
+ - Test: -amin N
+ - Test: -cmin N
+ - Test: -mmin N
+ True if the file was last accessed (or its status changed, or it
+ was modified) N minutes ago. These tests provide finer
+ granularity of measurement than `-atime' et al. For example, to
+ list files in `/u/bill' that were last read from 2 to 6 hours ago:
+
+ find /u/bill -amin +2 -amin -6
+
+ - Option: -daystart
+ Measure times from the beginning of today rather than from 24
+ hours ago. So, to list the regular files in your home directory
+ that were modified yesterday, do
+
+ find ~ -daystart -type f -mtime 1
+
+
+File: find.info, Node: Comparing Timestamps, Prev: Age Ranges, Up: Time
+
+Comparing Timestamps
+--------------------
+
+ As an alternative to comparing timestamps to the current time, you
+can compare them to another file's timestamp. That file's timestamp
+could be updated by another program when some event occurs. Or you
+could set it to a particular fixed date using the `touch' command. For
+example, to list files in `/usr' modified after February 1 of the
+current year:
+
+ touch -t 02010000 /tmp/stamp$$
+ find /usr -newer /tmp/stamp$$
+ rm -f /tmp/stamp$$
+
+ - Test: -anewer FILE
+ - Test: -cnewer FILE
+ - Test: -newer FILE
+ True if the file was last accessed (or its status changed, or it
+ was modified) more recently than FILE was modified. These tests
+ are affected by `-follow' only if `-follow' comes before them on
+ the command line. *Note Symbolic Links::, for more information on
+ `-follow'. As an example, to list any files modified since
+ `/bin/sh' was last modified:
+
+ find . -newer /bin/sh
+
+ - Test: -used N
+ True if the file was last accessed N days after its status was
+ last changed. Useful for finding files that are not being used,
+ and could perhaps be archived or removed to save disk space.
+
+
+File: find.info, Node: Size, Next: Type, Prev: Time, Up: Finding Files
+
+Size
+====
+
+ - Test: -size N[BCKW]
+ True if the file uses N units of space, rounding up. The units
+ are 512-byte blocks by default, but they can be changed by adding a
+ one-character suffix to N:
+
+ `b'
+ 512-byte blocks
+
+ `c'
+ bytes
+
+ `k'
+ kilobytes (1024 bytes)
+
+ `w'
+ 2-byte words
+
+ The size does not count indirect blocks, but it does count blocks
+ in sparse files that are not actually allocated.
+
+ - Test: -empty
+ True if the file is empty and is either a regular file or a
+ directory. This might make it a good candidate for deletion.
+ This test is useful with `-depth' (*note Directories::.) and
+ `-exec rm -rf '{}' ';'' (*note Single File::.).
+
+
+File: find.info, Node: Type, Next: Owner, Prev: Size, Up: Finding Files
+
+Type
+====
+
+ - Test: -type C
+ True if the file is of type C:
+
+ `b'
+ block (buffered) special
+
+ `c'
+ character (unbuffered) special
+
+ `d'
+ directory
+
+ `p'
+ named pipe (FIFO)
+
+ `f'
+ regular file
+
+ `l'
+ symbolic link
+
+ `s'
+ socket
+
+ - Test: -xtype C
+ The same as `-type' unless the file is a symbolic link. For
+ symbolic links: if `-follow' has not been given, true if the file
+ is a link to a file of type C; if `-follow' has been given, true
+ if C is `l'. In other words, for symbolic links, `-xtype' checks
+ the type of the file that `-type' does not check. *Note Symbolic
+ Links::, for more information on `-follow'.
+
+
+File: find.info, Node: Owner, Next: Permissions, Prev: Type, Up: Finding Files
+
+Owner
+=====
+
+ - Test: -user UNAME
+ - Test: -group GNAME
+ True if the file is owned by user UNAME (belongs to group GNAME).
+ A numeric ID is allowed.
+
+ - Test: -uid N
+ - Test: -gid N
+ True if the file's numeric user ID (group ID) is N. These tests
+ support ranges (`+N' and `-N'), unlike `-user' and `-group'.
+
+ - Test: -nouser
+ - Test: -nogroup
+ True if no user corresponds to the file's numeric user ID (no group
+ corresponds to the numeric group ID). These cases usually mean
+ that the files belonged to users who have since been removed from
+ the system. You probably should change the ownership of such
+ files to an existing user or group, using the `chown' or `chgrp'
+ program.
+
+
+File: find.info, Node: Permissions, Next: Contents, Prev: Owner, Up: Finding Files
+
+Permissions
+===========
+
+ *Note File Permissions::, for information on how file permissions are
+structured and how to specify them.
+
+ - Test: -perm MODE
+ True if the file's permissions are exactly MODE (which can be
+ numeric or symbolic). Symbolic modes use mode 0 as a point of
+ departure. If MODE starts with `-', true if *all* of the
+ permissions set in MODE are set for the file; permissions not set
+ in MODE are ignored. If MODE starts with `+', true if *any* of
+ the permissions set in MODE are set for the file; permissions not
+ set in MODE are ignored.
+
+
+File: find.info, Node: Contents, Next: Directories, Prev: Permissions, Up: Finding Files
+
+Contents
+========
+
+ To search for files based on their contents, you can use the `grep'
+program. For example, to find out which C source files in the current
+directory contain the string `thing', you can do:
+
+ grep -l thing *.[ch]
+
+ If you also want to search for the string in files in subdirectories,
+you can combine `grep' with `find' and `xargs', like this:
+
+ find . -name '*.[ch]' | xargs grep -l thing
+
+ The `-l' option causes `grep' to print only the names of files that
+contain the string, rather than the lines that contain it. The string
+argument (`thing') is actually a regular expression, so it can contain
+metacharacters. This method can be refined a little by using the `-r'
+option to make `xargs' not run `grep' if `find' produces no output, and
+using the `find' action `-print0' and the `xargs' option `-0' to avoid
+misinterpreting files whose names contain spaces:
+
+ find . -name '*.[ch]' -print0 | xargs -r -0 grep -l thing
+
+ For a fuller treatment of finding files whose contents match a
+pattern, see the manual page for `grep'.
+
+
+File: find.info, Node: Directories, Next: Filesystems, Prev: Contents, Up: Finding Files
+
+Directories
+===========
+
+ Here is how to control which directories `find' searches, and how it
+searches them. These two options allow you to process a horizontal
+slice of a directory tree.
+
+ - Option: -maxdepth LEVELS
+ Descend at most LEVELS (a non-negative integer) levels of
+ directories below the command line arguments. `-maxdepth 0' means
+ only apply the tests and actions to the command line arguments.
+
+ - Option: -mindepth LEVELS
+ Do not apply any tests or actions at levels less than LEVELS (a
+ non-negative integer). `-mindepth 1' means process all files
+ except the command line arguments.
+
+ - Option: -depth
+ Process each directory's contents before the directory itself.
+ Doing this is a good idea when producing lists of files to archive
+ with `cpio' or `tar'. If a directory does not have write
+ permission for its owner, its contents can still be restored from
+ the archive since the directory's permissions are restored after
+ its contents.
+
+ - Action: -prune
+ If `-depth' is not given, true; do not descend the current
+ directory. If `-depth' is given, false; no effect. `-prune' only
+ affects tests and actions that come after it in the expression, not
+ those that come before.
+
+ For example, to skip the directory `src/emacs' and all files and
+ directories under it, and print the names of the other files found:
+
+ find . -path './src/emacs' -prune -o -print
+
+ - Option: -noleaf
+ Do not optimize by assuming that directories contain 2 fewer
+ subdirectories than their hard link count. This option is needed
+ when searching filesystems that do not follow the Unix
+ directory-link convention, such as CD-ROM or MS-DOS filesystems or
+ AFS volume mount points. Each directory on a normal Unix
+ filesystem has at least 2 hard links: its name and its `.' entry.
+ Additionally, its subdirectories (if any) each have a `..' entry
+ linked to that directory. When `find' is examining a directory,
+ after it has statted 2 fewer subdirectories than the directory's
+ link count, it knows that the rest of the entries in the directory
+ are non-directories ("leaf" files in the directory tree). If only
+ the files' names need to be examined, there is no need to stat
+ them; this gives a significant increase in search speed.
+
+
+File: find.info, Node: Filesystems, Next: Combining Primaries With Operators, Prev: Directories, Up: Finding Files
+
+Filesystems
+===========
+
+ A "filesystem" is a section of a disk, either on the local host or
+mounted from a remote host over a network. Searching network
+filesystems can be slow, so it is common to make `find' avoid them.
+
+ There are two ways to avoid searching certain filesystems. One way
+is to tell `find' to only search one filesystem:
+
+ - Option: -xdev
+ - Option: -mount
+ Don't descend directories on other filesystems. These options are
+ synonyms.
+
+ The other way is to check the type of filesystem each file is on, and
+not descend directories that are on undesirable filesystem types:
+
+ - Test: -fstype TYPE
+ True if the file is on a filesystem of type TYPE. The valid
+ filesystem types vary among different versions of Unix; an
+ incomplete list of filesystem types that are accepted on some
+ version of Unix or another is:
+ ufs 4.2 4.3 nfs tmp mfs S51K S52K
+ You can use `-printf' with the `%F' directive to see the types of
+ your filesystems. *Note Print File Information::. `-fstype' is
+ usually used with `-prune' to avoid searching remote filesystems
+ (*note Directories::.).
+
+
+File: find.info, Node: Combining Primaries With Operators, Prev: Filesystems, Up: Finding Files
+
+Combining Primaries With Operators
+==================================
+
+ Operators build a complex expression from tests and actions. The
+operators are, in order of decreasing precedence:
+
+`( EXPR )'
+ Force precedence. True if EXPR is true.
+
+`! EXPR'
+`-not EXPR'
+ True if EXPR is false.
+
+`EXPR1 EXPR2'
+`EXPR1 -a EXPR2'
+`EXPR1 -and EXPR2'
+ And; EXPR2 is not evaluated if EXPR1 is false.
+
+`EXPR1 -o EXPR2'
+`EXPR1 -or EXPR2'
+ Or; EXPR2 is not evaluated if EXPR1 is true.
+
+`EXPR1 , EXPR2'
+ List; both EXPR1 and EXPR2 are always evaluated. True if EXPR2 is
+ true. The value of EXPR1 is discarded. This operator lets you do
+ multiple independent operations on one traversal, without
+ depending on whether other operations succeeded.
+
+ `find' searches the directory tree rooted at each file name by
+evaluating the expression from left to right, according to the rules of
+precedence, until the outcome is known (the left hand side is false for
+`-and', true for `-or'), at which point `find' moves on to the next
+file name.
+
+ There are two other tests that can be useful in complex expressions:
+
+ - Test: -true
+ Always true.
+
+ - Test: -false
+ Always false.
+
+
+File: find.info, Node: Actions, Next: Common Tasks, Prev: Finding Files, Up: Top
+
+Actions
+*******
+
+ There are several ways you can print information about the files that
+match the criteria you gave in the `find' expression. You can print
+the information either to the standard output or to a file that you
+name. You can also execute commands that have the file names as
+arguments. You can use those commands as further filters to select
+files.
+
+* Menu:
+
+* Print File Name::
+* Print File Information::
+* Run Commands::
+* Adding Tests::
+
+
+File: find.info, Node: Print File Name, Next: Print File Information, Up: Actions
+
+Print File Name
+===============
+
+ - Action: -print
+ True; print the full file name on the standard output, followed by
+ a newline.
+
+ - Action: -fprint FILE
+ True; print the full file name into file FILE, followed by a
+ newline. If FILE does not exist when `find' is run, it is
+ created; if it does exist, it is truncated to 0 bytes. The file
+ names `/dev/stdout' and `/dev/stderr' are handled specially; they
+ refer to the standard output and standard error output,
+ respectively.
+
+
+File: find.info, Node: Print File Information, Next: Run Commands, Prev: Print File Name, Up: Actions
+
+Print File Information
+======================
+
+ - Action: -ls
+ True; list the current file in `ls -dils' format on the standard
+ output. The output looks like this:
+
+ 204744 17 -rw-r--r-- 1 djm staff 17337 Nov 2 1992 ./lwall-quotes
+
+ The fields are:
+
+ 1. The inode number of the file. *Note Hard Links::, for how to
+ find files based on their inode number.
+
+ 2. the number of blocks in the file. The block counts are of 1K
+ blocks, unless the environment variable `POSIXLY_CORRECT' is
+ set, in which case 512-byte blocks are used. *Note Size::,
+ for how to find files based on their size.
+
+ 3. The file's type and permissions. The type is shown as a dash
+ for a regular file; for other file types, a letter like for
+ `-type' is used (*note Type::.). The permissions are read,
+ write, and execute for the file's owner, its group, and other
+ users, respectively; a dash means the permission is not
+ granted. *Note File Permissions::, for more details about
+ file permissions. *Note Permissions::, for how to find files
+ based on their permissions.
+
+ 4. The number of hard links to the file.
+
+ 5. The user who owns the file.
+
+ 6. The file's group.
+
+ 7. The file's size in bytes.
+
+ 8. The date the file was last modified.
+
+ 9. The file's name. `-ls' quotes non-printable characters in
+ the file names using C-like backslash escapes.
+
+ - Action: -fls FILE
+ True; like `-ls' but write to FILE like `-fprint' (*note Print
+ File Name::.).
+
+ - Action: -printf FORMAT
+ True; print FORMAT on the standard output, interpreting `\'
+ escapes and `%' directives. Field widths and precisions can be
+ specified as with the `printf' C function. Unlike `-print',
+ `-printf' does not add a newline at the end of the string.
+
+ - Action: -fprintf FILE FORMAT
+ True; like `-printf' but write to FILE like `-fprint' (*note Print
+ File Name::.).
+
+* Menu:
+
+* Escapes::
+* Format Directives::
+* Time Formats::
+
+
+File: find.info, Node: Escapes, Next: Format Directives, Up: Print File Information
+
+Escapes
+-------
+
+ The escapes that `-printf' and `-fprintf' recognize are:
+
+`\a'
+ Alarm bell.
+
+`\b'
+ Backspace.
+
+`\c'
+ Stop printing from this format immediately and flush the output.
+
+`\f'
+ Form feed.
+
+`\n'
+ Newline.
+
+`\r'
+ Carriage return.
+
+`\t'
+ Horizontal tab.
+
+`\v'
+ Vertical tab.
+
+`\\'
+ A literal backslash (`\').
+
+ A `\' character followed by any other character is treated as an
+ordinary character, so they both are printed, and a warning message is
+printed to the standard error output (because it was probably a typo).
+
+
+File: find.info, Node: Format Directives, Next: Time Formats, Prev: Escapes, Up: Print File Information
+
+Format Directives
+-----------------
+
+ `-printf' and `-fprintf' support the following format directives to
+print information about the file being processed. Unlike the C
+`printf' function, they do not support field width specifiers.
+
+ `%%' is a literal percent sign. A `%' character followed by any
+other character is discarded (but the other character is printed), and
+a warning message is printed to the standard error output (because it
+was probably a typo).
+
+* Menu:
+
+* Name Directives::
+* Ownership Directives::
+* Size Directives::
+* Location Directives::
+* Time Directives::
+
+
+File: find.info, Node: Name Directives, Next: Ownership Directives, Up: Format Directives
+
+Name Directives
+...............
+
+`%p'
+ File's name.
+
+`%f'
+ File's name with any leading directories removed (only the last
+ element).
+
+`%h'
+ Leading directories of file's name (all but the last element and
+ the slash before it).
+
+`%P'
+ File's name with the name of the command line argument under which
+ it was found removed from the beginning.
+
+`%H'
+ Command line argument under which file was found.
+
+
+File: find.info, Node: Ownership Directives, Next: Size Directives, Prev: Name Directives, Up: Format Directives
+
+Ownership Directives
+....................
+
+`%g'
+ File's group name, or numeric group ID if the group has no name.
+
+`%G'
+ File's numeric group ID.
+
+`%u'
+ File's user name, or numeric user ID if the user has no name.
+
+`%U'
+ File's numeric user ID.
+
+`%m'
+ File's permissions (in octal).
+
+
+File: find.info, Node: Size Directives, Next: Location Directives, Prev: Ownership Directives, Up: Format Directives
+
+Size Directives
+...............
+
+`%k'
+ File's size in 1K blocks (rounded up).
+
+`%b'
+ File's size in 512-byte blocks (rounded up).
+
+`%s'
+ File's size in bytes.
+
+
+File: find.info, Node: Location Directives, Next: Time Directives, Prev: Size Directives, Up: Format Directives
+
+Location Directives
+...................
+
+`%d'
+ File's depth in the directory tree; files named on the command line
+ have a depth of 0.
+
+`%F'
+ Type of the filesystem the file is on; this value can be used for
+ `-fstype' (*note Directories::.).
+
+`%l'
+ Object of symbolic link (empty string if file is not a symbolic
+ link).
+
+`%i'
+ File's inode number (in decimal).
+
+`%n'
+ Number of hard links to file.
+
+
+File: find.info, Node: Time Directives, Prev: Location Directives, Up: Format Directives
+
+Time Directives
+...............
+
+ Some of these directives use the C `ctime' function. Its output
+depends on the current locale, but it typically looks like
+
+ Wed Nov 2 00:42:36 1994
+
+`%a'
+ File's last access time in the format returned by the C `ctime'
+ function.
+
+`%AK'
+ File's last access time in the format specified by K (*note Time
+ Formats::.).
+
+`%c'
+ File's last status change time in the format returned by the C
+ `ctime' function.
+
+`%CK'
+ File's last status change time in the format specified by K (*note
+ Time Formats::.).
+
+`%t'
+ File's last modification time in the format returned by the C
+ `ctime' function.
+
+`%TK'
+ File's last modification time in the format specified by K (*note
+ Time Formats::.).
+
+
+File: find.info, Node: Time Formats, Prev: Format Directives, Up: Print File Information
+
+Time Formats
+------------
+
+ Below are the formats for the directives `%A', `%C', and `%T', which
+print the file's timestamps. Some of these formats might not be
+available on all systems, due to differences in the C `strftime'
+function between systems.
+
+* Menu:
+
+* Time Components::
+* Date Components::
+* Combined Time Formats::
+
+
+File: find.info, Node: Time Components, Next: Date Components, Up: Time Formats
+
+Time Components
+...............
+
+ The following format directives print single components of the time.
+
+`H'
+ hour (00..23)
+
+`I'
+ hour (01..12)
+
+`k'
+ hour ( 0..23)
+
+`l'
+ hour ( 1..12)
+
+`p'
+ locale's AM or PM
+
+`Z'
+ time zone (e.g., EDT), or nothing if no time zone is determinable
+
+`M'
+ minute (00..59)
+
+`S'
+ second (00..61)
+
+`@'
+ seconds since Jan. 1, 1970, 00:00 GMT.
+
+
+File: find.info, Node: Date Components, Next: Combined Time Formats, Prev: Time Components, Up: Time Formats
+
+Date Components
+...............
+
+ The following format directives print single components of the date.
+
+`a'
+ locale's abbreviated weekday name (Sun..Sat)
+
+`A'
+ locale's full weekday name, variable length (Sunday..Saturday)
+
+`b'
+`h'
+ locale's abbreviated month name (Jan..Dec)
+
+`B'
+ locale's full month name, variable length (January..December)
+
+`m'
+ month (01..12)
+
+`d'
+ day of month (01..31)
+
+`w'
+ day of week (0..6)
+
+`j'
+ day of year (001..366)
+
+`U'
+ week number of year with Sunday as first day of week (00..53)
+
+`W'
+ week number of year with Monday as first day of week (00..53)
+
+`Y'
+ year (1970...)
+
+`y'
+ last two digits of year (00..99)
+
+
+File: find.info, Node: Combined Time Formats, Prev: Date Components, Up: Time Formats
+
+Combined Time Formats
+.....................
+
+ The following format directives print combinations of time and date
+components.
+
+`r'
+ time, 12-hour (hh:mm:ss [AP]M)
+
+`T'
+ time, 24-hour (hh:mm:ss)
+
+`X'
+ locale's time representation (H:M:S)
+
+`c'
+ locale's date and time (Sat Nov 04 12:02:33 EST 1989)
+
+`D'
+ date (mm/dd/yy)
+
+`x'
+ locale's date representation (mm/dd/yy)
+
+
+File: find.info, Node: Run Commands, Next: Adding Tests, Prev: Print File Information, Up: Actions
+
+Run Commands
+============
+
+ You can use the list of file names created by `find' or `locate' as
+arguments to other commands. In this way you can perform arbitrary
+actions on the files.
+
+* Menu:
+
+* Single File::
+* Multiple Files::
+* Querying::
+
+
+File: find.info, Node: Single File, Next: Multiple Files, Up: Run Commands
+
+Single File
+-----------
+
+ Here is how to run a command on one file at a time.
+
+ - Action: -exec COMMAND ;
+ Execute COMMAND; true if 0 status is returned. `find' takes all
+ arguments after `-exec' to be part of the command until an
+ argument consisting of `;' is reached. It replaces the string
+ `{}' by the current file name being processed everywhere it occurs
+ in the command. Both of these constructions need to be escaped
+ (with a `\') or quoted to protect them from expansion by the shell.
+ The command is executed in the directory in which `find' was run.
+
+ For example, to compare each C header file in the current
+ directory with the file `/tmp/master':
+
+ find . -name '*.h' -exec diff -u '{}' /tmp/master ';'
+
+
+File: find.info, Node: Multiple Files, Next: Querying, Prev: Single File, Up: Run Commands
+
+Multiple Files
+--------------
+
+ Sometimes you need to process files alone. But when you don't, it
+is faster to run a command on as many files as possible at a time,
+rather than once per file. Doing this saves on the time it takes to
+start up the command each time.
+
+ To run a command on more than one file at once, use the `xargs'
+command, which is invoked like this:
+
+ xargs [OPTION...] [COMMAND [INITIAL-ARGUMENTS]]
+
+ `xargs' reads arguments from the standard input, delimited by blanks
+(which can be protected with double or single quotes or a backslash) or
+newlines. It executes the COMMAND (default is `/bin/echo') one or more
+times with any INITIAL-ARGUMENTS followed by arguments read from
+standard input. Blank lines on the standard input are ignored.
+
+ Instead of blank-delimited names, it is safer to use `find -print0'
+or `find -fprint0' and process the output by giving the `-0' or
+`--null' option to GNU `xargs', GNU `tar', GNU `cpio', or `perl'.
+
+ You can use shell command substitution (backquotes) to process a
+list of arguments, like this:
+
+ grep -l sprintf `find $HOME -name '*.c' -print`
+
+ However, that method produces an error if the length of the `.c'
+file names exceeds the operating system's command-line length limit.
+`xargs' avoids that problem by running the command as many times as
+necessary without exceeding the limit:
+
+ find $HOME -name '*.c' -print | grep -l sprintf
+
+ However, if the command needs to have its standard input be a
+terminal (`less', for example), you have to use the shell command
+substitution method.
+
+* Menu:
+
+* Unsafe File Name Handling::
+* Safe File Name Handling::
+* Limiting Command Size::
+* Interspersing File Names::
+
+
+File: find.info, Node: Unsafe File Name Handling, Next: Safe File Name Handling, Up: Multiple Files
+
+Unsafe File Name Handling
+.........................
+
+ Because file names can contain quotes, backslashes, blank characters,
+and even newlines, it is not safe to process them using `xargs' in its
+default mode of operation. But since most files' names do not contain
+blanks, this problem occurs only infrequently. If you are only
+searching through files that you know have safe names, then you need not
+be concerned about it.
+
+ In many applications, if `xargs' botches processing a file because
+its name contains special characters, some data might be lost. The
+importance of this problem depends on the importance of the data and
+whether anyone notices the loss soon enough to correct it. However,
+here is an extreme example of the problems that using blank-delimited
+names can cause. If the following command is run daily from `cron',
+then any user can remove any file on the system:
+
+ find / -name '#*' -atime +7 -print | xargs rm
+
+ For example, you could do something like this:
+
+ eg$ echo > '#
+ vmunix'
+
+and then `cron' would delete `/vmunix', if it ran `xargs' with `/' as
+its current directory.
+
+ To delete other files, for example `/u/joeuser/.plan', you could do
+this:
+
+ eg$ mkdir '#
+ '
+ eg$ cd '#
+ '
+ eg$ mkdir u u/joeuser u/joeuser/.plan'
+ '
+ eg$ echo > u/joeuser/.plan'
+ /#foo'
+ eg$ cd ..
+ eg$ find . -name '#*' -print | xargs echo
+ ./# ./# /u/joeuser/.plan /#foo
+
+
+File: find.info, Node: Safe File Name Handling, Next: Limiting Command Size, Prev: Unsafe File Name Handling, Up: Multiple Files
+
+Safe File Name Handling
+.......................
+
+ Here is how to make `find' output file names so that they can be
+used by other programs without being mangled or misinterpreted. You can
+process file names generated this way by giving the `-0' or `--null'
+option to GNU `xargs', GNU `tar', GNU `cpio', or `perl'.
+
+ - Action: -print0
+ True; print the full file name on the standard output, followed by
+ a null character.
+
+ - Action: -fprint0 FILE
+ True; like `-print0' but write to FILE like `-fprint' (*note Print
+ File Name::.).
+
+
+File: find.info, Node: Limiting Command Size, Next: Interspersing File Names, Prev: Safe File Name Handling, Up: Multiple Files
+
+Limiting Command Size
+.....................
+
+ `xargs' gives you control over how many arguments it passes to the
+command each time it executes it. By default, it uses up to `ARG_MAX'
+- 2k, or 20k, whichever is smaller, characters per command. It uses as
+many lines and arguments as fit within that limit. The following
+options modify those values.
+
+`--no-run-if-empty'
+`-r'
+ If the standard input does not contain any nonblanks, do not run
+ the command. By default, the command is run once even if there is
+ no input.
+
+`--max-lines[=MAX-LINES]'
+`-l[MAX-LINES]'
+ Use at most MAX-LINES nonblank input lines per command line;
+ MAX-LINES defaults to 1 if omitted. Trailing blanks cause an
+ input line to be logically continued on the next input line, for
+ the purpose of counting the lines. Implies `-x'.
+
+`--max-args=MAX-ARGS'
+`-n MAX-ARGS'
+ Use at most MAX-ARGS arguments per command line. Fewer than
+ MAX-ARGS arguments will be used if the size (see the `-s' option)
+ is exceeded, unless the `-x' option is given, in which case
+ `xargs' will exit.
+
+`--max-chars=MAX-CHARS'
+`-s MAX-CHARS'
+ Use at most MAX-CHARS characters per command line, including the
+ command and initial arguments and the terminating nulls at the
+ ends of the argument strings.
+
+`--max-procs=MAX-PROCS'
+`-P MAX-PROCS'
+ Run up to MAX-PROCS processes at a time; the default is 1. If
+ MAX-PROCS is 0, `xargs' will run as many processes as possible at
+ a time. Use the `-n', `-s', or `-l' option with `-P'; otherwise
+ chances are that the command will be run only once.
+
+
+File: find.info, Node: Interspersing File Names, Prev: Limiting Command Size, Up: Multiple Files
+
+Interspersing File Names
+........................
+
+ `xargs' can insert the name of the file it is processing between
+arguments you give for the command. Unless you also give options to
+limit the command size (*note Limiting Command Size::.), this mode of
+operation is equivalent to `find -exec' (*note Single File::.).
+
+`--replace[=REPLACE-STR]'
+`-i[REPLACE-STR]'
+ Replace occurences of REPLACE-STR in the initial arguments with
+ names read from standard input. Also, unquoted blanks do not
+ terminate arguments. If REPLACE-STR is omitted, it defaults to
+ `{}' (like for `find -exec'). Implies `-x' and `-l 1'. As an
+ example, to sort each file the `bills' directory, leaving the
+ output in that file name with `.sorted' appended, you could do:
+
+ find bills -type f | xargs -iXX sort -o XX.sorted XX
+
+ The equivalent command using `find -exec' is:
+
+ find bills -type f -exec sort -o '{}.sorted' '{}' ';'
+
+
+File: find.info, Node: Querying, Prev: Multiple Files, Up: Run Commands
+
+Querying
+--------
+
+ To ask the user whether to execute a command on a single file, you
+can use the `find' primary `-ok' instead of `-exec':
+
+ - Action: -ok COMMAND ;
+ Like `-exec' (*note Single File::.), but ask the user first (on
+ the standard input); if the response does not start with `y' or
+ `Y', do not run the command, and return false.
+
+ When processing multiple files with a single command, to query the
+user you give `xargs' the following option. When using this option, you
+might find it useful to control the number of files processed per
+invocation of the command (*note Limiting Command Size::.).
+
+`--interactive'
+`-p'
+ Prompt the user about whether to run each command line and read a
+ line from the terminal. Only run the command line if the response
+ starts with `y' or `Y'. Implies `-t'.
+
+
+File: find.info, Node: Adding Tests, Prev: Run Commands, Up: Actions
+
+Adding Tests
+============
+
+ You can test for file attributes that none of the `find' builtin
+tests check. To do this, use `xargs' to run a program that filters a
+list of files printed by `find'. If possible, use `find' builtin tests
+to pare down the list, so the program run by `xargs' has less work to
+do. The tests builtin to `find' will likely run faster than tests that
+other programs perform.
+
+ For example, here is a way to print the names of all of the
+unstripped binaries in the `/usr/local' directory tree. Builtin tests
+avoid running `file' on files that are not regular files or are not
+executable.
+
+ find /usr/local -type f -perm +a=x | xargs file |
+ grep 'not stripped' | cut -d: -f1
+
+The `cut' program removes everything after the file name from the
+output of `file'.
+
+ If you want to place a special test somewhere in the middle of a
+`find' expression, you can use `-exec' to run a program that performs
+the test. Because `-exec' evaluates to the exit status of the executed
+program, you can write a program (which can be a shell script) that
+tests for a special attribute and make it exit with a true (zero) or
+false (non-zero) status. It is a good idea to place such a special
+test *after* the builtin tests, because it starts a new process which
+could be avoided if a builtin test evaluates to false. Use this method
+only when `xargs' is not flexible enough, because starting one or more
+new processes to test each file is slower than using `xargs' to start
+one process that tests many files.
+
+ Here is a shell script called `unstripped' that checks whether its
+argument is an unstripped binary file:
+
+ #!/bin/sh
+ file $1 | grep 'not stripped' > /dev/null
+
+ This script relies on the fact that the shell exits with the status
+of the last program it executed, in this case `grep'. `grep' exits
+with a true status if it found any matches, false if not. Here is an
+example of using the script (assuming it is in your search path). It
+lists the stripped executables in the file `sbins' and the unstripped
+ones in `ubins'.
+
+ find /usr/local -type f -perm +a=x \
+ \( -exec unstripped '{}' \; -fprint ubins -o -fprint sbins \)
+
+
+File: find.info, Node: Common Tasks, Next: Databases, Prev: Actions, Up: Top
+
+Common Tasks
+************
+
+ The sections that follow contain some extended examples that both
+give a good idea of the power of these programs, and show you how to
+solve common real-world problems.
+
+* Menu:
+
+* Viewing And Editing::
+* Archiving::
+* Cleaning Up::
+* Strange File Names::
+* Fixing Permissions::
+* Classifying Files::
+
View Lorry Controller Status