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