---- findutils-4.2.32/doc/find.texi.orig 2007-12-08 17:00:30.000000000 +0100
-+++ findutils-4.2.32/doc/find.texi 2008-01-26 00:37:49.666750899 +0100
-@@ -12,17 +12,11 @@
+--- 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
@end direntry
@copying
-@@ -2406,10 +2400,6 @@
- fileserver where that filesystem is on a local disk, to prevent
- thrashing the network.
+@@ -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.
--@xref{Invoking updatedb},
--for the description of the options to @code{updatedb}, which specify
--which directories would each database contain entries for.
+-@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
-@@ -2590,15 +2580,13 @@
+
+@@ -2904,15 +2774,13 @@
discussed in this manual.
@menu
* Environment Variables::
@end menu
--@node Invoking find, Invoking locate, , Reference
-+@node find, xargs, , Reference
+-@node Invoking find
++@node find
@section Invoking @code{find}
@example
-@@ -2669,7 +2657,7 @@
- @end menu
-
+@@ -3120,268 +2988,7 @@
+ actions, and options that the expression can contain. If the
+ expression is missing, @samp{-print} is assumed.
--@node Warning Messages,,, Invoking find
-+@node Warning Messages,,, find
- @subsection Warning Messages
-
- If there is an error on the @code{find} command line, an error message
-@@ -2725,251 +2713,7 @@
- Use of an unrecognised formatting directive with @samp{-fprintf}
- @end itemize
-
--@node Invoking locate, Invoking updatedb, Invoking find, Reference
+-@node Invoking locate
-@section Invoking @code{locate}
-
-@example
-
-@item --database=@var{path}
-@itemx -d @var{path}
--Instead of searching the default @code{locate} database, @code{locate} search the file
+-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
-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.
+-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
-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
-@item --null
-@itemx -0
-Results are separated with the ASCII NUL character rather than the
--newline character. To get the full benefit of the use of this option,
+-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, because of the
--presence of @samp{--statistics} (@samp{-S}) or @samp{--count}
+-Print search results when they normally would not be due to
+-use of @samp{--statistics} (@samp{-S}) or @samp{--count}
-(@samp{-c}).
-
-@item --wholename
-@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
+-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 the version number of @code{locate} and exit.
-@end table
-
--@node Invoking updatedb, Invoking xargs, Invoking locate, Reference
+-@node Invoking updatedb
-@section Invoking @code{updatedb}
-
-@example
-is @file{nfs NFS proc}.
-
-@item --output=@var{dbfile}
--The database file to build. Default is system-dependent, but
--typically @file{/usr/local/var/locatedb}.
+-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}.
-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). Versions of
--@code{locate} prior to 4.2.31 fail to correctly handle long filenames
--in old-format databases. Versions 4.3.0 to 4.3.6 were also affected.
+-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, Regular Expressions, Invoking updatedb, Reference
-+@node xargs, Regular Expressions, find, Reference
+-@node Invoking xargs
++@node xargs
@section Invoking @code{xargs}
@example
-@@ -3118,7 +2862,7 @@
- @end table
-
+@@ -5091,8 +4698,6 @@
+ @menu
+ * Error Messages From find::
+ * Error Messages From xargs::
+-* Error Messages From locate::
+-* Error Messages From updatedb::
+ @end menu
--@node Regular Expressions, Environment Variables, Invoking xargs, Reference
-+@node Regular Expressions, Environment Variables, xargs, Reference
- @section Regular Expressions
+ @node Error Messages From find
+@@ -5223,38 +4828,6 @@
+ See the description of the similar message for @code{find}.
+ @end table
- The @samp{-regex} and @samp{-iregex} tests of @code{find} allow
+-@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
projects / packages / findutils.git / blobdiff