NAME

       plocate - find files by name, quickly

SYNOPSIS

       plocate [OPTION]...  PATTERN...

DESCRIPTION

       plocate  finds all files on the system matching the given pattern (or all of the patterns if multiple are
       given). It does this by means of an index made by updatedb(8) or (less commonly) converted  from  another
       index by plocate-build(8).

       plocate  is  largely  argument-compatible with mlocate(1), but is significantly faster. In particular, it
       rarely needs to scan through its entire database, unless the pattern  is  very  short  (less  than  three
       bytes) or you want to search for a regular expression. It does not try to maintain compatibility with BSD
       locate,  or  non-UTF-8  filenames  and  locales.  Most  I/O  is  done asynchronously, but the results are
       synchronized so that output comes in the same order every time.

       When multiple patterns are given, plocate will search for files that match all of them. This is the  main
       incompatibility  with mlocate(1), which searches for files that match one or more patterns, unless the -A
       option is given.

       By default, patterns are taken to be substrings to search for.  If  at  least  one  non-escaped  globbing
       metacharacter  (*,  ? or []) is given, that pattern is instead taken to be a glob pattern (which means it
       needs to start and end in * for a substring match). If --regexp is given, patterns are instead  taken  to
       be  (non-anchored)  POSIX  basic  regular  expressions, and if --regex is given, patterns are taken to be
       POSIX extended regular expressions.  All of this matches mlocate(1) behavior.

       Like mlocate(1), plocate shows all files visible to the calling  user  (by  virtue  of  having  read  and
       execute  permissions  on  all  parent  directories),  and none that are not, by means of running with the
       setgid bit set to access the index (which is built as root), but by testing  visibility  as  the  calling
       user.

EXIT STATUS

       plocate  exits  with  0  to  indicate  that  a  match  was found or that --help or --version were passed.
       Otherwise, plocate exits with status code 1, indicating that an error occurred or that  no  matches  were
       found.

OPTIONS

       -A, --all
              Ignored for compatibility with mlocate(1).

       -b, --basename
              Match  only  against  the  file  name  portion  of the path name, ie., the directory names will be
              excluded from the match (but still printed). This does not speed up the search, but  can  suppress
              uninteresting matches.

       -c, --count
              Do not print each match. Instead, count them, and print out a total number at the end.

       -d, --database DBPATH
              Find  matches in the given database, instead of /var/lib/plocate/plocate.db.  This argument can be
              given multiple times, to search  multiple  databases.   It  is  also  possible  to  give  multiple
              databases  in  one argument, separated by :.  (Any character, including : and \, can be escaped by
              prepending a \.)

       -e, --existing
              Print only entries that refer to files existing at the  time  locate  is  run.  Note  that  unlike
              mlocate(1), symlinks are not followed by default (and indeed, there is no option to change this).

       -i, --ignore-case
              Do  a  case-insensitive  match as given by the current locale (default is case-sensitive, byte-by-
              byte match). Note that plocate does not support the full range of Unicode case folding  rules;  in
              particular,  searching  for  ß  will not give you matches on ss even in a German locale. Also note
              that this option will be somewhat slower than a case-sensitive match, since it needs  to  generate
              more candidates for searching the index.

       -p, --ignore-spaces
              Ignore punctuation and spaces when matching patterns.

       -l, --limit LIMIT
              Stop  searching  after  LIMIT matches have been found. If --count is given, the number printed out
              will be at most LIMIT.

       -N, --literal
              Print entry names without quoting. Normally, plocate will escape special characters in  filenames,
              so  that  they  are  safe  for  consumption by typical shells (similar to the GNU coreutils shell-
              escape-always quoting style), unless printing to a pipe, but  this  options  will  turn  off  such
              quoting.

       -0, --null
              Instead of writing a newline after every match, write a NUL (ASCII 0). This is useful for creating
              unambiguous  output  when  it  is to be processed by other tools (like xargs(1)), as filenames are
              allowed to contain embedded newlines.

       -r, --regexp
              Patterns are taken to be POSIX basic regular expressions.  See regex(7) for more information. Note
              that this forces a linear scan through the entire database, which is slow.

       --regex
              Like --regexp, but patterns are instead taken to be POSIX extended regular expressions.

       -w, --wholename
              Match against the entire path name. This is the default, so unless -b is given first (see  above),
              it will not do anything. This option thus exists only as compatibility with mlocate(1).

       --help Print out usage information, then exit successfully.

       --version
              Print out version information, then exit successfully.

ENVIRONMENT

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

AUTHOR

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

SEE ALSO

       plocate-build(8), mlocate(1), updatedb(8)

plocate                                             Oct 2020                                           locate(1)