1 --- findutils-4.2.27/doc/find.texi.orig 2005-12-05 08:35:33.000000000 +0100
2 +++ findutils-4.2.27/doc/find.texi 2006-02-05 22:46:45.723352000 +0100
8 +@dircategory Shell utilities:
10 -* Finding files: (find). Operating on files matching certain criteria.
13 -@dircategory Individual utilities
15 -* find: (find)Invoking find. Finding and acting on files.
16 -* locate: (find)Invoking locate. Finding files in a database.
17 -* updatedb: (find)Invoking updatedb. Building the locate database.
18 -* xargs: (find)Invoking xargs. Operating on many files.
19 +* Finding files: (find). Operating on files matching certain criteria
20 +* find: (find)find. Finding and acting on files
21 +* xargs: (find)xargs. Operating on many files
25 @@ -2390,10 +2384,6 @@
26 fileserver where that filesystem is on a local disk, to prevent
27 thrashing the network.
29 -@xref{Invoking updatedb},
30 -for the description of the options to @code{updatedb}, which specify
31 -which directories would each database contain entries for.
34 @node Database Formats
35 @section Database Formats
36 @@ -2569,15 +2559,13 @@
37 discussed in this manual.
42 -* Invoking updatedb::
46 * Regular Expressions::
47 * Environment Variables::
50 -@node Invoking find, Invoking locate, , Reference
51 +@node find, xargs, , Reference
52 @section Invoking @code{find}
59 -@node Warning Messages,,, Invoking find
60 +@node Warning Messages,,, find
61 @subsection Warning Messages
63 If there is an error on the @code{find} command line, an error message
64 @@ -2700,247 +2688,7 @@
65 Use of an unrecognised formatting directive with @samp{-fprintf}
68 -@node Invoking locate, Invoking updatedb, Invoking find, Reference
69 -@section Invoking @code{locate}
72 -locate @r{[}@var{option}@dots{}@r{]} @var{pattern}@dots{}
75 -For each @var{pattern} given @code{locate} searches one or more file
76 -name databases returning each match of @var{pattern}.
78 -For each @var{pattern} given @code{locate} searches one or more file
79 -name databases returning each match of @var{pattern}.
84 -Print only names which match all non-option arguments, not those
85 -matching one or more non-option arguments.
89 -The specified pattern is matched against just the last component of
90 -the name of a file in the @code{locate} database. This last
91 -component is also called the ``base name''. For example, the base
92 -name of @file{/tmp/mystuff/foo.old.c} is @file{foo.old.c}. If the
93 -pattern contains metacharacters, it must match the base name exactly.
94 -If not, it must match part of the base name.
98 -Instead of printing the matched file names, just print the total
99 -number of matches found, unless @samp{--print} (@samp{-p}) is also
103 -@item --database=@var{path}
104 -@itemx -d @var{path}
105 -Instead of searching the default @code{locate} database, @code{locate} search the file
106 -name databases in @var{path}, which is a colon-separated list of
107 -database file names. You can also use the environment variable
108 -@code{LOCATE_PATH} to set the list of database files to search. The
109 -option overrides the environment variable if both are used. Empty
110 -elements in @var{path} (that is, a leading or trailing colon, or two
111 -colons in a row) are taken to stand for the default database.
112 -A database can be supplied on stdin, using @samp{-} as an element
113 -of @samp{path}. If more than one element of @samp{path} is @samp{-},
114 -later instances are ignored (but a warning message is printed).
118 -Only print out such names which currently exist (instead of such names
119 -which existed when the database was created). Note that this may slow
120 -down the program a lot, if there are many matches in the database.
121 -The way in which broken symbolic links are treated is affected by the
122 -@samp{-L}, @samp{-P} and @samp{-H} options. Please note that it is
123 -possible for the file to be deleted after @code{locate} has checked
124 -that it exists, but before you use it.
126 -@item --non-existing
128 -Only print out such names which currently do not exist (instead of
129 -such names which existed when the database was created). Note that
130 -this may slow down the program a lot, if there are many matches in the
131 -database. The way in which broken symbolic links are treated is
132 -affected by the @samp{-L}, @samp{-P} and @samp{-H} options. Please
133 -note that @code{locate} checks that the file does not exist, but a
134 -file of the same name might be created after @code{locate}'s check but
135 -before you read @code{locate}'s output.
139 -If testing for the existence of files (with the @samp{-e} or @samp{-E}
140 -options), consider broken symbolic links to be non-existing. This is
141 -the default behaviour.
146 -If testing for the existence of files (with the @samp{-e} or @samp{-E}
147 -options), treat broken symbolic links as if they were existing files.
148 -The @samp{-H} form of this option is provided purely for similarity
149 -with @code{find}; the use of @samp{-P} is recommended over @samp{-H}.
153 -Ignore case distinctions in both the pattern and the file names.
157 -Limit the number of results printed to N. When used with the
158 -@samp{--count} option, the value printed will never be larger than
163 -Accepted but does nothing. The option is supported only to provide
164 -compatibility with BSD's @code{locate}.
168 -Results are separated with the ASCII NUL character rather than the
169 -newline character. To get the full benefit of the use of this option,
170 -use the new @code{locate} database format (that is the default
175 -Print search results when they normally would not, because of the
176 -presence of @samp{--statistics} (@samp{-S}) or @samp{--count}
181 -The specified pattern is matched against the whole name of the file in
182 -the @code{locate} database. If the pattern contains metacharacters,
183 -it must match exactly. If not, it must match part of the whole file
184 -name. This is the default behaviour.
188 -Instead of using substring or shell glob matching, the pattern
189 -specified on the command line is understood to be a regular
190 -expression. GNU Emacs-style regular expressions are assumed unless
191 -the @samp{--regextype} option is also given. File names from the
192 -@code{locate} database are matched using the specified regular
193 -expression. If the @samp{-i} flag is also given, matching is
194 -case-insensitive. Matches are performed against the whole path name,
195 -and so by default a pathname will be matched if any part of it matches
196 -the specified regular expression. The regular expression may use
197 -@samp{^} or @samp{$} to anchor a match at the beginning or end of a
201 -This option changes the regular expression syntax and behaviour used
202 -by the @samp{--regex} option. @ref{Regular Expressions} for more
203 -information on the regular expression dialects understood by GNU
208 -Accepted but does nothing. The option is supported only to provide
209 -compatibility with BSD's @code{locate}.
213 -Print some summary information for each @code{locate} database. No
214 -search is performed unless non-option arguments are given.
217 -Print a summary of the command line usage for @code{locate} and exit.
220 -Print the version number of @code{locate} and exit.
223 -@node Invoking updatedb, Invoking xargs, Invoking locate, Reference
224 -@section Invoking @code{updatedb}
227 -updatedb @r{[}@var{option}@dots{}@r{]}
230 -@code{updatedb} creates and updates the database of file names used by
231 -@code{locate}. @code{updatedb} generates a list of files similar to
232 -the output of @code{find} and then uses utilities for optimizing the
233 -database for performance. @code{updatedb} is often run periodically
234 -as a @code{cron} job and configured with environment variables or
235 -command options. Typically, operating systems have a shell script
236 -that ``exports'' configurations for variable definitions and uses
237 -another schell script that ``sources'' the configuration file into the
238 -environment and then executes @code{updatedb} in the environment.
240 -@code{updatedb} creates and updates the database of file names used by
241 -@code{locate}. @code{updatedb} generates a list of files similar to
242 -the output of @code{find} and then uses utilities for optimizing the
243 -database for performance. @code{updatedb} is often run periodically
244 -as a @code{cron} job and configured with environment variables or
245 -command options. Typically, operating systems have a shell script
246 -that ``exports'' configurations for variable definitions and uses
247 -another schell script that ``sources'' the configuration file into the
248 -environment and then executes @code{updatedb} in the environment.
251 -@item --findoptions='@var{OPTION}@dots{}'
252 -Global options to pass on to @code{find}.
253 -The environment variable @code{FINDOPTIONS} also sets this value.
256 -@item --localpaths='@var{path}@dots{}'
257 -Non-network directories to put in the database.
258 -Default is @file{/}.
260 -@item --netpaths='@var{path}@dots{}'
261 -Network (NFS, AFS, RFS, etc.) directories to put in the database.
262 -The environment variable @code{NETPATHS} also sets this value.
265 -@item --prunepaths='@var{path}@dots{}'
266 -Directories to omit from the database, which would otherwise be
267 -included. The environment variable @code{PRUNEPATHS} also sets this
268 -value. Default is @file{/tmp /usr/tmp /var/tmp /afs}. The paths are
269 -used as regular expressions (with @code{find ... -regex}, so you need
270 -to specify these paths in the same way that @code{find} will encounter
271 -them. This means for example that the paths must not include trailing
274 -@item --prunefs='@var{path}@dots{}'
275 -Filesystems to omit from the database, which would otherwise be
276 -included. Note that files are pruned when a filesystem is reached;
277 -Any filesystem mounted under an undesired filesystem will be ignored.
278 -The environment variable @code{PRUNEFS} also sets this value. Default
279 -is @file{nfs NFS proc}.
281 -@item --output=@var{dbfile}
282 -The database file to build. Default is system-dependent, but
283 -typically @file{/usr/local/var/locatedb}.
285 -@item --localuser=@var{user}
286 -The user to search the non-network directories as, using @code{su}.
287 -Default is to search the non-network directories as the current user.
288 -You can also use the environment variable @code{LOCALUSER} to set this user.
290 -@item --netuser=@var{user}
291 -The user to search network directories as, using @code{su}. Default
292 -@code{user} is @code{daemon}. You can also use the environment variable
293 -@code{NETUSER} to set this user.
296 -Generate a @code{locate} database in the old format, for compatibility
297 -with versions of @code{locate} other than GNU @code{locate}. Using
298 -this option means that @code{locate} will not be able to properly
299 -handle non-ASCII characters in file names (that is, file names
300 -containing characters which have the eighth bit set, such as many of
301 -the characters from the ISO-8859-1 character set).
303 -Print a summary of the command line usage and exit.
305 -Print the version number of @code{updatedb} and exit.
308 -@node Invoking xargs, Regular Expressions, Invoking updatedb, Reference
309 +@node xargs, Regular Expressions, find, Reference
310 @section Invoking @code{xargs}
313 @@ -3089,7 +2837,7 @@
317 -@node Regular Expressions, Environment Variables, Invoking xargs, Reference
318 +@node Regular Expressions, Environment Variables, xargs, Reference
319 @section Regular Expressions
321 The @samp{-regex} and @samp{-iregex} tests of @code{find} allow