| 1 |
.TH LOCATE 1 \" -*- nroff -*- |
| 2 |
.SH NAME |
| 3 |
locate \- list files in databases that match a pattern |
| 4 |
. |
| 5 |
.SH SYNOPSIS |
| 6 |
.B locate |
| 7 |
[\-d path | \-\-database=path] |
| 8 |
[\-e | \-E | \-\-[non\-]existing] |
| 9 |
[\-i | \-\-ignore-case] |
| 10 |
[\-0 | \-\-null] |
| 11 |
[\-c | \-\-count] |
| 12 |
[\-w | \-\-wholename] |
| 13 |
[\-b | \-\-basename] |
| 14 |
[\-l N | \-\-limit=N] |
| 15 |
[\-S | \-\-statistics] |
| 16 |
[\-r | \-\-regex ] |
| 17 |
[\-\-regextype R] |
| 18 |
[\-\-max-database-age D] |
| 19 |
[\-P | \-H | \-\-nofollow] |
| 20 |
[\-L | \-\-follow] |
| 21 |
[\-\-version] |
| 22 |
[\-A | \-\-all] |
| 23 |
[\-p | \-\-print] |
| 24 |
[\-\-help] |
| 25 |
pattern... |
| 26 |
. |
| 27 |
.SH DESCRIPTION |
| 28 |
This manual page |
| 29 |
documents the GNU version of |
| 30 |
.BR locate . |
| 31 |
For each given pattern, |
| 32 |
.B locate |
| 33 |
searches one or more databases of file names and displays the |
| 34 |
file names that contain the pattern. Patterns can contain shell-style |
| 35 |
metacharacters: `*', `?', and `[]'. The metacharacters do not treat |
| 36 |
`/' or `.' specially. Therefore, a pattern `foo*bar' can match a |
| 37 |
file name that contains `foo3/bar', and a pattern `*duck*' can match a |
| 38 |
file name that contains `lake/.ducky'. Patterns that contain |
| 39 |
metacharacters should be quoted to protect them from expansion by the |
| 40 |
shell. |
| 41 |
.P |
| 42 |
If a pattern is a plain string \(em it contains no metacharacters \(em |
| 43 |
.B locate |
| 44 |
displays all file names in the database that contain that string |
| 45 |
anywhere. If a pattern does contain metacharacters, |
| 46 |
.B locate |
| 47 |
only displays file names that match the pattern exactly. As a result, |
| 48 |
patterns that contain metacharacters should usually begin with a `*', |
| 49 |
and will most often end with one as well. The exceptions are patterns |
| 50 |
that are intended to explicitly match the beginning or end of a file |
| 51 |
name. |
| 52 |
.P |
| 53 |
The file name databases contain lists of files that were on the system |
| 54 |
when the databases were last updated. The system administrator can |
| 55 |
choose the file name of the default database, the frequency with which |
| 56 |
the databases are updated, and the directories for which they contain |
| 57 |
entries; see \fBupdatedb\fP(1). |
| 58 |
.P |
| 59 |
If |
| 60 |
.BR locate 's |
| 61 |
output is going to a terminal, unusual characters in the output are |
| 62 |
escaped in the same way as for the \-print action of the |
| 63 |
.B find |
| 64 |
command. If the output is not going to a terminal, file names are |
| 65 |
printed exactly as-is. |
| 66 |
. |
| 67 |
.SH OPTIONS |
| 68 |
.TP |
| 69 |
.I "\-0, \-\-null" |
| 70 |
Use ASCII NUL as a separator, instead of newline. |
| 71 |
.TP |
| 72 |
.I "\-A, \-\-all" |
| 73 |
Print only names which match all non-option arguments, not those matching |
| 74 |
one or more non-option arguments. |
| 75 |
.TP |
| 76 |
.I "\-b, \-\-basename" |
| 77 |
Results are considered to match if the pattern specified matches the |
| 78 |
final component of the name of a file as listed in the database. |
| 79 |
This final component is usually referred to as the `base name'. |
| 80 |
.TP |
| 81 |
.I "\-c, \-\-count" |
| 82 |
Instead of printing the matched filenames, just print the total |
| 83 |
number of matches we found, unless \-\-\fIprint\fP (\-p) is also present. |
| 84 |
.TP |
| 85 |
.I "\-d \fIpath\fP, \-\-database=\fIpath\fP" |
| 86 |
Instead of searching the default file name database, search the file |
| 87 |
name databases in \fIpath\fP, which is a colon-separated list of |
| 88 |
database file names. You can also use the environment variable |
| 89 |
.B LOCATE_PATH |
| 90 |
to set the list of database files to search. |
| 91 |
The option overrides the environment variable if both are used. Empty |
| 92 |
elements in the path are taken to be synonyms for the file name of the |
| 93 |
default database. |
| 94 |
A database can be supplied on stdin, using `\-' as an element |
| 95 |
of \fIpath\fP. If more than one element of \fIpath\fP is `\-', |
| 96 |
later instances are ignored (and a warning message is printed). |
| 97 |
.IP |
| 98 |
The file name database format changed starting with GNU |
| 99 |
.B find |
| 100 |
and |
| 101 |
.B locate |
| 102 |
version 4.0 to allow machines with different byte orderings to share |
| 103 |
the databases. This version of |
| 104 |
.B locate |
| 105 |
can automatically recognize and read databases produced for older |
| 106 |
versions of GNU |
| 107 |
.B locate |
| 108 |
or Unix versions of |
| 109 |
.B locate |
| 110 |
or |
| 111 |
.BR find . |
| 112 |
Support for the old locate database format will be discontinued in a |
| 113 |
future release. |
| 114 |
.TP |
| 115 |
.I "\-e, \-\-existing" |
| 116 |
Only print out such names that currently exist (instead of such names |
| 117 |
that existed when the database was created). |
| 118 |
Note that this may slow down the program a lot, if there are many matches |
| 119 |
in the database. If you are using this option within a program, |
| 120 |
please note that it is possible for the file to be deleted after |
| 121 |
.B locate |
| 122 |
has checked that it exists, but before you use it. |
| 123 |
.TP |
| 124 |
.I "\-E, \-\-non\-existing" |
| 125 |
Only print out such names that currently do not exist (instead of such names |
| 126 |
that existed when the database was created). |
| 127 |
Note that this may slow down the program a lot, if there are many matches |
| 128 |
in the database. |
| 129 |
.TP |
| 130 |
.I "\-\-help" |
| 131 |
Print a summary of the options to |
| 132 |
.B locate |
| 133 |
and exit. |
| 134 |
.TP |
| 135 |
.I "\-i, \-\-ignore-case" |
| 136 |
Ignore case distinctions in both the pattern and the file names. |
| 137 |
.TP |
| 138 |
.I "\-l N, \-\-limit=N" |
| 139 |
Limit the number of matches to N. If a limit is set via this option, |
| 140 |
the number of results printed for the \-c option will never be larger |
| 141 |
than this number. |
| 142 |
.TP |
| 143 |
.I "\-L, \-\-follow" |
| 144 |
If testing for the existence of files (with the \-e or \-E options), |
| 145 |
consider broken symbolic links to be non-existing. This is the default. |
| 146 |
.TP |
| 147 |
.I "\-\-max-database-age D" |
| 148 |
Normally, |
| 149 |
.B locate |
| 150 |
will issue a warning message when it searches a database which is more |
| 151 |
than 8 days old. This option changes that value to something other |
| 152 |
than 8. The effect of specifying a negative value is undefined. |
| 153 |
.TP |
| 154 |
.I "\-m, \-\-mmap" |
| 155 |
Accepted but does nothing, for compatibility with BSD |
| 156 |
.BR locate . |
| 157 |
.TP |
| 158 |
.I "\-P, \-H, \-\-nofollow" |
| 159 |
If testing for the existence of files (with the \-e or \-E options), treat |
| 160 |
broken symbolic links as if they were existing files. The \-H |
| 161 |
form of this option is provided purely for similarity with |
| 162 |
.BR find ; |
| 163 |
the use of \-P is recommended over \-H. |
| 164 |
.TP |
| 165 |
.I "\-p, \-\-print" |
| 166 |
Print search results when they normally would not, because of the presence |
| 167 |
of \-\-statistics (\-S) or \-\-count (\-c). |
| 168 |
.TP |
| 169 |
.I "\-r, \-\-regex" |
| 170 |
The pattern specified on the command line is understood to be a |
| 171 |
regular expression, as opposed to a glob pattern. The Regular |
| 172 |
expressions work in the same was as in |
| 173 |
.B emacs |
| 174 |
except for the fact that "." will match a newline. GNU |
| 175 |
.B find |
| 176 |
uses the same regular expressions. |
| 177 |
Filenames whose full paths match the specified regular expression are |
| 178 |
printed (or, in the case of the \-c option, counted). If you wish to |
| 179 |
anchor your regular expression at the ends of the full path name, then |
| 180 |
as is usual with regular expressions, you should use the characters ^ |
| 181 |
and $ to signify this. |
| 182 |
.TP |
| 183 |
.I "\-\-regextype R" |
| 184 |
Use regular expression dialect R. Supported dialects |
| 185 |
include `findutils-default', `posix-awk', `posix-basic', |
| 186 |
`posix-egrep', `posix-extended', `posix-minimal-basic', `awk', `ed', |
| 187 |
`egrep', `emacs', `gnu-awk', `grep' and `sed'. See the Texinfo |
| 188 |
documentation for a detailed explanation of these dialects. |
| 189 |
.TP |
| 190 |
.I "\-s, \-\-stdio" |
| 191 |
Accepted but does nothing, for compatibility with BSD |
| 192 |
.BR locate . |
| 193 |
.TP |
| 194 |
.I "\-S, \-\-statistics" |
| 195 |
Print various statistics about each locate database and then exit |
| 196 |
without performing a search, unless non-option arguments are given. |
| 197 |
For compatibility with BSD, \-S is accepted as a synonym |
| 198 |
for \-\-statistics. However, the output of |
| 199 |
.B locate \-S |
| 200 |
is different for the GNU and BSD implementations of |
| 201 |
.BR locate . |
| 202 |
.TP |
| 203 |
.I "\-\-version" |
| 204 |
Print the version number of |
| 205 |
.B locate |
| 206 |
and exit. |
| 207 |
.TP |
| 208 |
.I "\-w, \-\-wholename" |
| 209 |
Match against the whole name of the file as listed in the database. |
| 210 |
This is the default. |
| 211 |
.SH ENVIRONMENT |
| 212 |
.TP |
| 213 |
.B LOCATE_PATH |
| 214 |
Colon-separated list of databases to search. If the value has a |
| 215 |
leading or trailing colon, or has two colons in a row, you may get |
| 216 |
results that vary between different versions of |
| 217 |
.BR locate . |
| 218 |
. |
| 219 |
.SH "HISTORY" |
| 220 |
The |
| 221 |
.B locate |
| 222 |
program started life as the BSD fast find program, contributed to BSD |
| 223 |
by James A. Woods. This was described by his paper |
| 224 |
.I Finding Files Fast |
| 225 |
which was published in Usenix |
| 226 |
.IR ;login: , |
| 227 |
Vol 8, No 1, February/March, 1983, pp. 8-10. When the |
| 228 |
.B find |
| 229 |
program began to assume a default |
| 230 |
.B -print |
| 231 |
action if no action was specified, this changed the interpretation of |
| 232 |
.B find |
| 233 |
.BR pattern . |
| 234 |
The BSD developers therefore moved the fast find functionality into |
| 235 |
.BR locate . |
| 236 |
The GNU implementation of |
| 237 |
.B locate |
| 238 |
appears to be derived from the same code. |
| 239 |
.P |
| 240 |
Significant changes to |
| 241 |
.B locate |
| 242 |
in reverse order: |
| 243 |
.TS |
| 244 |
tab(|); |
| 245 |
LL. |
| 246 |
4.3.7 | Byte-order independent support for old database format |
| 247 |
4.3.3 | locate \fI\-i\fR supports multi-byte characters correctly |
| 248 |
| Introduced \fI\-\-max_db_age\fR |
| 249 |
4.3.2 | Support for the slocate database format |
| 250 |
4.2.22| Introduced the \fI\-\-all\fR option |
| 251 |
4.2.15| Introduced the \fI\-\-regex\fR option |
| 252 |
4.2.14| Introduced options \fI\-L, \-P, \-H\fR |
| 253 |
4.2.12| Empty items in \fBLOCATE_PATH\fR now indicate the default database |
| 254 |
4.2.11| Introduced the \fI\-\-statistics\fR option |
| 255 |
4.2.4 | Introduced \fI\-\-count\fR and \fI\-\-limit\fR |
| 256 |
4.2.0 | Glob characters cause matching against the whole file name |
| 257 |
4.0 | Introduced the LOCATE02 database format |
| 258 |
3.7 | Locate can search multiple databases |
| 259 |
.TE |
| 260 |
. |
| 261 |
.SH "BUGS" |
| 262 |
The |
| 263 |
.B locate |
| 264 |
database correctly handles filenames containing newlines, |
| 265 |
but only if the system's sort command has a working |
| 266 |
.I \-z |
| 267 |
option. If you suspect that |
| 268 |
.B locate |
| 269 |
may need to return filenames containing newlines, consider using its |
| 270 |
.I \-\-null |
| 271 |
option. |
| 272 |
. |
| 273 |
.SH "REPORTING BUGS" |
| 274 |
GNU findutils online help: <https://www.gnu.org/software/findutils/#get-help> |
| 275 |
.br |
| 276 |
Report any translation bugs to <https://translationproject.org/team/> |
| 277 |
.PP |
| 278 |
Report any other issue via the form at the GNU Savannah bug tracker: |
| 279 |
.RS |
| 280 |
<https://savannah.gnu.org/bugs/?group=findutils> |
| 281 |
.RE |
| 282 |
General topics about the GNU findutils package are discussed at the |
| 283 |
.I bug\-findutils |
| 284 |
mailing list: |
| 285 |
.RS |
| 286 |
<https://lists.gnu.org/mailman/listinfo/bug-findutils> |
| 287 |
.RE |
| 288 |
. |
| 289 |
.SH COPYRIGHT |
| 290 |
Copyright \(co 1994\(en2024 Free Software Foundation, Inc. |
| 291 |
License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>. |
| 292 |
.br |
| 293 |
This is free software: you are free to change and redistribute it. |
| 294 |
There is NO WARRANTY, to the extent permitted by law. |
| 295 |
. |
| 296 |
.SH "SEE ALSO" |
| 297 |
.BR find (1), |
| 298 |
.BR updatedb (1), |
| 299 |
.BR xargs (1), |
| 300 |
.BR glob (3), |
| 301 |
.BR locatedb (5) |
| 302 |
.PP |
| 303 |
Full documentation <https://www.gnu.org/software/findutils/locate> |
| 304 |
.br |
| 305 |
or available locally via: |
| 306 |
.B info locate |