   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.

   This file documents the GNU utilities for finding files that match
certain criteria and performing various actions on them.  This is
edition 4.1.6, for `find' version 4.1.6.

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-findutils@gnu.org'.  Please include the version number, which you
can get by running `find --version'.

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.

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

`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'.  See 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 (see 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.

Finding Files
*************

   By default, `find' prints to the standard output the names of the
files that match the given criteria.  See Actions, for how to get
more information about the matching files.

Name
====

   Here are ways to search for files whose name matches a certain
pattern.  See 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.

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' (see Directories).  As an example, to find Texinfo
     source files in `/usr/local/doc':

          find /usr/local/doc -name '*.texi'

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 (see 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'.  See Syntax of Regular Expressions (emacs),
     for a description of the syntax of
     regular expressions.  For `-iregex', the match is case-insensitive.

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.  See 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' (see 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.

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'.

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.

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.
     See 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' (see Directories).

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.  See
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.

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.

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 minutes
     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

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.  See 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.

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' (see Directories) and `-exec
     rm -rf '{}' ';'' (see Single File).

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.  See Symbolic Links,
     for more information on `-follow'.

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.

Permissions
===========

   See 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.

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'.

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 into 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.

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.  See Print File Information.  `-fstype' is
     usually used with `-prune' to avoid searching remote filesystems
     (see Directories).

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.

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.

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.

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.  See 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.  See 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 (see 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.  See File Permissions, for more details about
          file permissions.  See 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' (see 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' (see Print File Name).

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).

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).

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.

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).

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.

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' (see 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.

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 (see 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 (see
     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 (see
     Time Formats).

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.

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.

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)

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)

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.

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 ';'

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 | xargs 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.

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

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' (see Print File Name).

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.

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 (see Limiting Command Size), this mode of
operation is equivalent to `find -exec' (see Single File).

`--replace[=REPLACE-STR]'
`-i[REPLACE-STR]'
     Replace occurrences 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' '{}' ';'

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' (see 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 (see 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'.

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 \)

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.