mirror of
https://https.git.savannah.gnu.org/git/findutils.git
synced 2026-01-26 15:39:06 +00:00
3c2af8a185
The .HP macro introduced only recently triggers a 'make check' errors: env GROFF=groff ../build-aux/man-lint.sh . find.1 check_manpages_format_without_error_messages ( find.1): OK check_manpages_with_groff_checkstyle_2 ( find.1): FAILED an.tmac:./find.1:23: style: use of deprecated macro: .HP make[3]: *** [Makefile:3112: findutils-check-manpages] Error 1 and env GROFF=groff ../build-aux/man-lint.sh . locate.1 updatedb.1 locatedb.5 check_manpages_format_without_error_messages ( locate.1): OK check_manpages_format_without_error_messages ( updatedb.1): OK check_manpages_format_without_error_messages ( locatedb.5): OK check_manpages_with_groff_checkstyle_2 ( locate.1): FAILED an.tmac:./locate.1:18: style: use of deprecated macro: .HP make[3]: *** [Makefile:3287: findutils-check-manpages] Error 1 make[3]: Target 'check-local' not remade because of errors. The HP hanging paragraph would work nicely, but is marked as deprecated in groff-1.23; the deprecations warning will disappear in groff-1.24. Until then, use .TP instead to avoid the check errors. * find/find.1: Change '.HP' to the '.TP' tagged paragraph macro. Add a FIXME for 2027 to switch to .HP when groff-1.24 is more commonly available. * locate/locate.1: Likewise.
373 lines
11 KiB
Groff
373 lines
11 KiB
Groff
.TH LOCATE 1 2020-12-27 findutils \" -*- nroff -*-
|
|
.\" As a GNU troff extension, \% at the beginning of a word suppresses
|
|
.\" its hyphenation.
|
|
.ie \n(.g \{\
|
|
. ds ^ \(ha
|
|
. ds en \(en
|
|
. ds % \%
|
|
.\}
|
|
.el \{\
|
|
. ds ^ ^
|
|
. ds en \-
|
|
. ds % \" empty
|
|
.\}
|
|
.SH NAME
|
|
locate \- list files in databases that match a pattern
|
|
.
|
|
.SH SYNOPSIS
|
|
.TP \" FIXME-2027: switch to .HP when groff-1.24 is more commonly available.
|
|
.nr sA \n(.j \" Save the adjustment mode.
|
|
.na
|
|
.B locate
|
|
.RB [ \-d\ \c
|
|
.I path
|
|
|
|
|
.BI \*%\-\-database= path\c
|
|
]
|
|
.RB [ \-e
|
|
|
|
|
.B \-E
|
|
|
|
|
.BR \*%\-\- [ non\- ] existing ]
|
|
.RB [ \-i
|
|
|
|
|
.BR \*%\-\-ignore\-case ]
|
|
.RB [ \-0
|
|
|
|
|
.BR \-\-null ]
|
|
.RB [ \-c
|
|
|
|
|
.BR \*%\-\-count ]
|
|
.RB [ \-w
|
|
|
|
|
.BR \*%\-\-wholename ]
|
|
.RB [ \-b
|
|
|
|
|
.BR \*%\-\-basename ]
|
|
.RB [ \-l\ \c
|
|
.I N
|
|
|
|
|
.BI \*%\-\-limit= N\c
|
|
]
|
|
.RB [ \-S
|
|
|
|
|
.BR \*%\-\-statistics ]
|
|
.RB [ \-r
|
|
|
|
|
.BR \*%\-\-regex ]
|
|
.RB \*%[ \-\-regextype\ \c
|
|
.IR R ]
|
|
.RB \*%[ \-\-max\-database\-age\ \c
|
|
.IR D ]
|
|
.RB [ \-P
|
|
|
|
|
.B \-H
|
|
|
|
|
.BR \*%\-\-nofollow ]
|
|
.RB [ \-L
|
|
|
|
|
.BR \*%\-\-follow ]
|
|
.RB \*%[ \-\-version ]
|
|
.RB [ \-A
|
|
|
|
|
.BR \-\-all ]
|
|
.RB [ \-p
|
|
|
|
|
.BR \*%\-\-print ]
|
|
.RB \*%[ \-\-help ]
|
|
.IR pattern .\|.\|.
|
|
.ad \n(sA \" Restore the adjustment mode.
|
|
.rr sA
|
|
.
|
|
.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 standard input, 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:
|
|
.P
|
|
.TS
|
|
tab(|);
|
|
LL.
|
|
4.3.7|T{
|
|
.na
|
|
Byte-order independent support for old database format
|
|
T}
|
|
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|T{
|
|
.na
|
|
Empty items in \fBLOCATE_PATH\fR now indicate the default database
|
|
T}
|
|
4.2.11|Introduced the \fI\-\-statistics\fR option
|
|
4.2.4|Introduced \fI\-\-count\fR and \fI\-\-limit\fR
|
|
4.2.0|T{
|
|
.na
|
|
Glob characters cause matching against the whole file name
|
|
T}
|
|
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\*(en2026 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
|