1 --- findutils-4.6.0/doc/find.texi.orig 2015-12-28 22:10:23.000000000 +0100
2 +++ findutils-4.6.0/doc/find.texi 2016-01-24 17:56:21.578207819 +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
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.
32 * Configuration:: Options you can select at compile time.
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
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!
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
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}.
70 @code{find} searches for files in a directory hierarchy and prints
71 information about the files it found. It is run like this:
73 Notice that the wildcard must be enclosed in quotes in order to
74 protect it from expansion by the shell.
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:
81 -locate @r{[}@var{option}@dots{}@r{]} @var{pattern}@dots{}
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}.
90 -locate '*[Mm]akefile'
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
98 * Base Name Patterns::
99 * Full Name Patterns::
100 -* Fast Full Name Search::
101 * Shell Pattern Matching:: Wildcards used by these programs.
104 @@ -524,82 +495,10 @@
108 -@node Fast Full Name Search
109 -@subsection Fast Full Name Search
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.
118 -If a pattern is a plain string -- it contains no
119 -metacharacters -- @code{locate} displays all file names in the database
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.
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}.
134 -locate @var{pattern}
137 -is almost equivalent to
139 -find @var{directories} -name @var{pattern}
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}).
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
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}}.
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.
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.
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.
180 @node Shell Pattern Matching
181 @subsection Shell Pattern Matching
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}.
188 @@ -2849,261 +2748,6 @@
193 -@chapter File Name Databases
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.
203 -You can obtain some statistics about the databases by using
204 -@samp{locate --statistics}.
207 -* Database Locations::
208 -* Database Formats::
209 -* Newline Handling::
213 -@node Database Locations
214 -@section Database Locations
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.
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.
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.
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}}.
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}.
243 -@node Database Formats
244 -@section Database Formats
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.
251 -GNU @code{locate} can read both the old and new database formats.
252 -However, old versions of @code{locate} (on other Unix systems, or GNU
253 -@code{locate} before version 4.0) produce incorrect results if run
254 -against a database in something other than the old format.
256 -Support for the old database format will eventually be discontinued,
257 -first in @code{updatedb} and later in @code{locate}.
259 -If you run @samp{locate --statistics}, the resulting summary indicates
260 -the type of each @code{locate} database. You select which database
261 -format @code{updatedb} will use with the @samp{--dbformat} option.
265 -* LOCATE02 Database Format::
266 -* Sample LOCATE02 Database::
267 -* slocate Database Format::
268 -* Old Database Format::
271 -@node LOCATE02 Database Format
272 -@subsection LOCATE02 Database Format
274 -@code{updatedb} runs a program called @code{frcode} to
275 -@dfn{front-compress} the list of file names, which reduces the
276 -database size by a factor of 4 to 5. Front-compression (also known as
277 -incremental encoding) works as follows.
279 -The database entries are a sorted list (case-insensitively, for users'
280 -convenience). Since the list is sorted, each entry is likely to share
281 -a prefix (initial string) with the previous entry. Each database
282 -entry begins with an offset-differential count byte, which is the
283 -additional number of characters of prefix of the preceding entry to
284 -use beyond the number that the preceding entry is using of its
285 -predecessor. (The counts can be negative.) Following the count is a
286 -null-terminated ASCII remainder -- the part of the name that follows
289 -If the offset-differential count is larger than can be stored in a
290 -byte (+/-127), the byte has the value 0x80 and the count follows in a
291 -2-byte word, with the high byte first (network byte order).
293 -Every database begins with a dummy entry for a file called
294 -@file{LOCATE02}, which @code{locate} checks for to ensure that the
295 -database file has the correct format; it ignores the entry in doing
298 -Databases cannot be concatenated together, even if the first (dummy)
299 -entry is trimmed from all but the first database. This is because the
300 -offset-differential count in the first entry of the second and
301 -following databases will be wrong.
303 -In the output of @samp{locate --statistics}, the new database format
304 -is referred to as @samp{LOCATE02}.
306 -@node Sample LOCATE02 Database
307 -@subsection Sample LOCATE02 Database
309 -Sample input to @code{frcode}:
310 -@c with nulls changed to newlines:
314 -/usr/src/cmd/aardvark.c
315 -/usr/src/cmd/armadillo.c
319 -Length of the longest prefix of the preceding entry to share:
328 -Output from @code{frcode}, with trailing nulls changed to newlines
329 -and count bytes made printable:
339 -(6 = 14 - 8, and -9 = 5 - 14)
341 -@node slocate Database Format
342 -@subsection slocate Database Format
344 -The @code{slocate} program uses a database format similar to, but not
345 -quite the same as, GNU @code{locate}. The first byte of the database
346 -specifies its @dfn{security level}. If the security level is 0,
347 -@code{slocate} will read, match and print filenames on the basis of
348 -the information in the database only. However, if the security level
349 -byte is 1, @code{slocate} omits entries from its output if the
350 -invoking user is unable to access them. The second byte of the
351 -database is zero. The second byte is immediately followed by the
352 -first database entry. The first entry in the database is not preceded
353 -by any differential count or dummy entry. Instead the differential
354 -count for the first item is assumed to be zero.
356 -Starting with the second entry (if any) in the database, data is
357 -interpreted as for the GNU LOCATE02 format.
359 -@node Old Database Format
360 -@subsection Old Database Format
362 -The old database format is used by Unix @code{locate} and @code{find}
363 -programs and earlier releases of the GNU ones. @code{updatedb}
364 -produces this format if given the @samp{--old-format} option.
366 -@code{updatedb} runs programs called @code{bigram} and @code{code} to
367 -produce old-format databases. The old format differs from the new one
368 -in the following ways. Instead of each entry starting with an
369 -offset-differential count byte and ending with a null, byte values
370 -from 0 through 28 indicate offset-differential counts from -14 through
371 -14. The byte value indicating that a long offset-differential count
372 -follows is 0x1e (30), not 0x80. The long counts are stored in host
373 -byte order, which is not necessarily network byte order, and host
374 -integer word size, which is usually 4 bytes. They also represent a
375 -count 14 less than their value. The database lines have no
376 -termination byte; the start of the next line is indicated by its first
377 -byte having a value <= 30.
379 -In addition, instead of starting with a dummy entry, the old database
380 -format starts with a 256 byte table containing the 128 most common
381 -bigrams in the file list. A bigram is a pair of adjacent bytes.
382 -Bytes in the database that have the high bit set are indexes (with the
383 -high bit cleared) into the bigram table. The bigram and
384 -offset-differential count coding makes these databases 20-25% smaller
385 -than the new format, but makes them not 8-bit clean. Any byte in a
386 -file name that is in the ranges used for the special codes is replaced
387 -in the database by a question mark, which not coincidentally is the
388 -shell wildcard to match a single character.
390 -The old format therefore cannot faithfully store entries with
391 -non-ASCII characters. It therefore should not be used in
392 -internationalised environments. That is, most installations should
395 -Because the long counts are stored by the @code{code} program as
396 -native-order machine words, the database format is not easily used in
397 -environments which differ in terms of byte order. If locate databases
398 -are to be shared between machines, the LOCATE02 database format should
399 -be used. This has other benefits as discussed above. However, the
400 -length of the filename currently being processed can normally be used
401 -to place reasonable limits on the long counts and so this information
402 -is used by locate to help it guess the byte ordering of the old format
403 -database. Unless it finds evidence to the contrary, @code{locate}
404 -will assume that the byte order of the database is the same as the
405 -native byte order of the machine running @code{locate}. The output of
406 -@samp{locate --statistics} also includes information about the byte
407 -order of old-format databases.
409 -The output of @samp{locate --statistics} will give an incorrect count
410 -of the number of file names containing newlines or high-bit characters
411 -for old-format databases.
413 -Old versions of GNU @code{locate} fail to correctly handle very long
414 -file names, possibly leading to security problems relating to a heap
415 -buffer overrun. @xref{Security Considerations for locate}, for a
416 -detailed explanation.
418 -@node Newline Handling
419 -@section Newline Handling
421 -Within the database, file names are terminated with a null character.
422 -This is the case for both the old and the new format.
424 -When the new database format is being used, the compression technique
425 -used to generate the database though relies on the ability to sort the
426 -list of files before they are presented to @code{frcode}.
428 -If the system's sort command allows its input list of files to be
429 -separated with null characters via the @samp{-z} option, this option
430 -is used and therefore @code{updatedb} and @code{locate} will both
431 -correctly handle file names containing newlines. If the @code{sort}
432 -command lacks support for this, the list of files is delimited with
433 -the newline character, meaning that parts of file names containing
434 -newlines will be incorrectly sorted. This can result in both
435 -incorrect matches and incorrect failures to match.
437 -On the other hand, if you are using the old database format, file
438 -names with embedded newlines are not correctly handled. There is no
439 -technical limitation which enforces this, it's just that the
440 -@code{bigram} program has not been updated to support lists of file
441 -names separated by nulls.
443 -So, if you are using the new database format (this is the default) and
444 -your system uses GNU @code{sort}, newlines will be correctly handled
445 -at all times. Otherwise, newlines may not be correctly handled.
447 @node File Permissions
448 @chapter File Permissions
450 @@ -3182,15 +2826,13 @@
451 discussed in this manual.
456 -* Invoking updatedb::
460 * Regular Expressions::
461 * Environment Variables::
466 @section Invoking @code{find}
469 @@ -3404,255 +3046,7 @@
470 actions, and options that the expression can contain. If the
471 expression is missing, @samp{-print} is assumed.
473 -@node Invoking locate
474 -@section Invoking @code{locate}
477 -locate @r{[}@var{option}@dots{}@r{]} @var{pattern}@dots{}
480 -For each @var{pattern} given @code{locate} searches one or more file
481 -name databases returning each match of @var{pattern}.
486 -Print only names which match all non-option arguments, not those
487 -matching one or more non-option arguments.
491 -The specified pattern is matched against just the last component of
492 -the name of a file in the @code{locate} database. This last
493 -component is also called the ``base name''. For example, the base
494 -name of @file{/tmp/mystuff/foo.old.c} is @file{foo.old.c}. If the
495 -pattern contains metacharacters, it must match the base name exactly.
496 -If not, it must match part of the base name.
500 -Instead of printing the matched file names, just print the total
501 -number of matches found, unless @samp{--print} (@samp{-p}) is also
505 -@item --database=@var{path}
506 -@itemx -d @var{path}
507 -Instead of searching the default @code{locate} database
508 -@file{@value{LOCATE_DB}}, @code{locate} searches the file
509 -name databases in @var{path}, which is a colon-separated list of
510 -database file names. You can also use the environment variable
511 -@code{LOCATE_PATH} to set the list of database files to search. The
512 -option overrides the environment variable if both are used. Empty
513 -elements in @var{path} (that is, a leading or trailing colon, or two
514 -colons in a row) are taken to stand for the default database.
515 -A database can be supplied on stdin, using @samp{-} as an element
516 -of @samp{path}. If more than one element of @samp{path} is @samp{-},
517 -later instances are ignored (but a warning message is printed).
521 -Only print out such names which currently exist (instead of such names
522 -which existed when the database was created). Note that this may slow
523 -down the program a lot, if there are many matches in the database.
524 -The way in which broken symbolic links are treated is affected by the
525 -@samp{-L}, @samp{-P} and @samp{-H} options. Please note that it is
526 -possible for the file to be deleted after @code{locate} has checked
527 -that it exists, but before you use it. This option is automatically
528 -turned on when reading an @code{slocate} database in secure mode
529 -(@pxref{slocate Database Format}).
531 -@item --non-existing
533 -Only print out such names which currently do not exist (instead of
534 -such names which existed when the database was created). Note that
535 -this may slow down the program a lot, if there are many matches in the
536 -database. The way in which broken symbolic links are treated is
537 -affected by the @samp{-L}, @samp{-P} and @samp{-H} options. Please
538 -note that @code{locate} checks that the file does not exist, but a
539 -file of the same name might be created after @code{locate}'s check but
540 -before you read @code{locate}'s output.
544 -If testing for the existence of files (with the @samp{-e} or @samp{-E}
545 -options), consider broken symbolic links to be non-existing. This is
546 -the default behaviour.
551 -If testing for the existence of files (with the @samp{-e} or @samp{-E}
552 -options), treat broken symbolic links as if they were existing files.
553 -The @samp{-H} form of this option is provided purely for similarity
554 -with @code{find}; the use of @samp{-P} is recommended over @samp{-H}.
558 -Ignore case distinctions in both the pattern and the file names.
562 -Limit the number of results printed to N. When used with the
563 -@samp{--count} option, the value printed will never be larger than
565 -@item --max-database-age=D
566 -Normally, @code{locate} will issue a warning message when it searches
567 -a database which is more than 8 days old. This option changes that
568 -value to something other than 8. The effect of specifying a negative
572 -Accepted but does nothing. The option is supported only to provide
573 -compatibility with BSD's @code{locate}.
577 -Results are separated with the ASCII NUL character rather than the
578 -newline character. To get the full benefit of this option,
579 -use the new @code{locate} database format (that is the default
584 -Print search results when they normally would not be due to
585 -use of @samp{--statistics} (@samp{-S}) or @samp{--count}
590 -The specified pattern is matched against the whole name of the file in
591 -the @code{locate} database. If the pattern contains metacharacters,
592 -it must match exactly. If not, it must match part of the whole file
593 -name. This is the default behaviour.
597 -Instead of using substring or shell glob matching, the pattern
598 -specified on the command line is understood to be a regular
599 -expression. GNU Emacs-style regular expressions are assumed unless
600 -the @samp{--regextype} option is also given. File names from the
601 -@code{locate} database are matched using the specified regular
602 -expression. If the @samp{-i} flag is also given, matching is
603 -case-insensitive. Matches are performed against the whole path name,
604 -and so by default a pathname will be matched if any part of it matches
605 -the specified regular expression. The regular expression may use
606 -@samp{^} or @samp{$} to anchor a match at the beginning or end of a
610 -This option changes the regular expression syntax and behaviour used
611 -by the @samp{--regex} option. @ref{Regular Expressions} for more
612 -information on the regular expression dialects understood by GNU
617 -Accepted but does nothing. The option is supported only to provide
618 -compatibility with BSD's @code{locate}.
622 -Print some summary information for each @code{locate} database. No
623 -search is performed unless non-option arguments are given.
624 -Although the BSD version of locate also has this option, the format of the
625 -output is different.
628 -Print a summary of the command line usage for @code{locate} and exit.
631 -Print the version number of @code{locate} and exit.
634 -@node Invoking updatedb
635 -@section Invoking @code{updatedb}
638 -updatedb @r{[}@var{option}@dots{}@r{]}
641 -@code{updatedb} creates and updates the database of file names used by
642 -@code{locate}. @code{updatedb} generates a list of files similar to
643 -the output of @code{find} and then uses utilities for optimizing the
644 -database for performance. @code{updatedb} is often run periodically
645 -as a @code{cron} job and configured with environment variables or
646 -command options. Typically, operating systems have a shell script
647 -that ``exports'' configurations for variable definitions and uses
648 -another shell script that ``sources'' the configuration file into the
649 -environment and then executes @code{updatedb} in the environment.
652 -@item --findoptions='@var{OPTION}@dots{}'
653 -Global options to pass on to @code{find}.
654 -The environment variable @code{FINDOPTIONS} also sets this value.
657 -@item --localpaths='@var{path}@dots{}'
658 -Non-network directories to put in the database.
659 -Default is @file{/}.
661 -@item --netpaths='@var{path}@dots{}'
662 -Network (NFS, AFS, RFS, etc.) directories to put in the database.
663 -The environment variable @code{NETPATHS} also sets this value.
666 -@item --prunepaths='@var{path}@dots{}'
667 -Directories to omit from the database, which would otherwise be
668 -included. The environment variable @code{PRUNEPATHS} also sets this
669 -value. Default is @file{/tmp /usr/tmp /var/tmp /afs}. The paths are
670 -used as regular expressions (with @code{find ... -regex}, so you need
671 -to specify these paths in the same way that @code{find} will encounter
672 -them. This means for example that the paths must not include trailing
675 -@item --prunefs='@var{path}@dots{}'
676 -Filesystems to omit from the database, which would otherwise be
677 -included. Note that files are pruned when a filesystem is reached;
678 -Any filesystem mounted under an undesired filesystem will be ignored.
679 -The environment variable @code{PRUNEFS} also sets this value. Default
680 -is @file{nfs NFS proc}.
682 -@item --output=@var{dbfile}
683 -The database file to build. The default is system-dependent, but
684 -when this document was formatted it was @file{@value{LOCATE_DB}}.
686 -@item --localuser=@var{user}
687 -The user to search the non-network directories as, using @code{su}.
688 -Default is to search the non-network directories as the current user.
689 -You can also use the environment variable @code{LOCALUSER} to set this user.
691 -@item --netuser=@var{user}
692 -The user to search network directories as, using @code{su}. Default
693 -@code{user} is @code{daemon}. You can also use the environment variable
694 -@code{NETUSER} to set this user.
697 -Generate a @code{locate} database in the old format, for compatibility
698 -with versions of @code{locate} other than GNU @code{locate}. Using
699 -this option means that @code{locate} will not be able to properly
700 -handle non-ASCII characters in file names (that is, file names
701 -containing characters which have the eighth bit set, such as many of
702 -the characters from the ISO-8859-1 character set). @xref{Database
703 -Formats}, for a detailed description of the supported database
706 -@item --dbformat=@var{FORMAT}
707 -Generate the locate database in format @code{FORMAT}. Supported
708 -database formats include @code{LOCATE02} (which is the default),
709 -@code{old} and @code{slocate}. The @code{old} format exists for
710 -compatibility with implementations of @code{locate} on other Unix
711 -systems. The @code{slocate} format exists for compatibility with
712 -@code{slocate}. @xref{Database Formats}, for a detailed description
716 -Print a summary of the command line usage and exit.
718 -Print the version number of @code{updatedb} and exit.
721 -@node Invoking xargs
723 @section Invoking @code{xargs}
726 @@ -4953,7 +4347,6 @@
727 * Levels of Risk:: What is your level of exposure to security problems?
728 * Security Considerations for find:: Security problems with find
729 * Security Considerations for xargs:: Security problems with xargs
730 -* Security Considerations for locate:: Security problems with locate
731 * Security Summary:: That was all very complex, what does it boil down to?
732 * Further Reading on Security::
734 @@ -5360,59 +4753,6 @@
735 trailing whitespace is turned off by the @samp{-0} argument to
736 @code{xargs}, which is another reason to use that option.
738 -@comment node-name, next, previous, up
739 -@node Security Considerations for locate
740 -@section Security Considerations for @code{locate}
742 -@subsection Race Conditions
743 -It is fairly unusual for the output of @code{locate} to be fed into
744 -another command. However, if this were to be done, this would raise
745 -the same set of security issues as the use of @samp{find @dots{} -print}.
746 -Although the problems relating to whitespace in file names can be
747 -resolved by using @code{locate}'s @samp{-0} option, this still leaves
748 -the race condition problems associated with @samp{find @dots{} -print0}.
749 -There is no way to avoid these problems in the case of @code{locate}.
751 -@subsection Long File Name Bugs with Old-Format Databases
752 -Old versions of @code{locate} have a bug in the way that old-format
753 -databases are read. This bug affects the following versions of
757 -@item All releases prior to 4.2.31
758 -@item All 4.3.x releases prior to 4.3.7
761 -The affected versions of @code{locate} read file names into a
762 -fixed-length 1026 byte buffer, allocated on the heap. This buffer is
763 -not extended if file names are too long to fit into the buffer. No
764 -range checking on the length of the filename is performed. This could
765 -in theory lead to a privilege escalation attack. Findutils versions
766 -4.3.0 to 4.3.6 are also affected.
768 -On systems using the old database format and affected versions of
769 -@code{locate}, carefully-chosen long file names could in theory allow
770 -malicious users to run code of their choice as any user invoking
773 -If remote users can choose the names of files stored on your system,
774 -and these files are indexed by @code{updatedb}, this may be a remote
775 -security vulnerability. Findutils version 4.2.31 and findutils
776 -version 4.3.7 include fixes for this problem. The @code{updatedb},
777 -@code{bigram} and @code{code} programs do no appear to be affected.
779 -If you are also using GNU coreutils, you can use the following command
780 -to determine the length of the longest file name on a given system:
783 -find / -print0 | tr -c '\0' 'x' | tr '\0' '\n' | wc -L
786 -Although this problem is significant, the old database format is not
787 -the default, and use of the old database format is not common. Most
788 -installations and most users will not be affected by this problem.
792 @node Security Summary
794 @@ -5485,8 +4825,6 @@
796 * Error Messages From find::
797 * Error Messages From xargs::
798 -* Error Messages From locate::
799 -* Error Messages From updatedb::
802 @node Error Messages From find
803 @@ -5631,38 +4969,6 @@
804 why @code{xargs} is confused by your operating system).
807 -@node Error Messages From locate
808 -@section Error Messages From @code{locate}
811 -@item warning: database @file{@value{LOCATE_DB}} is more than 8 days old
812 -The @code{locate} program relies on a database which is periodically
813 -built by the @code{updatedb} program. That hasn't happened in a long
814 -time. To fix this problem, run @code{updatedb} manually. This can
815 -often happen on systems that are generally not left on, so the
816 -periodic ``cron'' task which normally does this doesn't get a chance
819 -@item locate database @file{@value{LOCATE_DB}} is corrupt or invalid
820 -This should not happen. Re-run @code{updatedb}. If that works, but
821 -@code{locate} still produces this error, run @code{locate --version}
822 -and @code{updatedb --version}. These should produce the same output.
823 -If not, you are using a mixed toolset; check your @samp{$PATH}
824 -environment variable and your shell aliases (if you have any). If
825 -both programs claim to be GNU versions, this is a bug; all versions of
826 -these programs should interoperate without problem. Ask for help on
827 -@email{bug-findutils@@gnu.org}.
831 -@node Error Messages From updatedb
832 -@section Error Messages From @code{updatedb}
834 -The @code{updatedb} program (and the programs it invokes) do issue
835 -error messages, but none seem to be candidates for guidance. If
836 -you are having a problem understanding one of these, ask for help on
837 -@email{bug-findutils@@gnu.org}.
839 @node GNU Free Documentation License
840 @appendix GNU Free Documentation License
projects / packages / findutils.git / blob