16/adplug/adplug/doc/adplugdb.1.in

   1 .\" -*- nroff -*-
   2 .\" This library is free software; you can redistribute it and/or
   3 .\" modify it under the terms of the GNU Lesser General Public
   4 .\" License as published by the Free Software Foundation; either
   5 .\" version 2.1 of the License, or (at your option) any later version.
   6 .\"
   7 .\" This library is distributed in the hope that it will be useful,
   8 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
   9 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  10 .\" Lesser General Public License for more details.
  11 .\"
  12 .\" You should have received a copy of the GNU Lesser General Public
  13 .\" License along with this library; if not, write to the Free Software
  14 .\" Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  15 .\"
  16 .TH ADPLUGDB 1 "March 4, 2006" "AdPlug database maintenance utility @VERSION@" "User Commands"
  17 .SH NAME
  18 adplugdb \- AdPlug database maintenance utility
  19 .SH SYNOPSIS
  20 .B adplugdb
  21 .RI "[OPTION]... COMMAND [ARGUMENT]..."
  22 .SH DESCRIPTION
  23 .PP
  24 \fBadplugdb\fP maintains database files in AdPlug database format. It
  25 can \fBadd\fP, \fBlist\fP and \fBremove\fP records within a central
  26 database, or \fBmerge\fP a set of databases together into one single
  27 database.
  28 .PP
  29 \fBadplugdb\fP always operates on a central database file. The
  30 location of this database file is determined by first checking if the
  31 user has a home directory. If a home directory is present, the
  32 database file will be located in \fB~/.adplug/adplug.db\fP. If a home
  33 directory is not present, a database file \fBadplug.db\fP will be
  34 looked for in the current working directory.
  35 .PP
  36 A system-wide database file can be used instead, by specifying the
  37 \fB-s\fP commandline option. The system-wide database file is located
  38 in \fB@sharedstatedir@/adplug/adplug.db\fP and may only be manipulated
  39 as the superuser. An arbitrary database file might be used as well, by
  40 specifying the \fB-d\fP commandline parameter. Only one database file
  41 may be manipulated at a time.
  42 .SH EXIT STATUS
  43 \fBadplugdb\fP returns with a successful exit status (\fB0\fP on most
  44 systems) on successful operation. An unsuccessful exit status (\fB1\fP
  45 on most systems) is returned otherwise.
  46 .SH COMMANDS
  47 .PP
  48 Commands control the main operation mode of \fBadplugdb\fP. Commands
  49 can have a number of arguments. Only one command may be specified at a
  50 time.
  51 .TP
  52 .B add
  53 This command takes a list of filenames, separated by spaces, as
  54 arguments. Each file is examined and a record is added to the
  55 database if the file is supported by AdPlug. By default, the record
  56 will be of type \fBPlain\fP, unless the \fB-t\fP commandline option is
  57 specified (see below). The default comment entry is the specified
  58 filename. If a record for a file is already in the database, it will
  59 be replaced by the new record.
  60 .TP
  61 .B list
  62 This command takes an optional list of filenames or keys, separated by
  63 spaces, as arguments. Each file is examined and the corresponding
  64 record is looked up from the database and displayed on \fBstdout\fP,
  65 in a human-readable form. If no arguments are given, all records from
  66 the database are displayed.
  67 .TP
  68 .B remove
  69 This command takes a list of filenames or keys, separated by spaces,
  70 as arguments. Each file is examined and the corresponding record is
  71 removed from the database.
  72 .TP
  73 .B merge
  74 This command takes a list of database filenames, separated by spaces,
  75 as arguments. Each database file is loaded and the contents are merged
  76 and written to the central database file. The database files are
  77 processed in the order they are specified on the commandline. Records
  78 from databases that were specified earlier take precedence over
  79 records from databases that were specified later. Records from the
  80 central database take precedence over all other records. This means
  81 that only additional records from the other databases will be added to
  82 the central database and if a record is found that is not already in
  83 the central database, the version from the earliest specified database
  84 that contains this record will be taken. In no way will records ever
  85 be overwritten in the central database.
  86 .SH OPTIONS
  87 .PP
  88 The order of the option commandline parameters is not important.
  89 .SS "Database options:"
  90 .TP
  91 .B -d <file>
  92 Specify an arbitrary file to use as the central database.
  93 .TP
  94 .B -s
  95 Use the system-wide database file as the central database. This option
  96 is only present if \fBadplugdb\fP was compiled with system-wide
  97 database file support.
  98 .TP
  99 .B -t <type>
 100 Specify a record type to be used as the type for all newly added
 101 records. Each record needs a special type to be useful to AdPlug's
 102 players. The commandline help, displayed using the \fB-h\fP
 103 commandline option, presents a list of types that may be specified.
 104 .TP
 105 .B -c
 106 Prompt for record comment. If this option is given, the user will be
 107 prompted and asked for each newly added record's comment.
 108 .TP
 109 .B -k
 110 Specify keys instead of filenames. If this option is given, all
 111 command arguments that normally are filenames are expected to be
 112 record keys instead. Each record in the database has a unique
 113 identifying key, generated from the corresponding file's contents. To
 114 manipulate a record entry, you either must have the exact same file
 115 and specify its name, or you specify the record's key, using this
 116 option. Keys are specified the same way they are displayed using the
 117 \fBlist\fP command, as CRC16:CRC32 value in hexadecimal format.
 118 .SS "Generic options:"
 119 .TP
 120 .B -q, --quiet
 121 Be more quiet.
 122 .TP
 123 .B -v, --verbose
 124 Be more verbose.
 125 .TP
 126 .B -h, --help
 127 Show summary of commandline commands, arguments and options.
 128 .TP
 129 .B -V, --version
 130 Show version and author information of the program.
 131 .SH AUTHOR
 132 Simon Peter <dn.tlp@gmx.net>