From 05252f095a1315bfc6283f7a820657b48039e53f Mon Sep 17 00:00:00 2001 From: "Steinar H. Gunderson" Date: Wed, 2 Dec 2020 23:51:55 +0100 Subject: [PATCH] Add missing man page .in files. --- updatedb.8.in | 199 +++++++++++++++++++++++++++++++++++++++++++++ updatedb.conf.5.in | 138 +++++++++++++++++++++++++++++++ 2 files changed, 337 insertions(+) create mode 100644 updatedb.8.in create mode 100644 updatedb.conf.5.in diff --git a/updatedb.8.in b/updatedb.8.in new file mode 100644 index 0000000..3aba2c2 --- /dev/null +++ b/updatedb.8.in @@ -0,0 +1,199 @@ +.\" A man page for updatedb(8). -*- nroff -*- +.\" +.\" Copyright (C) 2005, 2007, 2008 Red Hat, Inc. All rights reserved. +.\" +.\" This copyrighted material is made available to anyone wishing to use, +.\" modify, copy, or redistribute it subject to the terms and conditions of the +.\" GNU General Public License v.2. +.\" +.\" This program is distributed in the hope that it will be useful, but WITHOUT +.\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or +.\" FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for +.\" more details. +.\" +.\" You should have received a copy of the GNU General Public License along +.\" with this program; if not, write to the Free Software Foundation, Inc., +.\" 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. +.\" +.\" Author: Miloslav Trmac +.TH updatedb 8 "Dec 2020" plocate + +.SH NAME +updatedb \- update a database for plocate + +.SH SYNOPSIS + +\fBupdatedb\fR [\fIOPTION\fR]... + +.SH DESCRIPTION +.B updatedb +creates or updates a database used by +.BR locate (1). +If the database already exists, +its data is reused +to avoid rereading directories that have not changed. + +.B updatedb +is usually run daily from a +.BR systemd.timer (8) +to update the default database. + +.SH EXIT STATUS +.B updatedb +returns with exit status 0 on success, 1 on error. + +.SH OPTIONS +The \fBPRUNE_BIND_MOUNTS\fR, \fBPRUNEFS\fR, +.B PRUNENAMES +and +.B PRUNEPATHS +variables, which are modified by some of the options, are documented in detail +in +.BR updatedb.conf (5). + +.TP +\fB\-f\fR, \fB\-\-add-prunefs\fB \fIFS\fR +Add entries in white-space-separated list \fIFS\fR to \fBPRUNEFS\fR. + +.TP +\fB\-n\fR, \fB\-\-add-prunenames\fB \fINAMES\fR +Add entries in white-space-separated list \fINAMES\fR to \fBPRUNENAMES\fR. + +.TP +\fB\-e\fR, \fB\-\-add-prunepaths\fB \fIPATHS\fR +Add entries in white-space-separated list \fIPATHS\fR to \fBPRUNEPATHS\fR. + +.TP +\fB\-U\fR, \fB\-\-database\-root\fR \fIPATH\fR +Store only results of scanning the file system subtree rooted at \fIPATH\fR to +the generated database. +The whole file system is scanned by default. + +.BR locate (1) +outputs entries as absolute path names which don't contain symbolic links, +regardless of the form of \fIPATH\fR. + +.TP +\fB\-\-debug\-pruning\fR +Write debugging information about pruning decisions to standard error output. + +.TP +\fB\-h\fR, \fB\-\-help\fR +Write a summary of the available options to standard output +and exit successfully. + +.TP +\fB\-o\fR, \fB\-\-output\fR \fIFILE\fR +Write the database to +.I FILE +instead of using the default database. + +.TP +\fB\-\-prune\-bind\-mounts\fR \fIFLAG\fR +Set +.B PRUNE_BIND_MOUNTS +to \fIFLAG\fR, overriding the configuration file. + +.TP +\fB\-\-prunefs\fR \fIFS\fR +Set \fBPRUNEFS\fR to \fIFS\fR, overriding the configuration file. + +.TP +\fB\-\-prunenames\fR \fINAMES\fR +Set \fBPRUNENAMES\fR to \fINAMES\fR, overriding the configuration file. + +.TP +\fB\-\-prunepaths\fR \fIPATHS\fR +Set \fBPRUNEPATHS\fR to \fIPATHS\fR, overriding the configuration file. + +.TP +\fB\-l\fR, \fB\-\-require\-visibility\fR \fIFLAG\fR +Set the \*(lqrequire file visibility before reporting it\*(rq flag in the +generated database to \fIFLAG\fR. + +If +.I FLAG +is +.B 0 +or \fBno\fR, +or if the database file is readable by "others" +or it is not owned by \fB@groupname@\fR, +.BR locate (1) +outputs the database entries even if the user running +.BR locate (1) +could not have read the directory necessary to find out the file described +by the database entry. + +If +.I FLAG +is +.B 1 +or +.B yes +(the default), +.BR locate (1) +checks the permissions of parent directories of each entry +before reporting it to the invoking user. +To make the file existence truly hidden from other users, the database +group is set to +.B @groupname@ +and the database permissions prohibit reading the database by users using +other means than +.BR locate (1), +which is set-gid \fB@groupname@\fR. + +Note that the visibility flag is checked only if the database is owned by +.B @groupname@ +and it is not readable by "others". + +.TP +\fB\-v\fR, \fB\-\-verbose\fR +Output path names of files to standard output, as soon as they are found. + +.TP +\fB\-V\fR, \fB\-\-version\fR +Write information about the version and license of +.B locate +on standard output and exit successfully. + +.SH EXAMPLES +To create a private mlocate database as an user other than \fBroot\fR, +run +.RS +.B updatedb -l 0 \-o +.I db_file +.B \-U +.I source_directory +.RE +Note that all users that can read +.I db_file +can get the complete list of files in the subtree of \fIsource_directory\fR. + +.SH FILES +.TP +\fB@updatedb_conf@\fR +A configuration file. See +.BR updatedb.conf (5). + +.TP +\fB@dbfile@\fR +The database updated by default. Uses exactly the same format +as the one used by +.BR mlocate (1)'s +updatedb, so they can be shared. + +.SH SECURITY +Databases built with +.B \-\-require\-visibility no +allow users to find names of files and directories of other users, +which they would not otherwise be able to do. + +.SH AUTHOR +Miloslav Trmac +.P +Steinar H. Gunderson + +.SH SEE ALSO +.BR locate (1), +.BR mlocate.db (5), +.BR updatedb.conf (5) diff --git a/updatedb.conf.5.in b/updatedb.conf.5.in new file mode 100644 index 0000000..dd11fa9 --- /dev/null +++ b/updatedb.conf.5.in @@ -0,0 +1,138 @@ +.\" A man page for updatedb.conf. -*- nroff -*- +.\" +.\" Copyright (C) 2005, 2007, 2008 Red Hat, Inc. All rights reserved. +.\" +.\" This copyrighted material is made available to anyone wishing to use, +.\" modify, copy, or redistribute it subject to the terms and conditions of the +.\" GNU General Public License v.2. +.\" +.\" This program is distributed in the hope that it will be useful, but WITHOUT +.\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or +.\" FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for +.\" more details. +.\" +.\" You should have received a copy of the GNU General Public License along +.\" with this program; if not, write to the Free Software Foundation, Inc., +.\" 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. +.\" +.\" Author: Miloslav Trmac +.TH updatedb.conf 5 "Oct 2020" plocate + +.SH NAME +@updatedb_conf@ \- a configuration file for updatedb(8) + +.SH DESCRIPTION +.B @updatedb_conf@ +is a text file. +Blank lines are ignored. +A +.B # +character outside of a quoted string starts a comment +extending until end of line. + +Other lines must be of the following form: +.RS +.I VARIABLE +.B = +\fB"\fIVALUE\fB"\fR +.RE + +White space between tokens is ignored. +.I VARIABLE +is an alphanumeric string which does not start with a digit. +.I VALUE +can contain any character except for \fB\(dq\fR. +No escape mechanism is supported within +.I VALUE +and there is no way to write +.I VALUE +spanning more than one line. + +Unknown +.I VARIABLE +values are considered an error. +The defined variables are: + +.TP +\fBPRUNEFS\fR +A whitespace-separated list of file system types (as used in \fB/etc/mtab\fR) +which should not be scanned by +.BR updatedb (8). +The file system type matching is case-insensitive. By default, no file system +types are skipped. + +When scanning a file system is skipped, +all file systems mounted in the subtree are skipped too, +even if their type does not match any entry in \fBPRUNEFS\fR. + +.TP +\fBPRUNENAMES\fR +A whitespace-separated list of directory names (without paths) which should not +be scanned by +.BR updatedb (8). +By default, no directory names are skipped. + +Note that only directories can be specified, and no pattern mechanism (e.g. +globbing) is used. + +.TP +\fBPRUNEPATHS\fR +A whitespace-separated list of path names of directories which should not be +scanned by +.BR updatedb (8). +Each path name must be exactly in the form +in which the directory would be reported by +.BR locate (1). + +By default, no paths are skipped. + +.TP +\fBPRUNE_BIND_MOUNTS\fR +One of the strings \fB0\fR, \fBno\fR, \fB1\fR or \fByes\fR. +If +.B PRUNE_BIND_MOUNTS +is \fB1\fR or \fByes\fR, +bind mounts are not scanned by +.BR updatedb (8). +All file systems mounted in the subtree of a bind mount are skipped as well, +even if they are not bind mounts. +As an exception, bind mounts of a directory on itself are not skipped. + +By default, bind mounts are not skipped. + +.SH NOTES +When a directory is matched by \fBPRUNEFS\fR, \fBPRUNENAMES\fR or +\fBPRUNEPATHS\fR, +.BR updatedb (8) +does not scan the contents of the directory. +The path of the directory itself is, however, entered in the created database. +For example, if +.I /tmp +is in \fBPRUNEPATHS\fR, +.BR locate (1) +will not show any files stored in \fI/tmp\fR, +but it can show the +.I /tmp +directory. +This behavior differs from traditional +.B locate +implementations. + +In some +.BR updatedb (8) +implementations \fBPRUNEPATHS\fR can be used to exclude non-directory files. +This is not the case in this implementation. + +.B @updatedb_conf@ +is a shell script in some implementations, +which allows much more flexibility in defining the variables. +Equivalent functionality can be achieved by using the command-line options +to +.BR updatedb (8). + +.SH AUTHOR +Miloslav Trmac + +.SH SEE ALSO +.BR locate (1), +.BR updatedb (8) -- 2.39.2