.\" -*- nroff -*-
.\" This library is free software; you can redistribute it and/or
.\" modify it under the terms of the GNU Lesser General Public
.\" License as published by the Free Software Foundation; either
.\" version 2.1 of the License, or (at your option) any later version.
.\"
.\" This library 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
.\" Lesser General Public License for more details.
.\"
.\" You should have received a copy of the GNU Lesser General Public
.\" License along with this library; if not, write to the Free Software
.\" Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
.\"
.TH ADPLUGDB 1 "March 4, 2006" "AdPlug database maintenance utility @VERSION@" "User Commands"
.SH NAME
adplugdb \- AdPlug database maintenance utility
.SH SYNOPSIS
.B adplugdb
.RI "[OPTION]... COMMAND [ARGUMENT]..."
.SH DESCRIPTION
.PP
\fBadplugdb\fP maintains database files in AdPlug database format. It
can \fBadd\fP, \fBlist\fP and \fBremove\fP records within a central
database, or \fBmerge\fP a set of databases together into one single
database.
.PP
\fBadplugdb\fP always operates on a central database file. The
location of this database file is determined by first checking if the
user has a home directory. If a home directory is present, the
database file will be located in \fB~/.adplug/adplug.db\fP. If a home
directory is not present, a database file \fBadplug.db\fP will be
looked for in the current working directory.
.PP
A system-wide database file can be used instead, by specifying the
\fB-s\fP commandline option. The system-wide database file is located
in \fB@sharedstatedir@/adplug/adplug.db\fP and may only be manipulated
as the superuser. An arbitrary database file might be used as well, by
specifying the \fB-d\fP commandline parameter. Only one database file
may be manipulated at a time.
.SH EXIT STATUS
\fBadplugdb\fP returns with a successful exit status (\fB0\fP on most
systems) on successful operation. An unsuccessful exit status (\fB1\fP
on most systems) is returned otherwise.
.SH COMMANDS
.PP
Commands control the main operation mode of \fBadplugdb\fP. Commands
can have a number of arguments. Only one command may be specified at a
time.
.TP
.B add
This command takes a list of filenames, separated by spaces, as
arguments. Each file is examined and a record is added to the
database if the file is supported by AdPlug. By default, the record
will be of type \fBPlain\fP, unless the \fB-t\fP commandline option is
specified (see below). The default comment entry is the specified
filename. If a record for a file is already in the database, it will
be replaced by the new record.
.TP
.B list
This command takes an optional list of filenames or keys, separated by
spaces, as arguments. Each file is examined and the corresponding
record is looked up from the database and displayed on \fBstdout\fP,
in a human-readable form. If no arguments are given, all records from
the database are displayed.
.TP
.B remove
This command takes a list of filenames or keys, separated by spaces,
as arguments. Each file is examined and the corresponding record is
removed from the database.
.TP
.B merge
This command takes a list of database filenames, separated by spaces,
as arguments. Each database file is loaded and the contents are merged
and written to the central database file. The database files are
processed in the order they are specified on the commandline. Records
from databases that were specified earlier take precedence over
records from databases that were specified later. Records from the
central database take precedence over all other records. This means
that only additional records from the other databases will be added to
the central database and if a record is found that is not already in
the central database, the version from the earliest specified database
that contains this record will be taken. In no way will records ever
be overwritten in the central database.
.SH OPTIONS
.PP
The order of the option commandline parameters is not important.
.SS "Database options:"
.TP
.B -d <file>
Specify an arbitrary file to use as the central database.
.TP
.B -s
Use the system-wide database file as the central database. This option
is only present if \fBadplugdb\fP was compiled with system-wide
database file support.
.TP
.B -t <type>
Specify a record type to be used as the type for all newly added
records. Each record needs a special type to be useful to AdPlug's
players. The commandline help, displayed using the \fB-h\fP
commandline option, presents a list of types that may be specified.
.TP
.B -c
Prompt for record comment. If this option is given, the user will be
prompted and asked for each newly added record's comment.
.TP
.B -k
Specify keys instead of filenames. If this option is given, all
command arguments that normally are filenames are expected to be
record keys instead. Each record in the database has a unique
identifying key, generated from the corresponding file's contents. To
manipulate a record entry, you either must have the exact same file
and specify its name, or you specify the record's key, using this
option. Keys are specified the same way they are displayed using the
\fBlist\fP command, as CRC16:CRC32 value in hexadecimal format.
.SS "Generic options:"
.TP
.B -q, --quiet
Be more quiet.
.TP
.B -v, --verbose
Be more verbose.
.TP
.B -h, --help
Show summary of commandline commands, arguments and options.
.TP
.B -V, --version
Show version and author information of the program.
.SH AUTHOR
Simon Peter <dn.tlp@gmx.net>
