From c4d3a7eb75a36921310731ca6e85fe2a5d65c0fa Mon Sep 17 00:00:00 2001 From: "Steinar H. Gunderson" Date: Sun, 11 Oct 2020 10:07:38 +0200 Subject: [PATCH] Add some man pages. --- meson.build | 2 + plocate-build.8 | 59 ++++++++++++++++++++++ plocate.1 | 127 ++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 188 insertions(+) create mode 100644 plocate-build.8 create mode 100644 plocate.1 diff --git a/meson.build b/meson.build index a37a89f..5bf6d99 100644 --- a/meson.build +++ b/meson.build @@ -23,6 +23,8 @@ executable('plocate-build', 'plocate-build.cpp', install_data('update-plocate.sh', install_dir: '/etc/cron.daily', rename: 'plocate') +install_man('plocate.1') +install_man('plocate-build.8') # Requires having TurboPFor checked out, so not built by default. # Unless you have a recent Meson, there's no apparently good way diff --git a/plocate-build.8 b/plocate-build.8 new file mode 100644 index 0000000..79b0a17 --- /dev/null +++ b/plocate-build.8 @@ -0,0 +1,59 @@ +.TH plocate-build 1 "Oct 2020" plocate-build +.SH NAME +plocate-build \- generate index for plocate + +.SH SYNOPSIS +.B plocate-build +.I "[OPTION]..." +.I "MLOCATE_DB" +.I "PLOCATE_DB" + +.SH DESCRIPTION +.B plocate-build +creates an index from +.BR plocate (1) +from an index earlier generated by +.BR updatedb (1) +from the +.BR mlocate (1) +package. This is currently the only way to build such an index. +If +.I MLOCATE_DB +already exists, it will be overwritten (non-atomically). The file is +created such that it is not world-readable, as the final access check +is done by +.BR plocate (1) +during the search. + +.SH OPTIONS +.TP +\fB\-b\fR, \fB\-\-block\-size\fR \fISIZE\fR +Create blocks containing +.I SIZE +filenames each, compress them together, and treat them as the same element +in the posting lists. This makes the index smaller (because the compression +algorithm gets more context to work with, and because there are fewer elements +in each posting list), but also makes posting lists less precise, moving more +work to weeding out false positives after posting list intersection. + +Making this number larger will make linear search (for \fB\-\-regex\fR, +or very short patterns) faster, with diminishing returns around 256 filenames +per block. However, making it too large will cause more false positives, +reducing overall performance for typical queries. The default value is 32. +Setting it to 1 makes one (compressed) block per filename. + +.TP +.B \-\-help +Print out usage information, then exit successfully. + +.TP +.B \-\-version +Print out version information, then exit successfully. + +.SH AUTHOR +Steinar H. Gunderson + +.SH SEE ALSO +\fBplocate\fP(1), +\fB/etc/cron.daily/plocate\fR (which is called +\fBupdate-plocate.sh\fR in the source distribution) diff --git a/plocate.1 b/plocate.1 new file mode 100644 index 0000000..e58ad58 --- /dev/null +++ b/plocate.1 @@ -0,0 +1,127 @@ +.TH locate 1 "Oct 2020" plocate +.SH NAME +plocate \- find files by name, quickly + +.SH SYNOPSIS +.B plocate +.I "[OPTION]..." +.I "PATTERN..." + +.SH DESCRIPTION +.B 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 +.BR plocate-build (8), +which in turn reads the database made by +.BR updatedb (8). + +plocate is largely compatible with +.BR mlocate (1), +and reuses its database to create its index, 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, +.B plocate +will search for files that match +.I all +of them. This is the main incompatibility with +.BR 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 +.B --regexp +is given, patterns are instead taken to be (non-anchored) POSIX basic +regular expressions, and if +.B --regex +is given, patterns are taken to be POSIX extended regular expressions. +All of this matches +.BR mlocate (1) +behavior. + +Like +.BR mlocate(1), +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. + +.SH OPTIONS +.TP +\fB\-c\fR, \fB\-\-count\fR +Do not print each match. Instead, count them, and print out a total +number at the end. + +.TP +\fB\-d\fR, \fB\-\-database\fR \fIDBPATH\fR +Find matches in \fB/var/lib/mlocate/plocate.db\fR, instead of the given database. +( +.B plocate +does not currently support multiple databases.) + +.TP +\fB\-i\fR, \fB\-\-ignore\-case\fR +Do a case-insensitive match as given by the current locale +(default is case-sensitive, byte-by-byte match). Note that +.B plocate +does not support the full range of Unicode case folding rules; +in particular, searching for \fIß\fR will not give you matches on \fIss\fR +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. + +.TP +\fB\-l\fR, \fB\-\-limit\fR \fILIMIT\fR +Stop searching after +.I LIMIT +matches have been found. If +.B \-\-count +is given, the number printed out will be at most \fILIMIT\fR. + +.TP +\fB\-0\fR, \fB\-\-null\fR +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 \fBxargs\fP(1)), as filenames are +allowed to contain embedded newlines. + +.TP +\fB\-r\fR, \fB\-\-regexp\fR +Patterns are taken to be POSIX basic regular expressions. +See +.BR regex(7) +for more information. Note that this forces a linear scan +through the entire database, which is slow. + +.TP +.B \-\-regex +Like \fB\-\-regexp\fR, but patterns are instead taken to +be POSIX +.I extended +regular expressions. + +.TP +.B \-\-help +Print out usage information, then exit successfully. + +.TP +.B \-\-version +Print out version information, then exit successfully. + +.SH AUTHOR +Steinar H. Gunderson + +.SH SEE ALSO +\fBplocate-build\fP(8), +\fBmlocate\fP(1), +\fBupdatedb\fP(8) -- 2.39.2