]>
Commit | Line | Data |
---|---|---|
1a4e795f JB |
1 | --- findutils-4.7.0/doc/find.texi.orig 2019-06-23 11:00:40.000000000 +0200 |
2 | +++ findutils-4.7.0/doc/find.texi 2019-09-01 20:37:54.009605511 +0200 | |
a2caf129 | 3 | @@ -13,17 +13,11 @@ |
fe8a0ce5 JB |
4 | @finalout |
5 | @end iftex | |
6 | ||
7 | -@dircategory Basics | |
8 | +@dircategory Shell utilities: | |
9 | @direntry | |
10 | -* Finding files: (find). Operating on files matching certain criteria. | |
11 | -@end direntry | |
12 | - | |
13 | -@dircategory Individual utilities | |
14 | -@direntry | |
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 | |
22 | @end direntry | |
23 | ||
24 | @copying | |
1a4e795f | 25 | @@ -72,7 +66,6 @@ |
fe8a0ce5 JB |
26 | * Introduction:: Summary of the tasks this manual describes. |
27 | * Finding Files:: Finding files that match certain criteria. | |
28 | * Actions:: Doing things to files you have found. | |
29 | -* Databases:: Maintaining file name databases. | |
30 | * File Permissions:: How to control access to files. | |
31 | * Date input formats:: Specifying literal times. | |
a2caf129 | 32 | * Configuration:: Options you can select at compile time. |
1a4e795f | 33 | @@ -91,16 +84,14 @@ |
fe8a0ce5 JB |
34 | This manual shows how to find files that meet criteria you specify, |
35 | and how to perform various actions on the files that you find. The | |
36 | principal programs that you use to perform these tasks are | |
37 | -@code{find}, @code{locate}, and @code{xargs}. Some of the examples in | |
38 | +@code{find} and @code{xargs}. Some of the examples in | |
39 | this manual use capabilities specific to the GNU versions of those | |
40 | programs. | |
41 | ||
42 | GNU @code{find} was originally written by Eric Decker, with | |
43 | enhancements by David MacKenzie, Jay Plett, and Tim Wood. GNU | |
44 | @code{xargs} was originally written by Mike Rendell, with enhancements | |
45 | -by David MacKenzie. GNU @code{locate} and its associated utilities | |
46 | -were originally written by James Woods, with enhancements by David | |
47 | -MacKenzie. The idea for @samp{find -print0} and @samp{xargs -0} came | |
48 | +by David MacKenzie. The idea for @samp{find -print0} and @samp{xargs -0} came | |
49 | from Dan Bernstein. The current maintainer of GNU findutils (and this | |
50 | manual) is James Youngman. Many other people have contributed bug | |
51 | fixes, small improvements, and helpful suggestions. Thanks! | |
1a4e795f | 52 | @@ -126,7 +117,7 @@ |
fe8a0ce5 JB |
53 | |
54 | @itemize @bullet | |
55 | @item The version of the software you are running. You can find this | |
56 | -out by running @samp{locate --version}. | |
57 | +out by running @samp{find --version}. | |
58 | @item What you were trying to do | |
59 | @item The @emph{exact} command line you used | |
60 | @item The @emph{exact} output you got (if this is very long, try to | |
1a4e795f | 61 | @@ -225,9 +216,7 @@ |
fe8a0ce5 JB |
62 | @section Overview |
63 | ||
64 | The principal programs used for making lists of files that match given | |
65 | -criteria and running commands on them are @code{find}, @code{locate}, | |
66 | -and @code{xargs}. An additional command, @code{updatedb}, is used by | |
67 | -system administrators to create databases for @code{locate} to use. | |
68 | +criteria and running commands on them are @code{find} and @code{xargs}. | |
69 | ||
70 | @code{find} searches for files in a directory hierarchy and prints | |
71 | information about the files it found. It is run like this: | |
1a4e795f | 72 | @@ -247,23 +236,6 @@ |
fe8a0ce5 JB |
73 | Notice that the wildcard must be enclosed in quotes in order to |
74 | protect it from expansion by the shell. | |
75 | ||
76 | -@code{locate} searches special file name databases for file names that | |
77 | -match patterns. The system administrator runs the @code{updatedb} | |
78 | -program to create the databases. @code{locate} is run like this: | |
79 | - | |
80 | -@example | |
81 | -locate @r{[}@var{option}@dots{}@r{]} @var{pattern}@dots{} | |
82 | -@end example | |
83 | - | |
84 | -@noindent | |
85 | -This example prints the names of all files in the default file name | |
86 | -database whose name ends with @samp{Makefile} or @samp{makefile}. | |
87 | -Which file names are stored in the database depends on how the system | |
88 | -administrator ran @code{updatedb}. | |
89 | -@example | |
90 | -locate '*[Mm]akefile' | |
91 | -@end example | |
92 | - | |
93 | The name @code{xargs}, pronounced EX-args, means ``combine | |
94 | arguments.'' @code{xargs} builds and executes command lines by | |
95 | gathering together arguments it reads on the standard input. Most | |
1a4e795f | 96 | @@ -376,7 +348,6 @@ |
fe8a0ce5 JB |
97 | @menu |
98 | * Base Name Patterns:: | |
99 | * Full Name Patterns:: | |
100 | -* Fast Full Name Search:: | |
101 | * Shell Pattern Matching:: Wildcards used by these programs. | |
102 | @end menu | |
103 | ||
1a4e795f | 104 | @@ -528,82 +499,10 @@ |
fe8a0ce5 JB |
105 | |
106 | @end deffn | |
107 | ||
108 | -@node Fast Full Name Search | |
109 | -@subsection Fast Full Name Search | |
110 | - | |
111 | -To search for files by name without having to actually scan the | |
112 | -directories on the disk (which can be slow), you can use the | |
113 | -@code{locate} program. For each shell pattern you give it, | |
114 | -@code{locate} searches one or more databases of file names and | |
115 | -displays the file names that contain the pattern. @xref{Shell Pattern | |
116 | -Matching}, for details about shell patterns. | |
117 | - | |
a2caf129 JB |
118 | -If a pattern is a plain string -- it contains no |
119 | -metacharacters -- @code{locate} displays all file names in the database | |
fe8a0ce5 JB |
120 | -that contain that string. If a pattern contains |
121 | -metacharacters, @code{locate} only displays file names that match the | |
122 | -pattern exactly. As a result, patterns that contain metacharacters | |
123 | -should usually begin with a @samp{*}, and will most often end with one | |
124 | -as well. The exceptions are patterns that are intended to explicitly | |
125 | -match the beginning or end of a file name. | |
126 | - | |
127 | -If you only want @code{locate} to match against the last component of | |
128 | -the file names (the ``base name'' of the files) you can use the | |
129 | -@samp{--basename} option. The opposite behaviour is the default, but | |
130 | -can be selected explicitly by using the option @samp{--wholename}. | |
131 | - | |
132 | -The command | |
133 | -@example | |
134 | -locate @var{pattern} | |
135 | -@end example | |
136 | - | |
137 | -is almost equivalent to | |
138 | -@example | |
139 | -find @var{directories} -name @var{pattern} | |
140 | -@end example | |
141 | - | |
142 | -where @var{directories} are the directories for which the file name | |
143 | -databases contain information. The differences are that the | |
144 | -@code{locate} information might be out of date, and that @code{locate} | |
145 | -handles wildcards in the pattern slightly differently than @code{find} | |
146 | -(@pxref{Shell Pattern Matching}). | |
147 | - | |
148 | -The file name databases contain lists of files that were on the system | |
149 | -when the databases were last updated. The system administrator can | |
150 | -choose the file name of the default database, the frequency with which | |
151 | -the databases are updated, and the directories for which they contain | |
152 | -entries. | |
153 | - | |
154 | -Here is how to select which file name databases @code{locate} | |
155 | -searches. The default is system-dependent. At the time this document | |
156 | -was generated, the default was @file{@value{LOCATE_DB}}. | |
157 | - | |
158 | -@table @code | |
159 | -@item --database=@var{path} | |
160 | -@itemx -d @var{path} | |
161 | -Instead of searching the default file name database, search the file | |
162 | -name databases in @var{path}, which is a colon-separated list of | |
163 | -database file names. You can also use the environment variable | |
164 | -@code{LOCATE_PATH} to set the list of database files to search. The | |
165 | -option overrides the environment variable if both are used. | |
166 | -@end table | |
167 | - | |
168 | -GNU @code{locate} can read file name databases generated by the | |
169 | -@code{slocate} package. However, these generally contain a list of | |
170 | -all the files on the system, and so when using this database, | |
171 | -@code{locate} will produce output only for files which are accessible | |
172 | -to you. @xref{Invoking locate}, for a description of the | |
173 | -@samp{--existing} option which is used to do this. | |
174 | - | |
175 | -The @code{updatedb} program can also generate database in a format | |
176 | -compatible with @code{slocate}. @xref{Invoking updatedb}, for a | |
177 | -description of its @samp{--dbformat} and @samp{--output} options. | |
178 | - | |
a2caf129 | 179 | - |
fe8a0ce5 JB |
180 | @node Shell Pattern Matching |
181 | @subsection Shell Pattern Matching | |
182 | ||
183 | -@code{find} and @code{locate} can compare file names, or parts of file | |
184 | +@code{find} can compare file names, or parts of file | |
185 | names, to shell patterns. A @dfn{shell pattern} is a string that may | |
186 | contain the following special characters, which are known as | |
187 | @dfn{wildcards} or @dfn{metacharacters}. | |
1a4e795f | 188 | @@ -2886,245 +2785,6 @@ |
fe8a0ce5 JB |
189 | @end example |
190 | ||
191 | ||
192 | -@node Databases | |
193 | -@chapter File Name Databases | |
194 | - | |
195 | -The file name databases used by @code{locate} contain lists of files | |
196 | -that were in particular directory trees when the databases were last | |
197 | -updated. The file name of the default database is determined when | |
198 | -@code{locate} and @code{updatedb} are configured and installed. The | |
199 | -frequency with which the databases are updated and the directories for | |
200 | -which they contain entries depend on how often @code{updatedb} is run, | |
201 | -and with which arguments. | |
202 | - | |
203 | -You can obtain some statistics about the databases by using | |
204 | -@samp{locate --statistics}. | |
205 | - | |
206 | -@menu | |
207 | -* Database Locations:: | |
208 | -* Database Formats:: | |
209 | -* Newline Handling:: | |
210 | -@end menu | |
211 | - | |
212 | - | |
213 | -@node Database Locations | |
214 | -@section Database Locations | |
215 | - | |
216 | -There can be multiple file name databases. Users can select which | |
217 | -databases @code{locate} searches using the @code{LOCATE_PATH} | |
218 | -environment variable or a command line option. The system | |
219 | -administrator can choose the file name of the default database, the | |
220 | -frequency with which the databases are updated, and the directories | |
221 | -for which they contain entries. File name databases are updated by | |
222 | -running the @code{updatedb} program, typically nightly. | |
223 | - | |
224 | -In networked environments, it often makes sense to build a database at | |
225 | -the root of each filesystem, containing the entries for that | |
226 | -filesystem. @code{updatedb} is then run for each filesystem on the | |
227 | -fileserver where that filesystem is on a local disk, to prevent | |
228 | -thrashing the network. | |
229 | - | |
230 | -@xref{Invoking updatedb}, for the description of the options to | |
231 | -@code{updatedb}. These options can be used to specify which | |
232 | -directories are indexed by each database file. | |
233 | - | |
234 | -The default location for the locate database depends on how findutils | |
235 | -is built, but the findutils installation accompanying this manual uses | |
236 | -the default location @file{@value{LOCATE_DB}}. | |
237 | - | |
238 | -If no database exists at @file{@value{LOCATE_DB}} but the user did not | |
239 | -specify where to look (by using @samp{-d} or setting | |
240 | -@code{LOCATE_PATH}), then @code{locate} will also check for a | |
241 | -``secure'' database in @file{/var/lib/slocate/slocate.db}. | |
242 | - | |
243 | -@node Database Formats | |
244 | -@section Database Formats | |
245 | - | |
246 | -The file name databases contain lists of files that were in particular | |
247 | -directory trees when the databases were last updated. The file name | |
248 | -database format changed starting with GNU @code{locate} version 4.0 to | |
249 | -allow machines with different byte orderings to share the databases. | |
250 | - | |
1a4e795f JB |
251 | -GNU @code{locate} can read both the old pre-findutils-4.0 database |
252 | -format and the @samp{LOCATE02} database format. Support for the old | |
253 | -database format will shortly be removed from @code{locate}. It has | |
254 | -already been removed from @code{updatedb}. | |
fe8a0ce5 JB |
255 | - |
256 | -If you run @samp{locate --statistics}, the resulting summary indicates | |
257 | -the type of each @code{locate} database. You select which database | |
258 | -format @code{updatedb} will use with the @samp{--dbformat} option. | |
259 | - | |
1a4e795f JB |
260 | -The @samp{slocate} database format is very similar to @samp{LOCATE02} |
261 | -and is also supported (in both @code{updatedb} and @code{locate}). | |
fe8a0ce5 JB |
262 | - |
263 | -@menu | |
264 | -* LOCATE02 Database Format:: | |
265 | -* Sample LOCATE02 Database:: | |
266 | -* slocate Database Format:: | |
267 | -* Old Database Format:: | |
268 | -@end menu | |
269 | - | |
270 | -@node LOCATE02 Database Format | |
271 | -@subsection LOCATE02 Database Format | |
272 | - | |
273 | -@code{updatedb} runs a program called @code{frcode} to | |
274 | -@dfn{front-compress} the list of file names, which reduces the | |
275 | -database size by a factor of 4 to 5. Front-compression (also known as | |
276 | -incremental encoding) works as follows. | |
277 | - | |
278 | -The database entries are a sorted list (case-insensitively, for users' | |
279 | -convenience). Since the list is sorted, each entry is likely to share | |
280 | -a prefix (initial string) with the previous entry. Each database | |
281 | -entry begins with an offset-differential count byte, which is the | |
282 | -additional number of characters of prefix of the preceding entry to | |
283 | -use beyond the number that the preceding entry is using of its | |
284 | -predecessor. (The counts can be negative.) Following the count is a | |
a2caf129 | 285 | -null-terminated ASCII remainder -- the part of the name that follows |
fe8a0ce5 JB |
286 | -the shared prefix. |
287 | - | |
288 | -If the offset-differential count is larger than can be stored in a | |
289 | -byte (+/-127), the byte has the value 0x80 and the count follows in a | |
290 | -2-byte word, with the high byte first (network byte order). | |
291 | - | |
292 | -Every database begins with a dummy entry for a file called | |
293 | -@file{LOCATE02}, which @code{locate} checks for to ensure that the | |
294 | -database file has the correct format; it ignores the entry in doing | |
295 | -the search. | |
296 | - | |
297 | -Databases cannot be concatenated together, even if the first (dummy) | |
298 | -entry is trimmed from all but the first database. This is because the | |
299 | -offset-differential count in the first entry of the second and | |
300 | -following databases will be wrong. | |
301 | - | |
302 | -In the output of @samp{locate --statistics}, the new database format | |
303 | -is referred to as @samp{LOCATE02}. | |
304 | - | |
305 | -@node Sample LOCATE02 Database | |
306 | -@subsection Sample LOCATE02 Database | |
307 | - | |
308 | -Sample input to @code{frcode}: | |
309 | -@c with nulls changed to newlines: | |
310 | - | |
311 | -@example | |
312 | -/usr/src | |
313 | -/usr/src/cmd/aardvark.c | |
314 | -/usr/src/cmd/armadillo.c | |
315 | -/usr/tmp/zoo | |
316 | -@end example | |
317 | - | |
318 | -Length of the longest prefix of the preceding entry to share: | |
319 | - | |
320 | -@example | |
321 | -0 /usr/src | |
322 | -8 /cmd/aardvark.c | |
323 | -14 rmadillo.c | |
324 | -5 tmp/zoo | |
325 | -@end example | |
326 | - | |
327 | -Output from @code{frcode}, with trailing nulls changed to newlines | |
328 | -and count bytes made printable: | |
329 | - | |
330 | -@example | |
331 | -0 LOCATE02 | |
332 | -0 /usr/src | |
333 | -8 /cmd/aardvark.c | |
334 | -6 rmadillo.c | |
335 | --9 tmp/zoo | |
336 | -@end example | |
337 | - | |
338 | -(6 = 14 - 8, and -9 = 5 - 14) | |
339 | - | |
340 | -@node slocate Database Format | |
341 | -@subsection slocate Database Format | |
342 | - | |
343 | -The @code{slocate} program uses a database format similar to, but not | |
344 | -quite the same as, GNU @code{locate}. The first byte of the database | |
345 | -specifies its @dfn{security level}. If the security level is 0, | |
346 | -@code{slocate} will read, match and print filenames on the basis of | |
347 | -the information in the database only. However, if the security level | |
348 | -byte is 1, @code{slocate} omits entries from its output if the | |
349 | -invoking user is unable to access them. The second byte of the | |
350 | -database is zero. The second byte is immediately followed by the | |
351 | -first database entry. The first entry in the database is not preceded | |
352 | -by any differential count or dummy entry. Instead the differential | |
353 | -count for the first item is assumed to be zero. | |
a2caf129 | 354 | - |
fe8a0ce5 JB |
355 | -Starting with the second entry (if any) in the database, data is |
356 | -interpreted as for the GNU LOCATE02 format. | |
357 | - | |
358 | -@node Old Database Format | |
359 | -@subsection Old Database Format | |
360 | - | |
361 | -The old database format is used by Unix @code{locate} and @code{find} | |
1a4e795f JB |
362 | -programs and pre-4.0 releases of GNU findutils. @code{locate} |
363 | -understands this format, though @code{updatedb} will no longer produce | |
364 | -it. | |
365 | - | |
366 | -The old format differs from @samp{LOCATE02} in the following ways. | |
367 | -Instead of each entry starting with an offset-differential count byte | |
368 | -and ending with a null, byte values from 0 through 28 indicate | |
369 | -offset-differential counts from -14 through 14. The byte value | |
370 | -indicating that a long offset-differential count follows is 0x1e (30), | |
371 | -not 0x80. The long counts are stored in host byte order, which is not | |
372 | -necessarily network byte order, and host integer word size, which is | |
373 | -usually 4 bytes. They also represent a count 14 less than their | |
374 | -value. The database lines have no termination byte; the start of the | |
375 | -next line is indicated by its first byte having a value <= 30. | |
fe8a0ce5 JB |
376 | - |
377 | -In addition, instead of starting with a dummy entry, the old database | |
378 | -format starts with a 256 byte table containing the 128 most common | |
379 | -bigrams in the file list. A bigram is a pair of adjacent bytes. | |
380 | -Bytes in the database that have the high bit set are indexes (with the | |
381 | -high bit cleared) into the bigram table. The bigram and | |
382 | -offset-differential count coding makes these databases 20-25% smaller | |
383 | -than the new format, but makes them not 8-bit clean. Any byte in a | |
384 | -file name that is in the ranges used for the special codes is replaced | |
385 | -in the database by a question mark, which not coincidentally is the | |
1a4e795f JB |
386 | -shell wildcard to match a single character. The old format therefore |
387 | -cannot faithfully store entries with non-ASCII characters. | |
fe8a0ce5 | 388 | - |
1a4e795f | 389 | -Because the long counts are stored as |
a2caf129 | 390 | -native-order machine words, the database format is not easily used in |
fe8a0ce5 | 391 | -environments which differ in terms of byte order. If locate databases |
1a4e795f | 392 | -are to be shared between machines, the @samp{LOCATE02} database format should |
fe8a0ce5 JB |
393 | -be used. This has other benefits as discussed above. However, the |
394 | -length of the filename currently being processed can normally be used | |
395 | -to place reasonable limits on the long counts and so this information | |
396 | -is used by locate to help it guess the byte ordering of the old format | |
397 | -database. Unless it finds evidence to the contrary, @code{locate} | |
398 | -will assume that the byte order of the database is the same as the | |
399 | -native byte order of the machine running @code{locate}. The output of | |
400 | -@samp{locate --statistics} also includes information about the byte | |
401 | -order of old-format databases. | |
402 | - | |
403 | -The output of @samp{locate --statistics} will give an incorrect count | |
404 | -of the number of file names containing newlines or high-bit characters | |
405 | -for old-format databases. | |
406 | - | |
407 | -Old versions of GNU @code{locate} fail to correctly handle very long | |
408 | -file names, possibly leading to security problems relating to a heap | |
409 | -buffer overrun. @xref{Security Considerations for locate}, for a | |
410 | -detailed explanation. | |
411 | - | |
412 | -@node Newline Handling | |
413 | -@section Newline Handling | |
414 | - | |
415 | -Within the database, file names are terminated with a null character. | |
416 | -This is the case for both the old and the new format. | |
417 | - | |
418 | -When the new database format is being used, the compression technique | |
419 | -used to generate the database though relies on the ability to sort the | |
420 | -list of files before they are presented to @code{frcode}. | |
421 | - | |
422 | -If the system's sort command allows its input list of files to be | |
423 | -separated with null characters via the @samp{-z} option, this option | |
424 | -is used and therefore @code{updatedb} and @code{locate} will both | |
425 | -correctly handle file names containing newlines. If the @code{sort} | |
426 | -command lacks support for this, the list of files is delimited with | |
427 | -the newline character, meaning that parts of file names containing | |
428 | -newlines will be incorrectly sorted. This can result in both | |
429 | -incorrect matches and incorrect failures to match. | |
fe8a0ce5 JB |
430 | - |
431 | @node File Permissions | |
432 | @chapter File Permissions | |
433 | ||
1a4e795f | 434 | @@ -3203,15 +2863,13 @@ |
fe8a0ce5 JB |
435 | discussed in this manual. |
436 | ||
437 | @menu | |
438 | -* Invoking find:: | |
439 | -* Invoking locate:: | |
440 | -* Invoking updatedb:: | |
441 | -* Invoking xargs:: | |
442 | +* find:: | |
443 | +* xargs:: | |
444 | * Regular Expressions:: | |
445 | * Environment Variables:: | |
446 | @end menu | |
447 | ||
448 | -@node Invoking find | |
449 | +@node find | |
450 | @section Invoking @code{find} | |
451 | ||
452 | @example | |
1a4e795f | 453 | @@ -3426,243 +3084,7 @@ |
fe8a0ce5 JB |
454 | actions, and options that the expression can contain. If the |
455 | expression is missing, @samp{-print} is assumed. | |
456 | ||
457 | -@node Invoking locate | |
458 | -@section Invoking @code{locate} | |
459 | - | |
460 | -@example | |
461 | -locate @r{[}@var{option}@dots{}@r{]} @var{pattern}@dots{} | |
462 | -@end example | |
463 | - | |
464 | -For each @var{pattern} given @code{locate} searches one or more file | |
465 | -name databases returning each match of @var{pattern}. | |
466 | - | |
fe8a0ce5 JB |
467 | -@table @code |
468 | -@item --all | |
469 | -@itemx -A | |
470 | -Print only names which match all non-option arguments, not those | |
471 | -matching one or more non-option arguments. | |
472 | - | |
473 | -@item --basename | |
474 | -@itemx -b | |
475 | -The specified pattern is matched against just the last component of | |
476 | -the name of a file in the @code{locate} database. This last | |
477 | -component is also called the ``base name''. For example, the base | |
478 | -name of @file{/tmp/mystuff/foo.old.c} is @file{foo.old.c}. If the | |
479 | -pattern contains metacharacters, it must match the base name exactly. | |
480 | -If not, it must match part of the base name. | |
481 | - | |
482 | -@item --count | |
483 | -@itemx -c | |
484 | -Instead of printing the matched file names, just print the total | |
485 | -number of matches found, unless @samp{--print} (@samp{-p}) is also | |
486 | -present. | |
487 | - | |
488 | - | |
489 | -@item --database=@var{path} | |
490 | -@itemx -d @var{path} | |
491 | -Instead of searching the default @code{locate} database | |
492 | -@file{@value{LOCATE_DB}}, @code{locate} searches the file | |
493 | -name databases in @var{path}, which is a colon-separated list of | |
494 | -database file names. You can also use the environment variable | |
495 | -@code{LOCATE_PATH} to set the list of database files to search. The | |
496 | -option overrides the environment variable if both are used. Empty | |
497 | -elements in @var{path} (that is, a leading or trailing colon, or two | |
498 | -colons in a row) are taken to stand for the default database. | |
499 | -A database can be supplied on stdin, using @samp{-} as an element | |
500 | -of @samp{path}. If more than one element of @samp{path} is @samp{-}, | |
501 | -later instances are ignored (but a warning message is printed). | |
502 | - | |
503 | -@item --existing | |
504 | -@itemx -e | |
505 | -Only print out such names which currently exist (instead of such names | |
506 | -which existed when the database was created). Note that this may slow | |
507 | -down the program a lot, if there are many matches in the database. | |
508 | -The way in which broken symbolic links are treated is affected by the | |
509 | -@samp{-L}, @samp{-P} and @samp{-H} options. Please note that it is | |
510 | -possible for the file to be deleted after @code{locate} has checked | |
511 | -that it exists, but before you use it. This option is automatically | |
512 | -turned on when reading an @code{slocate} database in secure mode | |
513 | -(@pxref{slocate Database Format}). | |
514 | - | |
515 | -@item --non-existing | |
516 | -@itemx -E | |
517 | -Only print out such names which currently do not exist (instead of | |
518 | -such names which existed when the database was created). Note that | |
519 | -this may slow down the program a lot, if there are many matches in the | |
520 | -database. The way in which broken symbolic links are treated is | |
521 | -affected by the @samp{-L}, @samp{-P} and @samp{-H} options. Please | |
522 | -note that @code{locate} checks that the file does not exist, but a | |
523 | -file of the same name might be created after @code{locate}'s check but | |
524 | -before you read @code{locate}'s output. | |
525 | - | |
526 | -@item --follow | |
527 | -@itemx -L | |
528 | -If testing for the existence of files (with the @samp{-e} or @samp{-E} | |
529 | -options), consider broken symbolic links to be non-existing. This is | |
530 | -the default behaviour. | |
531 | - | |
532 | -@item --nofollow | |
533 | -@itemx -P | |
534 | -@itemx -H | |
535 | -If testing for the existence of files (with the @samp{-e} or @samp{-E} | |
536 | -options), treat broken symbolic links as if they were existing files. | |
537 | -The @samp{-H} form of this option is provided purely for similarity | |
538 | -with @code{find}; the use of @samp{-P} is recommended over @samp{-H}. | |
539 | - | |
540 | -@item --ignore-case | |
541 | -@itemx -i | |
542 | -Ignore case distinctions in both the pattern and the file names. | |
543 | - | |
544 | -@item --limit=N | |
545 | -@itemx -l N | |
546 | -Limit the number of results printed to N. When used with the | |
547 | -@samp{--count} option, the value printed will never be larger than | |
548 | -this limit. | |
549 | -@item --max-database-age=D | |
550 | -Normally, @code{locate} will issue a warning message when it searches | |
551 | -a database which is more than 8 days old. This option changes that | |
552 | -value to something other than 8. The effect of specifying a negative | |
553 | -value is undefined. | |
554 | -@item --mmap | |
555 | -@itemx -m | |
556 | -Accepted but does nothing. The option is supported only to provide | |
557 | -compatibility with BSD's @code{locate}. | |
a2caf129 | 558 | - |
fe8a0ce5 JB |
559 | -@item --null |
560 | -@itemx -0 | |
561 | -Results are separated with the ASCII NUL character rather than the | |
562 | -newline character. To get the full benefit of this option, | |
563 | -use the new @code{locate} database format (that is the default | |
564 | -anyway). | |
565 | - | |
566 | -@item --print | |
567 | -@itemx -p | |
568 | -Print search results when they normally would not be due to | |
569 | -use of @samp{--statistics} (@samp{-S}) or @samp{--count} | |
570 | -(@samp{-c}). | |
571 | - | |
572 | -@item --wholename | |
573 | -@itemx -w | |
574 | -The specified pattern is matched against the whole name of the file in | |
575 | -the @code{locate} database. If the pattern contains metacharacters, | |
576 | -it must match exactly. If not, it must match part of the whole file | |
577 | -name. This is the default behaviour. | |
578 | - | |
579 | -@item --regex | |
580 | -@itemx -r | |
581 | -Instead of using substring or shell glob matching, the pattern | |
582 | -specified on the command line is understood to be a regular | |
583 | -expression. GNU Emacs-style regular expressions are assumed unless | |
584 | -the @samp{--regextype} option is also given. File names from the | |
585 | -@code{locate} database are matched using the specified regular | |
586 | -expression. If the @samp{-i} flag is also given, matching is | |
587 | -case-insensitive. Matches are performed against the whole path name, | |
588 | -and so by default a pathname will be matched if any part of it matches | |
589 | -the specified regular expression. The regular expression may use | |
590 | -@samp{^} or @samp{$} to anchor a match at the beginning or end of a | |
591 | -pathname. | |
592 | - | |
593 | -@item --regextype | |
594 | -This option changes the regular expression syntax and behaviour used | |
595 | -by the @samp{--regex} option. @ref{Regular Expressions} for more | |
596 | -information on the regular expression dialects understood by GNU | |
597 | -findutils. | |
598 | - | |
599 | -@item --stdio | |
600 | -@itemx -s | |
601 | -Accepted but does nothing. The option is supported only to provide | |
602 | -compatibility with BSD's @code{locate}. | |
603 | - | |
604 | -@item --statistics | |
605 | -@itemx -S | |
606 | -Print some summary information for each @code{locate} database. No | |
607 | -search is performed unless non-option arguments are given. | |
608 | -Although the BSD version of locate also has this option, the format of the | |
609 | -output is different. | |
610 | - | |
611 | -@item --help | |
612 | -Print a summary of the command line usage for @code{locate} and exit. | |
613 | - | |
614 | -@item --version | |
615 | -Print the version number of @code{locate} and exit. | |
616 | -@end table | |
617 | - | |
618 | -@node Invoking updatedb | |
619 | -@section Invoking @code{updatedb} | |
620 | - | |
621 | -@example | |
622 | -updatedb @r{[}@var{option}@dots{}@r{]} | |
623 | -@end example | |
624 | - | |
625 | -@code{updatedb} creates and updates the database of file names used by | |
626 | -@code{locate}. @code{updatedb} generates a list of files similar to | |
627 | -the output of @code{find} and then uses utilities for optimizing the | |
628 | -database for performance. @code{updatedb} is often run periodically | |
629 | -as a @code{cron} job and configured with environment variables or | |
630 | -command options. Typically, operating systems have a shell script | |
631 | -that ``exports'' configurations for variable definitions and uses | |
632 | -another shell script that ``sources'' the configuration file into the | |
633 | -environment and then executes @code{updatedb} in the environment. | |
634 | - | |
fe8a0ce5 JB |
635 | -@table @code |
636 | -@item --findoptions='@var{OPTION}@dots{}' | |
637 | -Global options to pass on to @code{find}. | |
638 | -The environment variable @code{FINDOPTIONS} also sets this value. | |
639 | -Default is none. | |
640 | - | |
641 | -@item --localpaths='@var{path}@dots{}' | |
642 | -Non-network directories to put in the database. | |
643 | -Default is @file{/}. | |
644 | - | |
645 | -@item --netpaths='@var{path}@dots{}' | |
646 | -Network (NFS, AFS, RFS, etc.) directories to put in the database. | |
647 | -The environment variable @code{NETPATHS} also sets this value. | |
648 | -Default is none. | |
649 | - | |
650 | -@item --prunepaths='@var{path}@dots{}' | |
651 | -Directories to omit from the database, which would otherwise be | |
652 | -included. The environment variable @code{PRUNEPATHS} also sets this | |
653 | -value. Default is @file{/tmp /usr/tmp /var/tmp /afs}. The paths are | |
654 | -used as regular expressions (with @code{find ... -regex}, so you need | |
655 | -to specify these paths in the same way that @code{find} will encounter | |
656 | -them. This means for example that the paths must not include trailing | |
657 | -slashes. | |
658 | - | |
659 | -@item --prunefs='@var{path}@dots{}' | |
660 | -Filesystems to omit from the database, which would otherwise be | |
661 | -included. Note that files are pruned when a filesystem is reached; | |
662 | -Any filesystem mounted under an undesired filesystem will be ignored. | |
663 | -The environment variable @code{PRUNEFS} also sets this value. Default | |
664 | -is @file{nfs NFS proc}. | |
665 | - | |
666 | -@item --output=@var{dbfile} | |
667 | -The database file to build. The default is system-dependent, but | |
668 | -when this document was formatted it was @file{@value{LOCATE_DB}}. | |
669 | - | |
670 | -@item --localuser=@var{user} | |
671 | -The user to search the non-network directories as, using @code{su}. | |
672 | -Default is to search the non-network directories as the current user. | |
673 | -You can also use the environment variable @code{LOCALUSER} to set this user. | |
674 | - | |
675 | -@item --netuser=@var{user} | |
676 | -The user to search network directories as, using @code{su}. Default | |
677 | -@code{user} is @code{daemon}. You can also use the environment variable | |
678 | -@code{NETUSER} to set this user. | |
679 | - | |
fe8a0ce5 JB |
680 | -@item --dbformat=@var{FORMAT} |
681 | -Generate the locate database in format @code{FORMAT}. Supported | |
1a4e795f JB |
682 | -database formats include @code{LOCATE02} (which is the default) and |
683 | -@code{slocate}. The @code{slocate} format exists for compatibility | |
684 | -with @code{slocate}. @xref{Database Formats}, for a detailed | |
685 | -description of each format. | |
fe8a0ce5 JB |
686 | - |
687 | -@item --help | |
688 | -Print a summary of the command line usage and exit. | |
689 | -@item --version | |
690 | -Print the version number of @code{updatedb} and exit. | |
691 | -@end table | |
692 | - | |
693 | -@node Invoking xargs | |
694 | +@node xargs | |
695 | @section Invoking @code{xargs} | |
696 | ||
697 | @example | |
1a4e795f | 698 | @@ -4985,7 +4407,6 @@ |
fe8a0ce5 JB |
699 | * Levels of Risk:: What is your level of exposure to security problems? |
700 | * Security Considerations for find:: Security problems with find | |
701 | * Security Considerations for xargs:: Security problems with xargs | |
702 | -* Security Considerations for locate:: Security problems with locate | |
703 | * Security Summary:: That was all very complex, what does it boil down to? | |
a2caf129 | 704 | * Further Reading on Security:: |
fe8a0ce5 | 705 | @end menu |
1a4e795f | 706 | @@ -5392,19 +4813,6 @@ |
fe8a0ce5 JB |
707 | trailing whitespace is turned off by the @samp{-0} argument to |
708 | @code{xargs}, which is another reason to use that option. | |
709 | ||
710 | -@comment node-name, next, previous, up | |
711 | -@node Security Considerations for locate | |
712 | -@section Security Considerations for @code{locate} | |
713 | - | |
714 | -@subsection Race Conditions | |
715 | -It is fairly unusual for the output of @code{locate} to be fed into | |
716 | -another command. However, if this were to be done, this would raise | |
717 | -the same set of security issues as the use of @samp{find @dots{} -print}. | |
718 | -Although the problems relating to whitespace in file names can be | |
719 | -resolved by using @code{locate}'s @samp{-0} option, this still leaves | |
720 | -the race condition problems associated with @samp{find @dots{} -print0}. | |
721 | -There is no way to avoid these problems in the case of @code{locate}. | |
722 | - | |
fe8a0ce5 JB |
723 | @node Security Summary |
724 | @section Summary | |
1a4e795f JB |
725 | |
726 | @@ -5476,8 +4884,6 @@ | |
fe8a0ce5 JB |
727 | @menu |
728 | * Error Messages From find:: | |
729 | * Error Messages From xargs:: | |
730 | -* Error Messages From locate:: | |
731 | -* Error Messages From updatedb:: | |
732 | @end menu | |
733 | ||
734 | @node Error Messages From find | |
1a4e795f JB |
735 | @@ -5627,38 +5033,6 @@ |
736 | See the manual of the system call @code{dup2(2)}. | |
fe8a0ce5 JB |
737 | @end table |
738 | ||
739 | -@node Error Messages From locate | |
740 | -@section Error Messages From @code{locate} | |
741 | - | |
742 | -@table @samp | |
743 | -@item warning: database @file{@value{LOCATE_DB}} is more than 8 days old | |
744 | -The @code{locate} program relies on a database which is periodically | |
745 | -built by the @code{updatedb} program. That hasn't happened in a long | |
746 | -time. To fix this problem, run @code{updatedb} manually. This can | |
747 | -often happen on systems that are generally not left on, so the | |
748 | -periodic ``cron'' task which normally does this doesn't get a chance | |
749 | -to run. | |
750 | - | |
751 | -@item locate database @file{@value{LOCATE_DB}} is corrupt or invalid | |
752 | -This should not happen. Re-run @code{updatedb}. If that works, but | |
753 | -@code{locate} still produces this error, run @code{locate --version} | |
754 | -and @code{updatedb --version}. These should produce the same output. | |
755 | -If not, you are using a mixed toolset; check your @samp{$PATH} | |
756 | -environment variable and your shell aliases (if you have any). If | |
757 | -both programs claim to be GNU versions, this is a bug; all versions of | |
758 | -these programs should interoperate without problem. Ask for help on | |
759 | -@email{bug-findutils@@gnu.org}. | |
760 | -@end table | |
761 | - | |
762 | - | |
763 | -@node Error Messages From updatedb | |
a2caf129 | 764 | -@section Error Messages From @code{updatedb} |
fe8a0ce5 JB |
765 | - |
766 | -The @code{updatedb} program (and the programs it invokes) do issue | |
767 | -error messages, but none seem to be candidates for guidance. If | |
768 | -you are having a problem understanding one of these, ask for help on | |
769 | -@email{bug-findutils@@gnu.org}. | |
a2caf129 | 770 | - |
fe8a0ce5 JB |
771 | @node GNU Free Documentation License |
772 | @appendix GNU Free Documentation License | |
a2caf129 | 773 | @include fdl.texi |