* README-alpha: added alpha README file

[findutils.git] / doc / find.info-2

This is Info file find.info, produced by Makeinfo version 1.68 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.

\x1f
File: find.info,  Node: Viewing And Editing,  Next: Archiving,  Up: Common Tasks

Viewing And Editing
===================

   To view a list of files that meet certain criteria, simply run your
file viewing program with the file names as arguments.  Shells
substitute a command enclosed in backquotes with its output, so the
whole command looks like this:

     less `find /usr/include -name '*.h' | xargs grep -l mode_t`

You can edit those files by giving an editor name instead of a file
viewing program.

\x1f
File: find.info,  Node: Archiving,  Next: Cleaning Up,  Prev: Viewing And Editing,  Up: Common Tasks

Archiving
=========

   You can pass a list of files produced by `find' to a file archiving
program.  GNU `tar' and `cpio' can both read lists of file names from
the standard input--either delimited by nulls (the safe way) or by
blanks (the lazy, risky default way).  To use null-delimited names,
give them the `--null' option.  You can store a file archive in a file,
write it on a tape, or send it over a network to extract on another
machine.

   One common use of `find' to archive files is to send a list of the
files in a directory tree to `cpio'.  Use `-depth' so 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.  Here is an example of doing this using
`cpio'; you could use a more complex `find' expression to archive only
certain files.

     find . -depth -print0 |
       cpio --create --null --format=crc --file=/dev/nrst0

   You could restore that archive using this command:

     cpio --extract --null --make-dir --unconditional \
       --preserve --file=/dev/nrst0

   Here are the commands to do the same things using `tar':

     find . -depth -print0 |
       tar --create --null --files-from=- --file=/dev/nrst0
     
     tar --extract --null --preserve-perm --same-owner \
       --file=/dev/nrst0

   Here is an example of copying a directory from one machine to
another:

     find . -depth -print0 | cpio -0o -Hnewc |
       rsh OTHER-MACHINE "cd `pwd` && cpio -i0dum"

\x1f
File: find.info,  Node: Cleaning Up,  Next: Strange File Names,  Prev: Archiving,  Up: Common Tasks

Cleaning Up
===========

   This section gives examples of removing unwanted files in various
situations.  Here is a command to remove the CVS backup files created
when an update requires a merge:

     find . -name '.#*' -print0 | xargs -0r rm -f

   You can run this command to clean out your clutter in `/tmp'.  You
might place it in the file your shell runs when you log out
(`.bash_logout', `.logout', or `.zlogout', depending on which shell you
use).

     find /tmp -user $LOGNAME -type f -print0 | xargs -0 -r rm -f

   To remove old Emacs backup and auto-save files, you can use a command
like the following.  It is especially important in this case to use
null-terminated file names because Emacs packages like the VM mailer
often create temporary file names with spaces in them, like `#reply to
David J. MacKenzie<1>#'.

     find ~ \( -name '*~' -o -name '#*#' \) -print0 |
       xargs --no-run-if-empty --null rm -vf

   Removing old files from `/tmp' is commonly done from `cron':

     find /tmp /var/tmp -not -type d -mtime +3 -print0 |
       xargs --null --no-run-if-empty rm -f
     
     find /tmp /var/tmp -depth -mindepth 1 -type d -empty -print0 |
       xargs --null --no-run-if-empty rmdir

   The second `find' command above uses `-depth' so it cleans out empty
directories depth-first, hoping that the parents become empty and can
be removed too.  It uses `-mindepth' to avoid removing `/tmp' itself if
it becomes totally empty.

\x1f
File: find.info,  Node: Strange File Names,  Next: Fixing Permissions,  Prev: Cleaning Up,  Up: Common Tasks

Strange File Names
==================

   `find' can help you remove or rename a file with strange characters
in its name.  People are sometimes stymied by files whose names contain
characters such as spaces, tabs, control characters, or characters with
the high bit set.  The simplest way to remove such files is:

     rm -i SOME*PATTERN*THAT*MATCHES*THE*PROBLEM*FILE

   `rm' asks you whether to remove each file matching the given
pattern.  If you are using an old shell, this approach might not work if
the file name contains a character with the high bit set; the shell may
strip it off.  A more reliable way is:

     find . -maxdepth 1 TESTS -ok rm '{}' \;

where TESTS uniquely identify the file.  The `-maxdepth 1' option
prevents `find' from wasting time searching for the file in any
subdirectories; if there are no subdirectories, you may omit it.  A
good way to uniquely identify the problem file is to figure out its
inode number; use

     ls -i

   Suppose you have a file whose name contains control characters, and
you have found that its inode number is 12345.  This command prompts
you for whether to remove it:

     find . -maxdepth 1 -inum 12345 -ok rm -f '{}' \;

   If you don't want to be asked, perhaps because the file name may
contain a strange character sequence that will mess up your screen when
printed, then use `-exec' instead of `-ok'.

   If you want to rename the file instead, you can use `mv' instead of
`rm':

     find . -maxdepth 1 -inum 12345 -ok mv '{}' NEW-FILE-NAME \;

\x1f
File: find.info,  Node: Fixing Permissions,  Next: Classifying Files,  Prev: Strange File Names,  Up: Common Tasks

Fixing Permissions
==================

   Suppose you want to make sure that everyone can write to the
directories in a certain directory tree.  Here is a way to find
directories lacking either user or group write permission (or both),
and fix their permissions:

     find . -type d -not -perm -ug=w | xargs chmod ug+w

You could also reverse the operations, if you want to make sure that
directories do *not* have world write permission.

\x1f
File: find.info,  Node: Classifying Files,  Prev: Fixing Permissions,  Up: Common Tasks

Classifying Files
=================

   If you want to classify a set of files into several groups based on
different criteria, you can use the comma operator to perform multiple
independent tests on the files.  Here is an example:

     find / -type d \( -perm -o=w -fprint allwrite , \
       -perm -o=x -fprint allexec \)
     
     echo "Directories that can be written to by everyone:"
     cat allwrite
     echo ""
     echo "Directories with search permissions for everyone:"
     cat allexec

   `find' has only to make one scan through the directory tree (which
is one of the most time consuming parts of its work).

\x1f
File: find.info,  Node: Databases,  Next: File Permissions,  Prev: Common Tasks,  Up: Top

File Name Databases
*******************

   The file name databases used by `locate' contain lists of files that
were in particular directory trees when the databases were last
updated.  The file name of the default database is determined when
`locate' and `updatedb' are configured and installed.  The frequency
with which the databases are updated and the directories for which they
contain entries depend on how often `updatedb' is run, and with which
arguments.

* Menu:

* Database Locations::
* Database Formats::

\x1f
File: find.info,  Node: Database Locations,  Next: Database Formats,  Up: Databases

Database Locations
==================

   There can be multiple file name databases.  Users can select which
databases `locate' searches using an environment variable or a command
line option.  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.  File name
databases are updated by running the `updatedb' program, typically
nightly.

   In networked environments, it often makes sense to build a database
at the root of each filesystem, containing the entries for that
filesystem.  `updatedb' is then run for each filesystem on the
fileserver where that filesystem is on a local disk, to prevent
thrashing the network.  Here are the options to `updatedb' to select
which directories each database contains entries for:

`--localpaths='PATH...''
     Non-network directories to put in the database.  Default is `/'.

`--netpaths='PATH...''
     Network (NFS, AFS, RFS, etc.) directories to put in the database.
     The environment variable `NETPATHS' also sets this value.  Default
     is none.

`--prunepaths='PATH...''
     Directories to not put in the database, which would otherwise be.
     The environment variable `PRUNEPATHS' also sets this value.
     Default is `/tmp /usr/tmp /var/tmp /afs'.

`--prunefs='PATH...''
     File systems to not put in the database, which would otherwise be.
     Note that files are pruned when a file system is reached; Any file
     system mounted under an undesired file system will be ignored.
     The environment variable `PRUNEFS' also sets this value.  Default
     is `nfs NFS proc'.

`--output=DBFILE'
     The database file to build.  Default is system-dependent, but
     typically `/usr/local/var/locatedb'.

`--localuser=USER'
     The user to search the non-network directories as, using `su'.
     Default is to search the non-network directories as the current
     user.  You can also use the environment variable `LOCALUSER' to
     set this user.

`--netuser=USER'
     The user to search network directories as, using `su'.  Default is
     `daemon'.  You can also use the environment variable `NETUSER' to
     set this user.

\x1f
File: find.info,  Node: Database Formats,  Prev: Database Locations,  Up: Databases

Database Formats
================

   The file name databases contain lists of files that were in
particular directory trees when the databases were last updated.  The
file name database format changed starting with GNU `locate' version
4.0 to allow machines with diffent byte orderings to share the
databases.  The new GNU `locate' can read both the old and new database
formats.  However, old versions of `locate' and `find' produce incorrect
results if given a new-format database.

* Menu:

* New Database Format::
* Sample Database::
* Old Database Format::

\x1f
File: find.info,  Node: New Database Format,  Next: Sample Database,  Up: Database Formats

New Database Format
-------------------

   `updatedb' runs a program called `frcode' to "front-compress" the
list of file names, which reduces the database size by a factor of 4 to
5.  Front-compression (also known as incremental encoding) works as
follows.

   The database entries are a sorted list (case-insensitively, for
users' convenience).  Since the list is sorted, each entry is likely to
share a prefix (initial string) with the previous entry.  Each database
entry begins with an offset-differential count byte, which is the
additional number of characters of prefix of the preceding entry to use
beyond the number that the preceding entry is using of its predecessor.
(The counts can be negative.)  Following the count is a
null-terminated ASCII remainder--the part of the name that follows the
shared prefix.

   If the offset-differential count is larger than can be stored in a
byte (+/-127), the byte has the value 0x80 and the count follows in a
2-byte word, with the high byte first (network byte order).

   Every database begins with a dummy entry for a file called
`LOCATE02', which `locate' checks for to ensure that the database file
has the correct format; it ignores the entry in doing the search.

   Databases can not be concatenated together, even if the first (dummy)
entry is trimmed from all but the first database.  This is because the
offset-differential count in the first entry of the second and following
databases will be wrong.

\x1f
File: find.info,  Node: Sample Database,  Next: Old Database Format,  Prev: New Database Format,  Up: Database Formats

Sample Database
---------------

   Sample input to `frcode':

     /usr/src
     /usr/src/cmd/aardvark.c
     /usr/src/cmd/armadillo.c
     /usr/tmp/zoo

   Length of the longest prefix of the preceding entry to share:

     0 /usr/src
     8 /cmd/aardvark.c
     14 rmadillo.c
     5 tmp/zoo

   Output from `frcode', with trailing nulls changed to newlines and
count bytes made printable:

     0 LOCATE02
     0 /usr/src
     8 /cmd/aardvark.c
     6 rmadillo.c
     -9 tmp/zoo

   (6 = 14 - 8, and -9 = 5 - 14)

\x1f
File: find.info,  Node: Old Database Format,  Prev: Sample Database,  Up: Database Formats

Old Database Format
-------------------

   The old database format is used by Unix `locate' and `find' programs
and earlier releases of the GNU ones.  `updatedb' produces this format
if given the `--old-format' option.

   `updatedb' runs programs called `bigram' and `code' to produce
old-format databases.  The old format differs from the new one in the
following ways.  Instead of each entry starting with an
offset-differential count byte and ending with a null, byte values from
0 through 28 indicate offset-differential counts from -14 through 14.
The byte value indicating that a long offset-differential count follows
is 0x1e (30), not 0x80.  The long counts are stored in host byte order,
which is not necessarily network byte order, and host integer word size,
which is usually 4 bytes.  They also represent a count 14 less than
their value.  The database lines have no termination byte; the start of
the next line is indicated by its first byte having a value <= 30.

   In addition, instead of starting with a dummy entry, the old database
format starts with a 256 byte table containing the 128 most common
bigrams in the file list.  A bigram is a pair of adjacent bytes.  Bytes
in the database that have the high bit set are indexes (with the high
bit cleared) into the bigram table.  The bigram and offset-differential
count coding makes these databases 20-25% smaller than the new format,
but makes them not 8-bit clean.  Any byte in a file name that is in the
ranges used for the special codes is replaced in the database by a
question mark, which not coincidentally is the shell wildcard to match a
single character.

\x1f
File: find.info,  Node: File Permissions,  Next: Reference,  Prev: Databases,  Up: Top

File Permissions
****************

   Each file has a set of "permissions" that control the kinds of
access that users have to that file.  The permissions for a file are
also called its "access mode".  They can be represented either in
symbolic form or as an octal number.

* Menu:

* Mode Structure::              Structure of file permissions.
* Symbolic Modes::              Mnemonic permissions representation.
* Numeric Modes::               Permissions as octal numbers.

\x1f
File: find.info,  Node: Mode Structure,  Next: Symbolic Modes,  Up: File Permissions

Structure of File Permissions
=============================

   There are three kinds of permissions that a user can have for a file:

  1. permission to read the file.  For directories, this means
     permission to list the contents of the directory.

  2. permission to write to (change) the file.  For directories, this
     means permission to create and remove files in the directory.

  3. permission to execute the file (run it as a program).  For
     directories, this means permission to access files in the
     directory.

   There are three categories of users who may have different
permissions to perform any of the above operations on a file:

  1. the file's owner;

  2. other users who are in the file's group;

  3. everyone else.

   Files are given an owner and group when they are created.  Usually
the owner is the current user and the group is the group of the
directory the file is in, but this varies with the operating system, the
filesystem the file is created on, and the way the file is created.  You
can change the owner and group of a file by using the `chown' and
`chgrp' commands.

   In addition to the three sets of three permissions listed above, a
file's permissions have three special components, which affect only
executable files (programs) and, on some systems, directories:

  1. set the process's effective user ID to that of the file upon
     execution (called the "setuid bit").  No effect on directories.

  2. set the process's effective group ID to that of the file upon
     execution (called the "setgid bit").  For directories on some
     systems, put files created in the directory into the same group as
     the directory, no matter what group the user who creates them is
     in.

  3. save the program's text image on the swap device so it will load
     more quickly when run (called the "sticky bit").  For directories
     on some systems, prevent users from removing files that they do
     not own in the directory; this is called making the directory
     "append-only".

\x1f
File: find.info,  Node: Symbolic Modes,  Next: Numeric Modes,  Prev: Mode Structure,  Up: File Permissions

Symbolic Modes
==============

   "Symbolic modes" represent changes to files' permissions as
operations on single-character symbols.  They allow you to modify either
all or selected parts of files' permissions, optionally based on their
previous values, and perhaps on the current `umask' as well (*note
Umask and Protection::.).

   The format of symbolic modes is:

     [ugoa...][[+-=][rwxXstugo...]...][,...]

   The following sections describe the operators and other details of
symbolic modes.

* Menu:

* Setting Permissions::          Basic operations on permissions.
* Copying Permissions::          Copying existing permissions.
* Changing Special Permissions:: Special permissions.
* Conditional Executability::    Conditionally affecting executability.
* Multiple Changes::             Making multiple changes.
* Umask and Protection::              The effect of the umask.

\x1f
File: find.info,  Node: Setting Permissions,  Next: Copying Permissions,  Up: Symbolic Modes

Setting Permissions
-------------------

   The basic symbolic operations on a file's permissions are adding,
removing, and setting the permission that certain users have to read,
write, and execute the file.  These operations have the following
format:

     USERS OPERATION PERMISSIONS

The spaces between the three parts above are shown for readability only;
symbolic modes can not contain spaces.

   The USERS part tells which users' access to the file is changed.  It
consists of one or more of the following letters (or it can be empty;
*note Umask and Protection::., for a description of what happens then).
When more than one of these letters is given, the order that they are
in does not matter.

`u'
     the user who owns the file;

`g'
     other users who are in the file's group;

`o'
     all other users;

`a'
     all users; the same as `ugo'.

   The OPERATION part tells how to change the affected users' access to
the file, and is one of the following symbols:

`+'
     to add the PERMISSIONS to whatever permissions the USERS already
     have for the file;

`-'
     to remove the PERMISSIONS from whatever permissions the USERS
     already have for the file;

`='
     to make the PERMISSIONS the only permissions that the USERS have
     for the file.

   The PERMISSIONS part tells what kind of access to the file should be
changed; it is zero or more of the following letters.  As with the
USERS part, the order does not matter when more than one letter is
given.  Omitting the PERMISSIONS part is useful only with the `='
operation, where it gives the specified USERS no access at all to the
file.

`r'
     the permission the USERS have to read the file;

`w'
     the permission the USERS have to write to the file;

`x'
     the permission the USERS have to execute the file.

   For example, to give everyone permission to read and write a file,
but not to execute it, use:

     a=rw

   To remove write permission for from all users other than the file's
owner, use:

     go-w

The above command does not affect the access that the owner of the file
has to it, nor does it affect whether other users can read or execute
the file.

   To give everyone except a file's owner no permission to do anything
with that file, use the mode below.  Other users could still remove the
file, if they have write permission on the directory it is in.

     go=

Another way to specify the same thing is:

     og-rxw

\x1f
File: find.info,  Node: Copying Permissions,  Next: Changing Special Permissions,  Prev: Setting Permissions,  Up: Symbolic Modes

Copying Existing Permissions
----------------------------

   You can base part of a file's permissions on part of its existing
permissions.  To do this, instead of using `r', `w', or `x' after the
operator, you use the letter `u', `g', or `o'.  For example, the mode

     o+g

adds the permissions for users who are in a file's group to the
permissions that other users have for the file.  Thus, if the file
started out as mode 664 (`rw-rw-r--'), the above mode would change it
to mode 666 (`rw-rw-rw-').  If the file had started out as mode 741
(`rwxr----x'), the above mode would change it to mode 745
(`rwxr--r-x').  The `-' and `=' operations work analogously.

\x1f
File: find.info,  Node: Changing Special Permissions,  Next: Conditional Executability,  Prev: Copying Permissions,  Up: Symbolic Modes

Changing Special Permissions
----------------------------

   In addition to changing a file's read, write, and execute
permissions, you can change its special permissions.  *Note Mode
Structure::, for a summary of these permissions.

   To change a file's permission to set the user ID on execution, use
`u' in the USERS part of the symbolic mode and `s' in the PERMISSIONS
part.

   To change a file's permission to set the group ID on execution, use
`g' in the USERS part of the symbolic mode and `s' in the PERMISSIONS
part.

   To change a file's permission to stay permanently on the swap device,
use `o' in the USERS part of the symbolic mode and `t' in the
PERMISSIONS part.

   For example, to add set user ID permission to a program, you can use
the mode:

     u+s

   To remove both set user ID and set group ID permission from it, you
can use the mode:

     ug-s

   To cause a program to be saved on the swap device, you can use the
mode:

     o+t

   Remember that the special permissions only affect files that are
executable, plus, on some systems, directories (on which they have
different meanings; *note Mode Structure::.).  Using `a' in the USERS
part of a symbolic mode does not cause the special permissions to be
affected; thus,

     a+s

has *no effect*.  You must use `u', `g', and `o' explicitly to affect
the special permissions.  Also, the combinations `u+t', `g+t', and
`o+s' have no effect.

   The `=' operator is not very useful with special permissions; for
example, the mode:

     o=t

does cause the file to be saved on the swap device, but it also removes
all read, write, and execute permissions that users not in the file's
group might have had for it.

\x1f
File: find.info,  Node: Conditional Executability,  Next: Multiple Changes,  Prev: Changing Special Permissions,  Up: Symbolic Modes

Conditional Executability
-------------------------

   There is one more special type of symbolic permission: if you use
`X' instead of `x', execute permission is affected only if the file
already had execute permission or is a directory.  It affects
directories' execute permission even if they did not initially have any
execute permissions set.

   For example, this mode:

     a+X

gives all users permission to execute files (or search directories) if
anyone could before.

\x1f
File: find.info,  Node: Multiple Changes,  Next: Umask and Protection,  Prev: Conditional Executability,  Up: Symbolic Modes

Making Multiple Changes
-----------------------

   The format of symbolic modes is actually more complex than described
above (*note Setting Permissions::.).  It provides two ways to make
multiple changes to files' permissions.

   The first way is to specify multiple OPERATION and PERMISSIONS parts
after a USERS part in the symbolic mode.

   For example, the mode:

     og+rX-w

gives users other than the owner of the file read permission and, if it
is a directory or if someone already had execute permission to it,
gives them execute permission; and it also denies them write permission
to it file.  It does not affect the permission that the owner of the
file has for it.  The above mode is equivalent to the two modes:

     og+rX
     og-w

   The second way to make multiple changes is to specify more than one
simple symbolic mode, separated by commas.  For example, the mode:

     a+r,go-w

gives everyone permission to read the file and removes write permission
on it for all users except its owner.  Another example:

     u=rwx,g=rx,o=

sets all of the non-special permissions for the file explicitly.  (It
gives users who are not in the file's group no permission at all for
it.)

   The two methods can be combined.  The mode:

     a+r,g+x-w

gives all users permission to read the file, and gives users who are in
the file's group permission to execute it, as well, but not permission
to write to it.  The above mode could be written in several different
ways; another is:

     u+r,g+rx,o+r,g-w

\x1f
File: find.info,  Node: Umask and Protection,  Prev: Multiple Changes,  Up: Symbolic Modes

The Umask and Protection
------------------------

   If the USERS part of a symbolic mode is omitted, it defaults to `a'
(affect all users), except that any permissions that are *set* in the
system variable `umask' are *not affected*.  The value of `umask' can
be set using the `umask' command.  Its default value varies from system
to system.

   Omitting the USERS part of a symbolic mode is generally not useful
with operations other than `+'.  It is useful with `+' because it
allows you to use `umask' as an easily customizable protection against
giving away more permission to files than you intended to.

   As an example, if `umask' has the value 2, which removes write
permission for users who are not in the file's group, then the mode:

     +w

adds permission to write to the file to its owner and to other users who
are in the file's group, but *not* to other users.  In contrast, the
mode:

     a+w

ignores `umask', and *does* give write permission for the file to all
users.

\x1f
File: find.info,  Node: Numeric Modes,  Prev: Symbolic Modes,  Up: File Permissions

Numeric Modes
=============

   File permissions are stored internally as 16 bit integers.  As an
alternative to giving a symbolic mode, you can give an octal (base 8)
number that corresponds to the internal representation of the new mode.
This number is always interpreted in octal; you do not have to add a
leading 0, as you do in C.  Mode 0055 is the same as mode 55.

   A numeric mode is usually shorter than the corresponding symbolic
mode, but it is limited in that it can not take into account a file's
previous permissions; it can only set them absolutely.

   The permissions granted to the user, to other users in the file's
group, and to other users not in the file's group are each stored as
three bits, which are represented as one octal digit.  The three special
permissions are also each stored as one bit, and they are as a group
represented as another octal digit.  Here is how the bits are arranged
in the 16 bit integer, starting with the lowest valued bit:

     Value in  Corresponding
     Mode      Permission
     
               Other users not in the file's group:
        1      Execute
        2      Write
        4      Read
     
               Other users in the file's group:
       10      Execute
       20      Write
       40      Read
     
               The file's owner:
      100      Execute
      200      Write
      400      Read
     
               Special permissions:
     1000      Save text image on swap device
     2000      Set group ID on execution
     4000      Set user ID on execution

   For example, numeric mode 4755 corresponds to symbolic mode
`u=rwxs,go=rx', and numeric mode 664 corresponds to symbolic mode
`ug=rw,o=r'.  Numeric mode 0 corresponds to symbolic mode `ugo='.

\x1f
File: find.info,  Node: Reference,  Next: Primary Index,  Prev: File Permissions,  Up: Top

Reference
*********

   Below are summaries of the command line syntax for the programs
discussed in this manual.

* Menu:

* Invoking find::
* Invoking locate::
* Invoking updatedb::
* Invoking xargs::

\x1f
File: find.info,  Node: Invoking find,  Next: Invoking locate,  Up: Reference

Invoking `find'
===============

     find [FILE...] [EXPRESSION]

   `find' searches the directory tree rooted at each file name FILE by
evaluating the EXPRESSION on each file it finds in the tree.

   `find' considers the first argument that begins with `-', `(', `)',
`,', or `!' to be the beginning of the expression; any arguments before
it are paths to search, and any arguments after it are the rest of the
expression.  If no paths are given, the current directory is used.  If
no expression is given, the expression `-print' is used.

   `find' exits with status 0 if all files are processed successfully,
greater than 0 if errors occur.

   *Note Primary Index::, for a summary of all of the tests, actions,
and options that the expression can contain.

   `find' also recognizes two options for administrative use:

`--help'
     Print a summary of the command-line argument format and exit.

`--version'
     Print the version number of `find' and exit.

\x1f
File: find.info,  Node: Invoking locate,  Next: Invoking updatedb,  Prev: Invoking find,  Up: Reference

Invoking `locate'
=================

     locate [OPTION...] PATTERN...

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

`--existing'
`-e'
     Only print out such names that currently exist (instead of such
     names that existed when the database was created).  Note that this
     may slow down the program a lot, if there are many matches in the
     database.

`--help'
     Print a summary of the options to `locate' and exit.

`--version'
     Print the version number of `locate' and exit.

\x1f
File: find.info,  Node: Invoking updatedb,  Next: Invoking xargs,  Prev: Invoking locate,  Up: Reference

Invoking `updatedb'
===================

     updatedb [OPTION...]

`--localpaths='PATH...''
     Non-network directories to put in the database.  Default is `/'.

`--netpaths='PATH...''
     Network (NFS, AFS, RFS, etc.) directories to put in the database.
     The environment variable `NETPATHS' also sets this value.  Default
     is none.

`--prunepaths='PATH...''
     Directories to not put in the database, which would otherwise be.
     The environment variable `PRUNEPATHS' also sets this value.
     Default is `/tmp /usr/tmp /var/tmp /afs'.

`--prunefs='PATH...''
     File systems to not put in the database, which would otherwise be.
     Note that files are pruned when a file system is reached; Any file
     system mounted under an undesired file system will be ignored.
     The environment variable `PRUNEFS' also sets this value.  Default
     is `nfs NFS proc'.

`--output=DBFILE'
     The database file to build.  Default is system-dependent, but
     typically `/usr/local/var/locatedb'.

`--localuser=USER'
     The user to search the non-network directories as, using `su'.
     Default is to search the non-network directories as the current
     user.  You can also use the environment variable `LOCALUSER' to
     set this user.

`--netuser=USER'
     The user to search network directories as, using `su'(1).  Default
     is `daemon'.  You can also use the environment variable `NETUSER'
     to set this user.

\x1f
File: find.info,  Node: Invoking xargs,  Prev: Invoking updatedb,  Up: Reference

Invoking `xargs'
================

     xargs [OPTION...] [COMMAND [INITIAL-ARGUMENTS]]

   `xargs' exits with the following status:

0
     if it succeeds

123
     if any invocation of the command exited with status 1-125

124
     if the command exited with status 255

125
     if the command is killed by a signal

126
     if the command cannot be run

127
     if the command is not found

1
     if some other error occurred.

`--null'
`-0'
     Input filenames are terminated by a null character instead of by
     whitespace, and the quotes and backslash are not special (every
     character is taken literally).  Disables the end of file string,
     which is treated like any other argument.

`--eof[=EOF-STR]'
`-e[EOF-STR]'
     Set the end of file string to EOF-STR.  If the end of file string
     occurs as a line of input, the rest of the input is ignored.  If
     EOF-STR is omitted, there is no end of file string.  If this
     option is not given, the end of file string defaults to `_'.

`--help'
     Print a summary of the options to `xargs' and exit.

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

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

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

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

`--verbose'
`-t'
     Print the command line on the standard error output before
     executing it.

`--version'
     Print the version number of `xargs' and exit.

`--exit'
`-x'
     Exit if the size (see the -S option) is exceeded.

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

\x1f
File: find.info,  Node: Primary Index,  Prev: Reference,  Up: Top

`find' Primary Index
********************

   This is a list of all of the primaries (tests, actions, and options)
that make up `find' expressions for selecting files.  *Note find
Expressions::, for more information on expressions.

* Menu:

* -amin:                                 Age Ranges.
* -anewer:                               Comparing Timestamps.
* -atime:                                Age Ranges.
* -cmin:                                 Age Ranges.
* -cnewer:                               Comparing Timestamps.
* -ctime:                                Age Ranges.
* -daystart:                             Age Ranges.
* -depth:                                Directories.
* -empty:                                Size.
* -exec:                                 Single File.
* -false:                                Combining Primaries With Operators.
* -fls:                                  Print File Information.
* -follow:                               Symbolic Links.
* -fprint:                               Print File Name.
* -fprint0:                              Safe File Name Handling.
* -fprintf:                              Print File Information.
* -fstype:                               Filesystems.
* -gid:                                  Owner.
* -group:                                Owner.
* -ilname:                               Symbolic Links.
* -iname:                                Base Name Patterns.
* -inum:                                 Hard Links.
* -ipath:                                Full Name Patterns.
* -iregex:                               Full Name Patterns.
* -links:                                Hard Links.
* -lname:                                Symbolic Links.
* -ls:                                   Print File Information.
* -maxdepth:                             Directories.
* -mindepth:                             Directories.
* -mmin:                                 Age Ranges.
* -mount:                                Filesystems.
* -mtime:                                Age Ranges.
* -name:                                 Base Name Patterns.
* -newer:                                Comparing Timestamps.
* -nogroup:                              Owner.
* -noleaf:                               Directories.
* -nouser:                               Owner.
* -ok:                                   Querying.
* -path:                                 Full Name Patterns.
* -perm:                                 Permissions.
* -print:                                Print File Name.
* -print0:                               Safe File Name Handling.
* -printf:                               Print File Information.
* -prune:                                Directories.
* -regex:                                Full Name Patterns.
* -size:                                 Size.
* -true:                                 Combining Primaries With Operators.
* -type:                                 Type.
* -uid:                                  Owner.
* -used:                                 Comparing Timestamps.
* -user:                                 Owner.
* -xdev:                                 Filesystems.
* -xtype:                                Type.