- unify ftp.gnu.org urls

[packages/findutils.git] / findutils-info.patch

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