1locate(1)                   General Commands Manual                  locate(1)
2
3
4

NAME

6       plocate - find files by name, quickly
7
8

SYNOPSIS

10       plocate [OPTION]...  PATTERN...
11
12

DESCRIPTION

14       plocate  finds  all  files on the system matching the given pattern (or
15       all of the patterns if multiple are given). It does this by means of an
16       index  made  by plocate-build(8), which in turn reads the database made
17       by updatedb(8).
18
19       plocate is largely compatible with mlocate(1), and reuses its  database
20       to  create  its  index,  but is significantly faster. In particular, it
21       rarely needs to scan through its entire database, unless the pattern is
22       very  short (less than three bytes) or you want to search for a regular
23       expression. It does not try to maintain compatibility with BSD  locate,
24       or  non-UTF-8  filenames  and locales. Most I/O is done asynchronously,
25       but the results are synchronized so that output comes in the same order
26       every time.
27
28       When  multiple  patterns  are given, plocate will search for files that
29       match all of them. This is the main  incompatibility  with  mlocate(1),
30       which searches for files that match one or more patterns, unless the -a
31       option is given.
32
33       By default, patterns are taken to be substrings to search for.   If  at
34       least  one  non-escaped  globbing  metacharacter (*, ? or []) is given,
35       that pattern is instead taken to be a  glob  pattern  (which  means  it
36       needs  to  start  and  end  in * for a substring match). If --regexp is
37       given, patterns are instead taken to be (non-anchored) POSIX basic reg‐
38       ular  expressions,  and  if  --regex is given, patterns are taken to be
39       POSIX extended regular expressions.  All of this matches mlocate(1) be‐
40       havior.
41
42       Like  mlocate(1),  plocate  shows all files visible to the calling user
43       (by virtue of having read and execute permissions on all parent  direc‐
44       tories), and none that are not, by means of running with the setgid bit
45       set to access the index (which is built as root), but by testing  visi‐
46       bility as the calling user.
47
48

OPTIONS

50       -b, --basename
51              Match  only against the file name portion of the path name, ie.,
52              the directory names will be excluded from the match  (but  still
53              printed).  This  does  not speed up the search, but can suppress
54              uninteresting matches.
55
56
57       -c, --count
58              Do not print each match. Instead, count them, and  print  out  a
59              total number at the end.
60
61
62       -d, --database DBPATH
63              Find  matches  in  the  given database, instead of /var/lib/plo‐
64              cate/plocate.db.  This argument can be given multiple times,  to
65              search multiple databases.  It is also possible to give multiple
66              databases in one argument, separated by :.  (Any character,  in‐
67              cluding : and \, can be escaped by prepending a \.)
68
69
70       -e, --existing
71              Print  only entries that refer to files existing at the time lo‐
72              cate is run. Note that unlike mlocate(1), symlinks are not  fol‐
73              lowed  by  default  (and  indeed,  there  is no option to change
74              this).
75
76
77       -i, --ignore-case
78              Do a case-insensitive match as given by the current locale  (de‐
79              fault  is case-sensitive, byte-by-byte match). Note that plocate
80              does not support the full range of Unicode case  folding  rules;
81              in  particular,  searching for ß will not give you matches on ss
82              even in a German locale. Also note  that  this  option  will  be
83              somewhat  slower  than a case-sensitive match, since it needs to
84              generate more candidates for searching the index.
85
86
87       -l, --limit LIMIT
88              Stop searching after LIMIT matches have been found.  If  --count
89              is given, the number printed out will be at most LIMIT.
90
91
92       -N, --literal
93              Print entry names without quoting. Normally, plocate will escape
94              special characters in filenames, so that they are safe for  con‐
95              sumption  by typical shells (similar to the GNU coreutils shell-
96              escape-always quoting style), unless printing  to  a  pipe,  but
97              this options will turn off such quoting.
98
99
100       -0, --null
101              Instead  of  writing  a  newline  after every match, write a NUL
102              (ASCII 0). This is useful for creating unambiguous  output  when
103              it  is  to be processed by other tools (like xargs(1)), as file‐
104              names are allowed to contain embedded newlines.
105
106
107       -r, --regexp
108              Patterns are taken to be POSIX basic regular  expressions.   See
109              regex(7)  for  more  information. Note that this forces a linear
110              scan through the entire database, which is slow.
111
112
113       --regex
114              Like --regexp, but patterns are instead taken to  be  POSIX  ex‐
115              tended regular expressions.
116
117
118       -w, --wholename
119              Match  against the entire path name. This is the default, so un‐
120              less -b is given first (see above), it  will  not  do  anything.
121              This option thus exists only as compatibility with mlocate(1).
122
123
124       --help Print out usage information, then exit successfully.
125
126
127       --version
128              Print out version information, then exit successfully.
129
130

ENVIRONMENT

132       LOCATE_PATH
133              If  given,  appended after the list of --database paths (whether
134              an explicit is given or the default is used).   Colon-delimiting
135              and character escaping follows the same rules as for --database.
136
137

AUTHOR

139       Steinar H. Gunderson <steinar+plocate@gunderson.no>
140
141

SEE ALSO

143       plocate-build(8), mlocate(1), updatedb(8)
144
145
146
147plocate                            Oct 2020                          locate(1)
Impressum