---- findutils-4.4.0/doc/find.texi.orig 2008-03-10 21:31:16.000000000 +0100
-+++ findutils-4.4.0/doc/find.texi 2008-03-16 00:00:13.875930612 +0100
-@@ -7,23 +7,16 @@
- @c %**end of header
-
- @include version.texi
--@include ../locate/dblocation.texi
-
- @iftex
- @finalout
- @end iftex
-
--@dircategory Basics
-+@dircategory Shell utilities:
- @direntry
--* Finding files: (find). Operating on files matching certain criteria.
--@end direntry
--
--@dircategory Individual utilities
--@direntry
--* find: (find)Invoking find. Finding and acting on files.
--* locate: (find)Invoking locate. Finding files in a database.
--* updatedb: (find)Invoking updatedb. Building the locate database.
--* xargs: (find)Invoking xargs. Operating on many files.
-+* Finding files: (find). Operating on files matching certain criteria
-+* find: (find)find. Finding and acting on files
-+* xargs: (find)xargs. Operating on many files
- @end direntry
-
- @copying
-@@ -225,9 +218,7 @@
- @section Overview
-
- The principal programs used for making lists of files that match given
--criteria and running commands on them are @code{find}, @code{locate},
--and @code{xargs}. An additional command, @code{updatedb}, is used by
--system administrators to create databases for @code{locate} to use.
-+criteria and running commands on them are @code{find} and @code{xargs}.
-
- @code{find} searches for files in a directory hierarchy and prints
- information about the files it found. It is run like this:
-@@ -247,23 +238,6 @@
- Notice that the wildcard must be enclosed in quotes in order to
- protect it from expansion by the shell.
-
--@code{locate} searches special file name databases for file names that
--match patterns. The system administrator runs the @code{updatedb}
--program to create the databases. @code{locate} is run like this:
--
--@example
--locate @r{[}@var{option}@dots{}@r{]} @var{pattern}@dots{}
--@end example
--
--@noindent
--This example prints the names of all files in the default file name
--database whose name ends with @samp{Makefile} or @samp{makefile}.
--Which file names are stored in the database depends on how the system
--administrator ran @code{updatedb}.
--@example
--locate '*[Mm]akefile'
--@end example
--
- The name @code{xargs}, pronounced EX-args, means ``combine
- arguments.'' @code{xargs} builds and executes command lines by
- gathering together arguments it reads on the standard input. Most
-@@ -371,7 +345,6 @@
- @menu
- * Base Name Patterns::
- * Full Name Patterns::
--* Fast Full Name Search::
- * Shell Pattern Matching:: Wildcards used by these programs.
- @end menu
-
-@@ -504,78 +477,6 @@
-
- @end deffn
-
--@node Fast Full Name Search
--@subsection 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
--@code{locate} program. For each shell pattern you give it,
--@code{locate} searches one or more databases of file names and
--displays the file names that contain the pattern. @xref{Shell Pattern
--Matching}, for details about shell patterns.
--
--If a pattern is a plain string---it contains no
--metacharacters---@code{locate} displays all file names in the database
--that contain that string. If a pattern contains
--metacharacters, @code{locate} only displays file names that match the
--pattern exactly. As a result, patterns that contain metacharacters
--should usually begin with a @samp{*}, 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.
--
--If you only want @code{locate} to match against the last component of
--the file names (the ``base name'' of the files) you can use the
--@samp{--basename} option. The opposite behaviour is the default, but
--can be selected explicitly by using the option @samp{--wholename}.
--
--The command
--@example
--locate @var{pattern}
--@end example
--
--is almost equivalent to
--@example
--find @var{directories} -name @var{pattern}
--@end example
--
--where @var{directories} are the directories for which the file name
--databases contain information. The differences are that the
--@code{locate} information might be out of date, and that @code{locate}
--handles wildcards in the pattern slightly differently than @code{find}
--(@pxref{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 @code{locate}
--searches. The default is system-dependent. At the time this document
--was generated, the default was @file{@value{LOCATE_DB}}.
--
--@table @code
--@item --database=@var{path}
--@itemx -d @var{path}
--Instead of searching the default file name database, search the file
--name databases in @var{path}, which is a colon-separated list of
--database file names. You can also use the environment variable
--@code{LOCATE_PATH} to set the list of database files to search. The
--option overrides the environment variable if both are used.
--@end table
--
--GNU @code{locate} can read file name databases generated by the
--@code{slocate} package. However, these generally contain a list of
--all the files on the system, and so when using this database,
--@code{locate} will produce output only for files which are accessible
--to you. @xref{Invoking locate}, for a description of the
--@samp{--existing} option which is used to do this.
--
--The @code{updatedb} program can also generate database in a format
--compatible with @code{slocate}. @xref{Invoking updatedb}, for a
--description of its @samp{--dbformat} and @samp{--output} options.
--
--
- @node Shell Pattern Matching
- @subsection Shell Pattern Matching
-
-@@ -2650,42 +2551,11 @@
- @samp{locate --statistics}.
-
- @menu
--* Database Locations::
- * Database Formats::
- * Newline Handling::
- @end menu
-
-
--@node Database Locations
--@section Database Locations
--
--There can be multiple file name databases. Users can select which
--databases @code{locate} searches using the @code{LOCATE_PATH}
--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 @code{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. @code{updatedb} is then run for each filesystem on the
--fileserver where that filesystem is on a local disk, to prevent
--thrashing the network.
--
--@xref{Invoking updatedb}, for the description of the options to
--@code{updatedb}. These options can be used to specify which
--directories are indexed by each database file.
--
--The default location for the locate database depends on how findutils
--is built, but the findutils installation accompanying this manual uses
--the default location @file{@value{LOCATE_DB}}.
--
--If no database exists at @file{@value{LOCATE_DB}} but the user did not
--specify where to look (by using @samp{-d} or setting
--@code{LOCATE_PATH}), then @code{locate} will also check for a
--``secure'' database in @file{/var/lib/slocate/slocate.db}.
--
- @node Database Formats
- @section Database Formats
-
-@@ -2904,15 +2774,13 @@
- discussed in this manual.
-
- @menu
--* Invoking find::
--* Invoking locate::
--* Invoking updatedb::
--* Invoking xargs::
-+* find::
-+* xargs::
- * Regular Expressions::
- * Environment Variables::
- @end menu
-
--@node Invoking find
-+@node find
- @section Invoking @code{find}
-
- @example
-@@ -3120,268 +2988,7 @@
- actions, and options that the expression can contain. If the
- expression is missing, @samp{-print} is assumed.
-
--@node Invoking locate
--@section Invoking @code{locate}
--
--@example
--locate @r{[}@var{option}@dots{}@r{]} @var{pattern}@dots{}
--@end example
--
--For each @var{pattern} given @code{locate} searches one or more file
--name databases returning each match of @var{pattern}.
--
--For each @var{pattern} given @code{locate} searches one or more file
--name databases returning each match of @var{pattern}.
--
--@table @code
--@item --all
--@itemx -A
--Print only names which match all non-option arguments, not those
--matching one or more non-option arguments.
--
--@item --basename
--@itemx -b
--The specified pattern is matched against just the last component of
--the name of a file in the @code{locate} database. This last
--component is also called the ``base name''. For example, the base
--name of @file{/tmp/mystuff/foo.old.c} is @file{foo.old.c}. If the
--pattern contains metacharacters, it must match the base name exactly.
--If not, it must match part of the base name.
--
--@item --count
--@itemx -c
--Instead of printing the matched file names, just print the total
--number of matches found, unless @samp{--print} (@samp{-p}) is also
--present.
--
--
--@item --database=@var{path}
--@itemx -d @var{path}
--Instead of searching the default @code{locate} database
--@file{@value{LOCATE_DB}}, @code{locate} searches the file
--name databases in @var{path}, which is a colon-separated list of
--database file names. You can also use the environment variable
--@code{LOCATE_PATH} to set the list of database files to search. The
--option overrides the environment variable if both are used. Empty
--elements in @var{path} (that is, a leading or trailing colon, or two
--colons in a row) are taken to stand for the default database.
--A database can be supplied on stdin, using @samp{-} as an element
--of @samp{path}. If more than one element of @samp{path} is @samp{-},
--later instances are ignored (but a warning message is printed).
--
--@item --existing
--@itemx -e
--Only print out such names which currently exist (instead of such names
--which existed when the database was created). Note that this may slow
--down the program a lot, if there are many matches in the database.
--The way in which broken symbolic links are treated is affected by the
--@samp{-L}, @samp{-P} and @samp{-H} options. Please note that it is
--possible for the file to be deleted after @code{locate} has checked
--that it exists, but before you use it. This option is automatically
--turned on when reading an @code{slocate} database in secure mode
--(@pxref{slocate Database Format}).
--
--@item --non-existing
--@itemx -E
--Only print out such names which currently do not exist (instead of
--such names which existed when the database was created). Note that
--this may slow down the program a lot, if there are many matches in the
--database. The way in which broken symbolic links are treated is
--affected by the @samp{-L}, @samp{-P} and @samp{-H} options. Please
--note that @code{locate} checks that the file does not exist, but a
--file of the same name might be created after @code{locate}'s check but
--before you read @code{locate}'s output.
--
--@item --follow
--@itemx -L
--If testing for the existence of files (with the @samp{-e} or @samp{-E}
--options), consider broken symbolic links to be non-existing. This is
--the default behaviour.
--
--@item --nofollow
--@itemx -P
--@itemx -H
--If testing for the existence of files (with the @samp{-e} or @samp{-E}
--options), treat broken symbolic links as if they were existing files.
--The @samp{-H} form of this option is provided purely for similarity
--with @code{find}; the use of @samp{-P} is recommended over @samp{-H}.
--
--@item --ignore-case
--@itemx -i
--Ignore case distinctions in both the pattern and the file names.
--
--@item --limit=N
--@itemx -l N
--Limit the number of results printed to N. When used with the
--@samp{--count} option, the value printed will never be larger than
--this limit.
--@item --max-database-age=D
--Normally, @code{locate} will issue a warning message when it searches
--a database which is more than 8 days old. This option changes that
--value to something other than 8. The effect of specifying a negative
--value is undefined.
--@item --mmap
--@itemx -m
--Accepted but does nothing. The option is supported only to provide
--compatibility with BSD's @code{locate}.
--
--@item --null
--@itemx -0
--Results are separated with the ASCII NUL character rather than the
--newline character. To get the full benefit of this option,
--use the new @code{locate} database format (that is the default
--anyway).
--
--@item --print
--@itemx -p
--Print search results when they normally would not be due to
--use of @samp{--statistics} (@samp{-S}) or @samp{--count}
--(@samp{-c}).
--
--@item --wholename
--@itemx -w
--The specified pattern is matched against the whole name of the file in
--the @code{locate} database. If the pattern contains metacharacters,
--it must match exactly. If not, it must match part of the whole file
--name. This is the default behaviour.
--
--@item --regex
--@itemx -r
--Instead of using substring or shell glob matching, the pattern
--specified on the command line is understood to be a regular
--expression. GNU Emacs-style regular expressions are assumed unless
--the @samp{--regextype} option is also given. File names from the
--@code{locate} database are matched using the specified regular
--expression. If the @samp{-i} flag is also given, matching is
--case-insensitive. Matches are performed against the whole path name,
--and so by default a pathname will be matched if any part of it matches
--the specified regular expression. The regular expression may use
--@samp{^} or @samp{$} to anchor a match at the beginning or end of a
--pathname.
--
--@item --regextype
--This option changes the regular expression syntax and behaviour used
--by the @samp{--regex} option. @ref{Regular Expressions} for more
--information on the regular expression dialects understood by GNU
--findutils.
--
--@item --stdio
--@itemx -s
--Accepted but does nothing. The option is supported only to provide
--compatibility with BSD's @code{locate}.
--
--@item --statistics
--@itemx -S
--Print some summary information for each @code{locate} database. No
--search is performed unless non-option arguments are given.
--Although the BSD version of locate also has this option, the format of the
--output is different.
--
--@item --help
--Print a summary of the command line usage for @code{locate} and exit.
--
--@item --version
--Print the version number of @code{locate} and exit.
--@end table
--
--@node Invoking updatedb
--@section Invoking @code{updatedb}
--
--@example
--updatedb @r{[}@var{option}@dots{}@r{]}
--@end example
--
--@code{updatedb} creates and updates the database of file names used by
--@code{locate}. @code{updatedb} generates a list of files similar to
--the output of @code{find} and then uses utilities for optimizing the
--database for performance. @code{updatedb} is often run periodically
--as a @code{cron} job and configured with environment variables or
--command options. Typically, operating systems have a shell script
--that ``exports'' configurations for variable definitions and uses
--another shell script that ``sources'' the configuration file into the
--environment and then executes @code{updatedb} in the environment.
--
--@code{updatedb} creates and updates the database of file names used by
--@code{locate}. @code{updatedb} generates a list of files similar to
--the output of @code{find} and then uses utilities for optimizing the
--database for performance. @code{updatedb} is often run periodically
--as a @code{cron} job and configured with environment variables or
--command options. Typically, operating systems have a shell script
--that ``exports'' configurations for variable definitions and uses
--another shell script that ``sources'' the configuration file into the
--environment and then executes @code{updatedb} in the environment.
--
--@table @code
--@item --findoptions='@var{OPTION}@dots{}'
--Global options to pass on to @code{find}.
--The environment variable @code{FINDOPTIONS} also sets this value.
--Default is none.
--
--@item --localpaths='@var{path}@dots{}'
--Non-network directories to put in the database.
--Default is @file{/}.
--
--@item --netpaths='@var{path}@dots{}'
--Network (NFS, AFS, RFS, etc.) directories to put in the database.
--The environment variable @code{NETPATHS} also sets this value.
--Default is none.
--
--@item --prunepaths='@var{path}@dots{}'
--Directories to omit from the database, which would otherwise be
--included. The environment variable @code{PRUNEPATHS} also sets this
--value. Default is @file{/tmp /usr/tmp /var/tmp /afs}. The paths are
--used as regular expressions (with @code{find ... -regex}, so you need
--to specify these paths in the same way that @code{find} will encounter
--them. This means for example that the paths must not include trailing
--slashes.
--
--@item --prunefs='@var{path}@dots{}'
--Filesystems to omit from the database, which would otherwise be
--included. Note that files are pruned when a filesystem is reached;
--Any filesystem mounted under an undesired filesystem will be ignored.
--The environment variable @code{PRUNEFS} also sets this value. Default
--is @file{nfs NFS proc}.
--
--@item --output=@var{dbfile}
--The database file to build. The default is system-dependent, but
--when this document was formatted it was @file{@value{LOCATE_DB}}.
--
--@item --localuser=@var{user}
--The user to search the non-network directories as, using @code{su}.
--Default is to search the non-network directories as the current user.
--You can also use the environment variable @code{LOCALUSER} to set this user.
--
--@item --netuser=@var{user}
--The user to search network directories as, using @code{su}. Default
--@code{user} is @code{daemon}. You can also use the environment variable
--@code{NETUSER} to set this user.
--
--@item --old-format
--Generate a @code{locate} database in the old format, for compatibility
--with versions of @code{locate} other than GNU @code{locate}. Using
--this option means that @code{locate} will not be able to properly
--handle non-ASCII characters in file names (that is, file names
--containing characters which have the eighth bit set, such as many of
--the characters from the ISO-8859-1 character set). @xref{Database
--Formats}, for a detailed description of the supported database
--formats.
--
--@item --dbformat=@var{FORMAT}
--Generate the locate database in format @code{FORMAT}. Supported
--database formats include @code{LOCATE02} (which is the default),
--@code{old} and @code{slocate}. The @code{old} format exists for
--compatibility with implementations of @code{locate} on other Unix
--systems. The @code{slocate} format exists for compatibility with
--@code{slocate}. @xref{Database Formats}, for a detailed description
--of each format.
--
--@item --help
--Print a summary of the command line usage and exit.
--@item --version
--Print the version number of @code{updatedb} and exit.
--@end table
--
--@node Invoking xargs
-+@node xargs
- @section Invoking @code{xargs}
-
- @example
-@@ -5091,8 +4698,6 @@
- @menu
- * Error Messages From find::
- * Error Messages From xargs::
--* Error Messages From locate::
--* Error Messages From updatedb::
- @end menu
-
- @node Error Messages From find
-@@ -5223,38 +4828,6 @@
- See the description of the similar message for @code{find}.
- @end table
-
--@node Error Messages From locate
--@section Error Messages From @code{locate}
--
--@table @samp
--@item warning: database @file{@value{LOCATE_DB}} is more than 8 days old
--The @code{locate} program relies on a database which is periodically
--built by the @code{updatedb} program. That hasn't happened in a long
--time. To fix this problem, run @code{updatedb} manually. This can
--often happen on systems that are generally not left on, so the
--periodic ``cron'' task which normally does this doesn't get a chance
--to run.
--
--@item locate database @file{@value{LOCATE_DB}} is corrupt or invalid
--This should not happen. Re-run @code{updatedb}. If that works, but
--@code{locate} still produces this error, run @code{locate --version}
--and @code{updatedb --version}. These should produce the same output.
--If not, you are using a mixed toolset; check your @samp{$PATH}
--environment variable and your shell aliases (if you have any). If
--both programs claim to be GNU versions, this is a bug; all versions of
--these programs should interoperate without problem. Ask for help on
--@email{bug-findutils@@gnu.org}.
--@end table
--
--
--@node Error Messages From updatedb
--@section Error Messages From updatedb
--
--The @code{updatedb} program (and the programs it invokes) do issue
--error messages, but none seem to be candidates for guidance. If
--you are having a problem understanding one of these, ask for help on
--@email{bug-findutils@@gnu.org}.
--
- @node GNU Free Documentation License
- @appendix GNU Free Documentation License
- @include fdl.texi