diff options
Diffstat (limited to 'upstream/debian-bookworm/man1/locate.findutils.1')
| -rw-r--r-- | upstream/debian-bookworm/man1/locate.findutils.1 | 306 |
1 files changed, 306 insertions, 0 deletions
diff --git a/upstream/debian-bookworm/man1/locate.findutils.1 b/upstream/debian-bookworm/man1/locate.findutils.1 new file mode 100644 index 00000000..a456e6d9 --- /dev/null +++ b/upstream/debian-bookworm/man1/locate.findutils.1 @@ -0,0 +1,306 @@ +.TH LOCATE 1 \" -*- nroff -*- +.SH NAME +locate \- list files in databases that match a pattern +. +.SH SYNOPSIS +.B locate +[\-d path | \-\-database=path] +[\-e | \-E | \-\-[non\-]existing] +[\-i | \-\-ignore-case] +[\-0 | \-\-null] +[\-c | \-\-count] +[\-w | \-\-wholename] +[\-b | \-\-basename] +[\-l N | \-\-limit=N] +[\-S | \-\-statistics] +[\-r | \-\-regex ] +[\-\-regextype R] +[\-\-max-database-age D] +[\-P | \-H | \-\-nofollow] +[\-L | \-\-follow] +[\-\-version] +[\-A | \-\-all] +[\-p | \-\-print] +[\-\-help] +pattern... +. +.SH DESCRIPTION +This manual page +documents the GNU version of +.BR locate . +For each given pattern, +.B locate +searches one or more databases of file names and displays the +file names that contain the pattern. Patterns can contain shell-style +metacharacters: `*', `?', and `[]'. The metacharacters do not treat +`/' or `.' specially. Therefore, a pattern `foo*bar' can match a +file name that contains `foo3/bar', and a pattern `*duck*' can match a +file name that contains `lake/.ducky'. Patterns that contain +metacharacters should be quoted to protect them from expansion by the +shell. +.P +If a pattern is a plain string \(em it contains no metacharacters \(em +.B locate +displays all file names in the database that contain that string +anywhere. If a pattern does contain metacharacters, +.B locate +only displays file names that match the pattern exactly. As a result, +patterns that contain metacharacters should usually begin with a `*', +and will most often end with one as well. The exceptions are patterns +that are intended to explicitly match the beginning or end of a file +name. +.P +The file name databases contain lists of files that were on the system +when the databases were last updated. The system administrator can +choose the file name of the default database, the frequency with which +the databases are updated, and the directories for which they contain +entries; see \fBupdatedb\fP(1). +.P +If +.BR locate 's +output is going to a terminal, unusual characters in the output are +escaped in the same way as for the \-print action of the +.B find +command. If the output is not going to a terminal, file names are +printed exactly as-is. +. +.SH OPTIONS +.TP +.I "\-0, \-\-null" +Use ASCII NUL as a separator, instead of newline. +.TP +.I "\-A, \-\-all" +Print only names which match all non-option arguments, not those matching +one or more non-option arguments. +.TP +.I "\-b, \-\-basename" +Results are considered to match if the pattern specified matches the +final component of the name of a file as listed in the database. +This final component is usually referred to as the `base name'. +.TP +.I "\-c, \-\-count" +Instead of printing the matched filenames, just print the total +number of matches we found, unless \-\-\fIprint\fP (\-p) is also present. +.TP +.I "\-d \fIpath\fP, \-\-database=\fIpath\fP" +Instead of searching the default file name database, search the file +name databases in \fIpath\fP, which is a colon-separated list of +database file names. You can also use the environment variable +.B LOCATE_PATH +to set the list of database files to search. +The option overrides the environment variable if both are used. Empty +elements in the path are taken to be synonyms for the file name of the +default database. +A database can be supplied on stdin, using `\-' as an element +of \fIpath\fP. If more than one element of \fIpath\fP is `\-', +later instances are ignored (and a warning message is printed). +.IP +The file name database format changed starting with GNU +.B find +and +.B locate +version 4.0 to allow machines with different byte orderings to share +the databases. This version of +.B locate +can automatically recognize and read databases produced for older +versions of GNU +.B locate +or Unix versions of +.B locate +or +.BR find . +Support for the old locate database format will be discontinued in a +future release. +.TP +.I "\-e, \-\-existing" +Only print out such names that currently exist (instead of such names +that existed when the database was created). +Note that this may slow down the program a lot, if there are many matches +in the database. If you are using this option within a program, +please note that it is possible for the file to be deleted after +.B locate +has checked that it exists, but before you use it. +.TP +.I "\-E, \-\-non\-existing" +Only print out such names that currently do not exist (instead of such names +that existed when the database was created). +Note that this may slow down the program a lot, if there are many matches +in the database. +.TP +.I "\-\-help" +Print a summary of the options to +.B locate +and exit. +.TP +.I "\-i, \-\-ignore-case" +Ignore case distinctions in both the pattern and the file names. +.TP +.I "\-l N, \-\-limit=N" +Limit the number of matches to N. If a limit is set via this option, +the number of results printed for the \-c option will never be larger +than this number. +.TP +.I "\-L, \-\-follow" +If testing for the existence of files (with the \-e or \-E options), +consider broken symbolic links to be non-existing. This is the default. +.TP +.I "\-\-max-database-age D" +Normally, +.B locate +will issue a warning message when it searches a database which is more +than 8 days old. This option changes that value to something other +than 8. The effect of specifying a negative value is undefined. +.TP +.I "\-m, \-\-mmap" +Accepted but does nothing, for compatibility with BSD +.BR locate . +.TP +.I "\-P, \-H, \-\-nofollow" +If testing for the existence of files (with the \-e or \-E options), treat +broken symbolic links as if they were existing files. The \-H +form of this option is provided purely for similarity with +.BR find ; +the use of \-P is recommended over \-H. +.TP +.I "\-p, \-\-print" +Print search results when they normally would not, because of the presence +of \-\-statistics (\-S) or \-\-count (\-c). +.TP +.I "\-r, \-\-regex" +The pattern specified on the command line is understood to be a +regular expression, as opposed to a glob pattern. The Regular +expressions work in the same was as in +.B emacs +except for the fact that "." will match a newline. GNU +.B find +uses the same regular expressions. +Filenames whose full paths match the specified regular expression are +printed (or, in the case of the \-c option, counted). If you wish to +anchor your regular expression at the ends of the full path name, then +as is usual with regular expressions, you should use the characters ^ +and $ to signify this. +.TP +.I "\-\-regextype R" +Use regular expression dialect R. Supported dialects +include `findutils-default', `posix-awk', `posix-basic', +`posix-egrep', `posix-extended', `posix-minimal-basic', `awk', `ed', +`egrep', `emacs', `gnu-awk', `grep' and `sed'. See the Texinfo +documentation for a detailed explanation of these dialects. +.TP +.I "\-s, \-\-stdio" +Accepted but does nothing, for compatibility with BSD +.BR locate . +.TP +.I "\-S, \-\-statistics" +Print various statistics about each locate database and then exit +without performing a search, unless non-option arguments are given. +For compatibility with BSD, \-S is accepted as a synonym +for \-\-statistics. However, the output of +.B locate \-S +is different for the GNU and BSD implementations of +.BR locate . +.TP +.I "\-\-version" +Print the version number of +.B locate +and exit. +.TP +.I "\-w, \-\-wholename" +Match against the whole name of the file as listed in the database. +This is the default. +.SH ENVIRONMENT +.TP +.B LOCATE_PATH +Colon-separated list of databases to search. If the value has a +leading or trailing colon, or has two colons in a row, you may get +results that vary between different versions of +.BR locate . +. +.SH "HISTORY" +The +.B locate +program started life as the BSD fast find program, contributed to BSD +by James A. Woods. This was described by his paper +.I Finding Files Fast +which was published in Usenix +.IR ;login: , +Vol 8, No 1, February/March, 1983, pp. 8-10. When the +.B find +program began to assume a default +.B -print +action if no action was specified, this changed the interpretation of +.B find +.BR pattern . +The BSD developers therefore moved the fast find functionality into +.BR locate . +The GNU implementation of +.B locate +appears to be derived from the same code. +.P +Significant changes to +.B locate +in reverse order: +.TS +tab(|); +LL. +4.3.7 | Byte-order independent support for old database format +4.3.3 | locate \fI\-i\fR supports multi-byte characters correctly + | Introduced \fI\-\-max_db_age\fR +4.3.2 | Support for the slocate database format +4.2.22| Introduced the \fI\-\-all\fR option +4.2.15| Introduced the \fI\-\-regex\fR option +4.2.14| Introduced options \fI\-L, \-P, \-H\fR +4.2.12| Empty items in \fBLOCATE_PATH\fR now indicate the default database +4.2.11| Introduced the \fI\-\-statistics\fR option +4.2.4 | Introduced \fI\-\-count\fR and \fI\-\-limit\fR +4.2.0 | Glob characters cause matching against the whole file name +4.0 | Introduced the LOCATE02 database format +3.7 | Locate can search multiple databases +.TE +. +.SH "BUGS" +The +.B locate +database correctly handles filenames containing newlines, +but only if the system's sort command has a working +.I \-z +option. If you suspect that +.B locate +may need to return filenames containing newlines, consider using its +.I \-\-null +option. +. +.SH "REPORTING BUGS" +GNU findutils online help: <https://www.gnu.org/software/findutils/#get-help> +.br +Report any translation bugs to <https://translationproject.org/team/> +.PP +Report any other issue via the form at the GNU Savannah bug tracker: +.RS +<https://savannah.gnu.org/bugs/?group=findutils> +.RE +General topics about the GNU findutils package are discussed at the +.I bug\-findutils +mailing list: +.RS +<https://lists.gnu.org/mailman/listinfo/bug-findutils> +.RE +. +.SH COPYRIGHT +Copyright \(co 1994-2022 Free Software Foundation, Inc. +License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>. +.br +This is free software: you are free to change and redistribute it. +There is NO WARRANTY, to the extent permitted by law. +. +.SH "SEE ALSO" +.BR find (1), +.BR updatedb (1), +.BR xargs (1), +.BR glob (3), +.BR locatedb (5) +.PP +Full documentation <https://www.gnu.org/software/findutils/locate> +.br +or available locally via: +.B info locate |