| 1 |
.TH locate 1 "Oct 2020" plocate |
| 2 |
.SH NAME |
| 3 |
plocate \- find files by name, quickly |
| 4 |
|
| 5 |
.SH SYNOPSIS |
| 6 |
.B plocate |
| 7 |
.I "[OPTION]..." |
| 8 |
.I "PATTERN..." |
| 9 |
|
| 10 |
.SH DESCRIPTION |
| 11 |
.B plocate |
| 12 |
finds all files on the system matching the given pattern (or all |
| 13 |
of the patterns if multiple are given). It does this by means of |
| 14 |
an index made by |
| 15 |
.BR updatedb (8) |
| 16 |
or (less commonly) converted from another index by |
| 17 |
.BR plocate\-build (8). |
| 18 |
|
| 19 |
plocate is largely argument-compatible with |
| 20 |
.BR mlocate (1), |
| 21 |
but is significantly |
| 22 |
faster. In particular, it rarely needs to scan through its entire |
| 23 |
database, unless the pattern is very short (less than three bytes) |
| 24 |
or you want to search for a regular expression. It does not try to |
| 25 |
maintain compatibility with BSD locate, or non-UTF-8 filenames |
| 26 |
and locales. Most I/O is done asynchronously, but the results are |
| 27 |
synchronized so that output comes in the same order every time. |
| 28 |
|
| 29 |
When multiple patterns are given, |
| 30 |
.B plocate |
| 31 |
will search for files that match |
| 32 |
.I all |
| 33 |
of them. This is the main incompatibility with |
| 34 |
.BR mlocate (1), |
| 35 |
which searches for files that match one or more patterns, unless |
| 36 |
the \-A option is given. |
| 37 |
|
| 38 |
By default, patterns are taken to be substrings to search for. |
| 39 |
If at least one non-escaped globbing metacharacter (*, ? or []) is given, |
| 40 |
that pattern is instead taken to be a glob pattern (which means it needs |
| 41 |
to start and end in * for a substring match). If |
| 42 |
.B \-\-regexp |
| 43 |
is given, patterns are instead taken to be (non-anchored) POSIX basic |
| 44 |
regular expressions, and if |
| 45 |
.B \-\-regex |
| 46 |
is given, patterns are taken to be POSIX extended regular expressions. |
| 47 |
All of this matches |
| 48 |
.BR mlocate (1) |
| 49 |
behavior. |
| 50 |
|
| 51 |
Like |
| 52 |
.BR mlocate (1), |
| 53 |
.B plocate |
| 54 |
shows all files visible to the calling user (by virtue of |
| 55 |
having read and execute permissions on all parent directories), |
| 56 |
and none that are not, by means of running with the setgid |
| 57 |
bit set to access the index (which is built as root), but by |
| 58 |
testing visibility as the calling user. |
| 59 |
|
| 60 |
.SH EXIT STATUS |
| 61 |
.B plocate |
| 62 |
exits with 0 to indicate that a match was found or that |
| 63 |
.B \-\-help |
| 64 |
or |
| 65 |
.B \-\-version |
| 66 |
were passed. Otherwise, |
| 67 |
.B plocate |
| 68 |
exits with status code 1, indicating that an error occurred or that no matches were found. |
| 69 |
|
| 70 |
.SH OPTIONS |
| 71 |
.TP |
| 72 |
\fB\-A\fR, \fB\-\-all\fR |
| 73 |
Ignored for compatibility with |
| 74 |
.BR mlocate (1). |
| 75 |
|
| 76 |
.TP |
| 77 |
\fB\-b\fR, \fB\-\-basename\fR |
| 78 |
Match only against the file name portion of the path name, |
| 79 |
ie., the directory names will be excluded from the match |
| 80 |
(but still printed). This does not speed up the search, |
| 81 |
but can suppress uninteresting matches. |
| 82 |
|
| 83 |
.TP |
| 84 |
\fB\-c\fR, \fB\-\-count\fR |
| 85 |
Do not print each match. Instead, count them, and print out a total |
| 86 |
number at the end. |
| 87 |
|
| 88 |
.TP |
| 89 |
\fB\-d\fR, \fB\-\-database\fR \fIDBPATH\fR |
| 90 |
Find matches in the given database, instead of \fB/var/lib/plocate/plocate.db\fR. |
| 91 |
This argument can be given multiple times, to search multiple databases. |
| 92 |
It is also possible to give multiple databases in one argument, separated by |
| 93 |
.BR : . |
| 94 |
(Any character, including : and \\, can be escaped by prepending a \\.) |
| 95 |
|
| 96 |
.TP |
| 97 |
\fB\-e\fR, \fB\-\-existing\fR |
| 98 |
Print only entries that refer to files existing at the time |
| 99 |
.B locate |
| 100 |
is run. Note that unlike |
| 101 |
.BR mlocate (1), |
| 102 |
symlinks are not followed by default (and indeed, there is no option |
| 103 |
to change this). |
| 104 |
|
| 105 |
.TP |
| 106 |
\fB\-i\fR, \fB\-\-ignore\-case\fR |
| 107 |
Do a case-insensitive match as given by the current locale |
| 108 |
(default is case-sensitive, byte-by-byte match). Note that |
| 109 |
.B plocate |
| 110 |
does not support the full range of Unicode case folding rules; |
| 111 |
in particular, searching for \fIß\fR will not give you matches on \fIss\fR |
| 112 |
even in a German locale. Also note that this option will be |
| 113 |
somewhat slower than a case-sensitive match, since it needs to |
| 114 |
generate more candidates for searching the index. |
| 115 |
|
| 116 |
.TP |
| 117 |
\fB\-l\fR, \fB\-\-limit\fR \fILIMIT\fR |
| 118 |
Stop searching after |
| 119 |
.I LIMIT |
| 120 |
matches have been found. If |
| 121 |
.B \-\-count |
| 122 |
is given, the number printed out will be at most \fILIMIT\fR. |
| 123 |
|
| 124 |
.TP |
| 125 |
\fB\-N\fR, \fB\-\-literal\fR |
| 126 |
Print entry names without quoting. Normally, |
| 127 |
.B plocate |
| 128 |
will escape special characters in filenames, so that they are safe for |
| 129 |
consumption by typical shells (similar to the GNU coreutils |
| 130 |
.I shell\-escape\-always |
| 131 |
quoting style), unless printing to a pipe, but this options will |
| 132 |
turn off such quoting. |
| 133 |
|
| 134 |
.TP |
| 135 |
\fB\-0\fR, \fB\-\-null\fR |
| 136 |
Instead of writing a newline after every match, write a NUL |
| 137 |
(ASCII 0). This is useful for creating unambiguous output |
| 138 |
when it is to be processed by other tools (like \fBxargs\fP(1)), as filenames are |
| 139 |
allowed to contain embedded newlines. |
| 140 |
|
| 141 |
.TP |
| 142 |
\fB\-r\fR, \fB\-\-regexp\fR |
| 143 |
Patterns are taken to be POSIX basic regular expressions. |
| 144 |
See |
| 145 |
.BR regex (7) |
| 146 |
for more information. Note that this forces a linear scan |
| 147 |
through the entire database, which is slow. |
| 148 |
|
| 149 |
.TP |
| 150 |
.B \-\-regex |
| 151 |
Like \fB\-\-regexp\fR, but patterns are instead taken to |
| 152 |
be POSIX |
| 153 |
.I extended |
| 154 |
regular expressions. |
| 155 |
|
| 156 |
.TP |
| 157 |
\fB\-w\fR, \fB\-\-wholename\fR |
| 158 |
Match against the entire path name. This is the default, |
| 159 |
so unless \fB\-b\fR is given first (see above), it will not do |
| 160 |
anything. This option thus exists only as compatibility with |
| 161 |
.BR mlocate (1). |
| 162 |
|
| 163 |
.TP |
| 164 |
.B \-\-help |
| 165 |
Print out usage information, then exit successfully. |
| 166 |
|
| 167 |
.TP |
| 168 |
.B \-\-version |
| 169 |
Print out version information, then exit successfully. |
| 170 |
|
| 171 |
.SH ENVIRONMENT |
| 172 |
|
| 173 |
.TP |
| 174 |
\fBLOCATE_PATH\fR |
| 175 |
If given, appended after the list of \fB\-\-database\fR paths |
| 176 |
(whether an explicit is given or the default is used). |
| 177 |
Colon-delimiting and character escaping follows the same rules |
| 178 |
as for \fB\-\-database\fR. |
| 179 |
|
| 180 |
.SH AUTHOR |
| 181 |
Steinar H. Gunderson <[email protected]> |
| 182 |
|
| 183 |
.SH SEE ALSO |
| 184 |
\fBplocate\-build\fP(8), |
| 185 |
\fBmlocate\fP(1), |
| 186 |
\fBupdatedb\fP(8) |