summaryrefslogtreecommitdiffabout
path: root/doc
authorSergey Poznyakoff <gray@gnu.org.ua>2013-05-08 16:27:01 (GMT)
committer Sergey Poznyakoff <gray@gnu.org.ua>2013-05-08 16:27:01 (GMT)
commit6658f41e38fec9e007a0fbd0883e030f6337e28d (patch) (side-by-side diff)
treed7ecc0b72b23a01a2bfa10e8a7bb184d704269dc /doc
parentc0cba983ab0c0bc1de630a200f902189ddddff09 (diff)
downloadgdbm-6658f41e38fec9e007a0fbd0883e030f6337e28d.tar.gz
gdbm-6658f41e38fec9e007a0fbd0883e030f6337e28d.tar.bz2
Rename testgdbm to gdbmtool. Improve documentation.
* configure.ac: Fix a typo. * src/.cvsignore: Add gdbmtool * src/Makefile.am: Rename testgdbm to gdbmtool. Source file not renamed because of CVS deficiency. * src/gdbm_dump.c: Enable NLS. * src/gdbm_load.c: Likewise. * src/testgdbm.c: New option -q (--quiet). New command: prompt. * doc/Makefile.am (man_MANS): Add new manpages. * doc/gdbmtool.1: New file. * doc/gdbm_load.1: New file. * doc/gdbm_dump.1: New file. * doc/gdbm.3: Update. * doc/gdbm.texinfo: Update.
Diffstat (limited to 'doc') (more/less context) (ignore whitespace changes)
-rw-r--r--doc/Makefile.am2
-rw-r--r--doc/gdbm.329
-rw-r--r--doc/gdbm.texinfo134
-rw-r--r--doc/gdbm_dump.188
-rw-r--r--doc/gdbm_load.196
-rw-r--r--doc/gdbmtool.1245
6 files changed, 510 insertions, 84 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am
index f4059d0..223c892 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -17,13 +17,13 @@
# Documentation
info_TEXINFOS = gdbm.texinfo
gdbm_TEXINFOS=\
fdl.texi
-man_MANS = gdbm.3
+man_MANS = gdbm.3 gdbm_dump.1 gdbm_load.1 gdbmtool.1
EXTRA_DIST = $(man_MANS)
GENDOCS=gendocs.sh
TEXI2DVI=texi2dvi -E
diff --git a/doc/gdbm.3 b/doc/gdbm.3
index e3b90d4..c08ece3 100644
--- a/doc/gdbm.3
+++ b/doc/gdbm.3
@@ -1,8 +1,8 @@
.\" This file is part of GDBM.
-.\" Copyright (C) 2011 Free Software Foundation, Inc.
+.\" Copyright (C) 2011, 2013 Free Software Foundation, Inc.
.\"
.\" GDBM is free software; you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation; either version 3, or (at your option)
.\" any later version.
.\"
@@ -10,17 +10,16 @@
.\" 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 GDBM. If not, see <http://www.gnu.org/licenses/>. */
-.TH GDBM 3 "August 9, 2011" "GDBM" "GDBM User Reference"
-.ds ve 1.9
+.TH GDBM 3 "May 8, 2013" "GDBM" "GDBM User Reference"
.SH NAME
-GDBM - The GNU database manager. Includes \fBdbm\fR and \fBndbm\fR
-compatability. (Version \*(ve.)
+GDBM \- The GNU database manager. Includes \fBdbm\fR and \fBndbm\fR
+compatibility.
.SH SYNOPSIS
.nf
.B #include <gdbm.h>
.sp
.BI "extern gdbm_error" " gdbm_errno";
.br
@@ -197,13 +196,13 @@ key data. \fIContent\fR is the data to be associated with the \fIkey\fR.
.B GDBM_INSERT
Insert only, generate an error if key exists;
.TP
.B GDBM_REPLACE
Replace contents if key exists.
.PP
-If a reader calls \fBgdbm_store\fR, the return value will be -1.
+If a reader calls \fBgdbm_store\fR, the return value will be \-1.
If called with \fBGDBM_INSERT\fR and \fIkey\fR is in the database, the return
value will be 1. Otherwise, the return value is 0.
\fINOTICE: If you store data for a key that is already in the data base,
\fBgdbm\fI replaces the old data with the new data if called with \fBGDBM_REPLACE\fI.
You do not get two data items for the same key and you do not get an
@@ -242,13 +241,13 @@ To remove some data from the database:
.BI "int gdbm_delete (GDBM_FILE " dbf ", datum " key );
\fIDbf\fR is the pointer returned by \fBgdbm_open\fR. \fIKey\fR is the
key data.
-The return value is -1 if the item is not present or the requester is a reader.
+The return value is \-1 if the item is not present or the requester is a reader.
The return value is 0 if there was a successful delete.
The next two routines allow for accessing all items in the database. This
access is not key sequential, but it is guaranteed to visit every key in
the database once. (The order has to do with the hash values.)
@@ -350,13 +349,13 @@ to be merged. This can become a CPU expensive process with time, though,
especially if used in conjunction with \fBGDBM_CENTFREE\fR. \fIvalue\fR
(see below) should be set to either TRUE or FALSE.
\fINOTICE: This feature is still under study.\fR
.PP
\fIvalue\fR is the value to set \fIoption\fR to, specified as an integer
pointer. \fIsize\fR is the size of the data pointed to by \fIvalue\fR.
-The return value will be -1 upon failure, or 0 upon success. The global
+The return value will be \-1 upon failure, or 0 upon success. The global
variable \fIgdbm_errno\fR will be set upon failure.
For instance, to set a database to use a cache of 10, after opening it
with \fBgdbm_open\fR, but prior to accessing it in any way, the following
code could be used:
.sp
@@ -396,36 +395,38 @@ required by the programmer, and only one file may be opened at a time.
All users in compatibility mode are assumed to be writers. If the
\fBgdbm\fR file is a read only, it will fail as a writer, but will
also try to open it as a reader. All returned pointers in datum
structures point to data that \fBgdbm\fR WILL free. They should be
treated as static pointers (as standard UNIX \fBdbm\fR does).
.SH LINKING
-This library is accessed by specifying \fI-lgdbm\fR as the last
+This library is accessed by specifying \fI\-lgdbm\fR as the last
parameter to the compile line, e.g.:
.sp
.nf
.in +5
-gcc -o prog prog.c -lgdbm
+gcc \-o prog prog.c \-lgdbm
.in
.fi
.PP
If you wish to use the \fBdbm\fR or \fBndbm\fR compatibility routines,
you must link in the \fIgdbm_compat\fR library as well. For example:
.sp
.nf
.in +5
-gcc -o prog proc.c -lgdbm -lgdbm_compat
+gcc \-o prog proc.c \-lgdbm \-lgdbm_compat
.in
.fi
.\" .SH BUGS
.SH "BUG REPORTS"
-Send bug reports to <bug-gdbm@gnu.org>.
+Send bug reports to <bug\-gdbm@gnu.org>.
.SH "SEE ALSO"
-dbm, ndbm
-.SH AUTHOR
+.BR gdbm_dump (1),
+.BR gdbm_load (1),
+.BR gdbmtool (1).
+.SH AUTHORS
by Philip A. Nelson, Jason Downs and Sergey Poznyakoff.
.SH COPYRIGHT
Copyright \(co 1990 - 2011 Free Software Foundation, Inc.
GDBM is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
diff --git a/doc/gdbm.texinfo b/doc/gdbm.texinfo
index 9f0af5b..17f47f9 100644
--- a/doc/gdbm.texinfo
+++ b/doc/gdbm.texinfo
@@ -115,13 +115,13 @@ Functions:
* Error codes:: Error codes returned by @code{gdbm} calls.
* Variables:: Two useful variables.
* Compatibility:: Compatibility with UNIX dbm and ndbm.
Programs
-* testgdbm:: Test and modify a GDBM database.
+* gdbmtool:: Examine and modify a GDBM database.
* gdbm_dump:: Dump the database into a flat file.
* gdbm_load:: Load the database from a flat file.
* gdbmexport:: Export a database into a portable format.
* Exit codes:: Exit codes returned by GDBM utilities.
Other topics:
@@ -1614,55 +1614,55 @@ the next key in the database. If the iteration covered all keys in the
database, the @code{dptr} member of the returned datum is @samp{NULL}.
Otherwise, the @code{dptr} member of the returned datum points to the
memory managed by the compatibility library. The application should
never free it.
@end deftypefn
-@node testgdbm
-@chapter Test and modify a GDBM database.
-@prindex testgdbm
+@node gdbmtool
+@chapter Examine and modify a GDBM database.
+@prindex gdbmtool
-The @command{testgdbm} utility allows you to view and modify an
+The @command{gdbmtool} utility allows you to view and modify an
existing @acronym{GDBM} database or to create a new one.
-@cindex default database, @command{testgdbm}
+@cindex default database, @command{gdbmtool}
@flindex junk.gdbm
When invoked without arguments, it tries to open a database file called
@file{junk.gdbm}, located in the current working directory. You can
change this default by supplying the name of the database to use as
-the only argument to @command{testgdbm}, e.g.:
+the only argument to @command{gdbmtool}, e.g.:
@example
-$ testgdbm file.db
+$ gdbmtool file.db
@end example
-@cindex read-only mode, @command{testgdbm}
-@cindex @option{-r}, @command{testgdbm} option
-@cindex @option{--read-only}, @command{testgdbm} option
+@cindex read-only mode, @command{gdbmtool}
+@cindex @option{-r}, @command{gdbmtool} option
+@cindex @option{--read-only}, @command{gdbmtool} option
The database will be opened in read-write mode, unless the
@option{-r} (@option{--read-only}) option is specified, in which case
it will be opened only for reading.
-@cindex creating a database, @command{testgdbm}
-@cindex @option{-n}, @command{testgdbm} option
-@cindex @option{--newdb}, @command{testgdbm} option
-If the database does not exist, @command{testgdbm} will create it.
+@cindex creating a database, @command{gdbmtool}
+@cindex @option{-n}, @command{gdbmtool} option
+@cindex @option{--newdb}, @command{gdbmtool} option
+If the database does not exist, @command{gdbmtool} will create it.
There is a special option @option{-n} (@option{--newdb}, which
instructs the utility to create a new database. If it is used and if
the database already exists, it will be deleted, so use it sparingly.
@menu
* invocation::
* shell::
@end menu
@node invocation
-@section testgdbm invocation
-@cindex command line options, @command{testgdbm}
+@section gdbmtool invocation
+@cindex command line options, @command{gdbmtool}
-The following table summarizes all @command{testgdbm} command line
+The following table summarizes all @command{gdbmtool} command line
options:
@table @option
@item -b @var{size}
@itemx --block-size=@var{size}
Set block size.
@@ -1678,12 +1678,15 @@ Create the database.
@item -l
@itemx --no-lock
Disable file locking.
@item -m
@itemx --no-mmap
Disable mmap.
+@item -q
+@itemx --quiet
+Don't print the usual welcome banner at startup.
@item -r
@itemx --read-only
Open the database in read-only mode.
@item -s
@itemx --synchronize
Synchronize to the disk after each write.
@@ -1693,29 +1696,29 @@ Print program version and licensing information and exit.
@item --usage
Print a terse invocation syntax summary along with a list of available
command line options.
@end table
@node shell
-@section testgdbm interactive mode
-@cindex interactive mode, @command{testgdbm}
+@section gdbmtool interactive mode
+@cindex interactive mode, @command{gdbmtool}
-After successful startup, @command{testgdbm} starts a loop, in which
+After successful startup, @command{gdbmtool} starts a loop, in which
it reads commands from the user, executes them and prints the results
on the standard output. If the standard input is attached to a console,
-@command{testgdbm} runs in interactive mode, which is indicated by its
+@command{gdbmtool} runs in interactive mode, which is indicated by its
@dfn{prompt}:
@example
-testgdbm> _
+gdbmtool> _
@end example
The utility finishes when it reads the @samp{quit} command (see below) or
detects end-of-file on its standard input, whichever occurs first.
-A @command{testgdbm} command consists of a @dfn{command verb},
+A @command{gdbmtool} command consists of a @dfn{command verb},
optionally followed by one or two @dfn{arguments}, separated by any
amount of white space. A command verb can be entered either in full
or in an abbreviated form, as long as that abbreviation does not match
any other verb. For example, @samp{co} can be used instead of
@samp{count} and @samp{ca} instead of @samp{cache}. Furthermore,
many command verbs also have single-letter forms, called @dfn{command
@@ -1724,219 +1727,212 @@ letters}.
An argument is any sequence of non-whitespace characters. Notice,
that currently there is no way to enter arguments containing white
space. This limitation will be removed in future releases.
Each command takes at most two @dfn{formal parameters}, which can be
optional or mandatory. If the number of actual arguments is less than the
-number of mandatory parameters, @command{testgdbm} will prompt you to
+number of mandatory parameters, @command{gdbmtool} will prompt you to
supply missing arguments. For example, the @samp{store} command takes two
mandatory parameters, so if you invoked it with no arguments, you
would be prompted twice to supply the necessary data, as shown in
example below:
@example
-testgdbm> @kbd{store}
+gdbmtool> @kbd{store}
key> @kbd{three}
data> @kbd{3}
@end example
However, such prompting is possible only in interactive mode. In
non-interactive mode (e.g.@: when running a script), all arguments must
-be supplied with each command, otherwise @command{testgdbm} will report an
+be supplied with each command, otherwise @command{gdbmtool} will report an
error and exit immediately.
@anchor{pager}
-@cindex pager, @command{testgdbm}
+@cindex pager, @command{gdbmtool}
@cindex @env{PAGER}
Some commands produce excessive amounts of output. To help you follow
-it, @command{testgdbm} uses a pager utility to display such
+it, @command{gdbmtool} uses a pager utility to display such
output. The name of the pager utility is taken from the environment
variable @env{PAGER}. The pager is invoked only in interactive mode
and only if the estimated number of output lines is greater then the
number of lines on your screen.
@anchor{nul-termination}
-Many of the @command{testgdbm} commands operate on database key and
+Many of the @command{gdbmtool} commands operate on database key and
data values. The utility assumes that both keys and data are
@acronym{ASCII} strings, either nul-terminated or not. By default,
it is assumed that strings are nul-terminated. You can change this
by using @code{z} (@code{key-zero}, for keys) and @code{Z}
(@code{data-zero}, for data) commands.
The following table summarizes all available commands:
@deffn {command verb} count
-@deffnx {command abbrev} co
@deffnx {command letter} c
Print the number of entries in the database.
@end deffn
@deffn {command verb} delete @var{key}
-@deffnx {command abbrev} de @var{key}
@deffnx {command letter} d @var{key}
-Delete entry with a given @var{key}
+Delete entry with the given @var{key}
@end deffn
-@anchor{testgdbm export}
+@anchor{gdbmtool export}
@deffn {command verb} export @var{file-name} [truncate] [binary|ascii]
-@deffnx {command abbrev} e @var{file-name} [truncate] [binary|ascii]
+@deffnx {command letter} e @var{file-name} [truncate] [binary|ascii]
Export the database to the flat file @var{file-name}. @xref{Flat files},
for a description of the flat file format and its purposes. This
-command will not overwrite an existing file, unless the argument
-@samp{truncate} is also given. Another optional argument determines
-the type of dump (@pxref{Flat files}). By default, ASCII dump is
-created.
+command will not overwrite an existing file, unless the
+@samp{truncate} parameter is also given. Another optional argument
+determines the type of the dump (@pxref{Flat files}). By default, ASCII
+dump is created.
See also @ref{gdbmexport}.
@end deffn
@deffn {command verb} fetch @var{key}
-@deffnx {command abbrev} fe @var{key}
@deffnx {command letter} f @var{key}
-Fetch and display a record with the given @var{key}.
+Fetch and display the record with the given @var{key}.
@end deffn
-@anchor{testgdbm import}
+@anchor{gdbmtool import}
@deffn {command verb} import @var{file-name} [replace] [nometa]
-@deffnx {command abbrev} i @var{file-name} [replace] [nometa]
+@deffnx {command letter} i @var{file-name} [replace] [nometa]
Import data from a flat dump file @var{file-name}
(@pxref{Flat files}). If the word @samp{replace} is given
as an argument, any records with the same keys as the already
existing ones will replace them. The word @samp{nometa} turns off
restoring meta-information from the dump file.
@end deffn
@deffn {command verb} list
-@deffnx {command abbrev} l
+@deffnx {command letter} l
List the contents of the database (@pxref{pager}).
@end deffn
@deffn {command verb} next [@var{key}]
-@deffnx {command abbrev} n [@var{key}]
-Sequential access: fetch and display a next record. If @var{key} is
-given, a record following one with this key will be fetched.
-Otherwise, the key supplied by the latest @code{1}, @code{2} or
-@var{n} command will be used.
+@deffnx {command letter} n [@var{key}]
+Sequential access: fetch and display the next record. If the @var{key} is
+given, the record following the one with this key will be fetched.
See also @code{first}, below.
@xref{Sequential}, for more information on sequential access.
@end deffn
+@deffn {command verb} prompt @var{text}
+Changes the command prompt to the string @var{text}. The string can
+contain @dfn{escape sequences}, the special entities consisting of the
+@samp{%} character followed by another character. These sequences are
+replaced in the generated prompt as follows:
+
+@multitable @columnfractions 0.4 0.5
+@headitem Sequence @tab Expansion
+@item %f @tab name of the db file
+@item %% @tab %
+@end multitable
+@end deffn
+
@deffn {command verb} quit
-@deffnx {command abbrev} q
+@deffnx {command letter} q
Close the database and quit the utility.
@end deffn
@deffn {command verb} store @var{key} @var{data}
-@deffnx {command abbrev} sto @var{key} @var{data}
@deffnx {command letter} s @var{key} @var{data}
Store the @var{data} with @var{key} in the database. If @var{key}
already exists, its data will be replaced.
@end deffn
@deffn {command verb} first
-@deffnx {command abbrev} fi
@deffnx {command letter} 1
Fetch and display the first record in the database. Subsequent
-records can be fetched using @code{next} command (see above).
+records can be fetched using the @code{next} command (see above).
@xref{Sequential}, for more information on sequential access.
@end deffn
@deffn {command verb} read @var{file} [replace]
-@deffnx {command abbrev} rea @var{file} [replace]
@deffnx {command letter} < @var{file} [replace]
Read entries from @var{file} and store them in the database. If the
-word @samp{replace} is given as the second argument, any existing
-records with matching keys will be replaced.
+@samp{replace} parameter is given, any existing records with matching
+keys will be replaced.
@end deffn
@deffn {command verb} reorganize
-@deffnx {command abbrev} reo
@deffnx {command letter} r
Reorganize the database (@pxref{Reorganization}).
@end deffn
@deffn {command verb} key-zero
-@deffnx {command abbrev} k
@deffnx {command letter} z
Toggle key nul-termination. Use @code{status} to inspect the current
state. @xref{nul-termination}.
@end deffn
@deffn {command verb} avail
-@deffnx {command abbrev} a
@deffnx {command letter} A
Print the @dfn{avail list}.
@end deffn
@deffn {command verb} bucket
-@deffnx {command abbrev} b
@deffnx {command letter} B
Print the bucket number @var{num}.
@end deffn
@deffn {command verb} current
-@deffnx {command abbrev} cu
@deffnx {command letter} C
Print the current bucket.
@end deffn
@deffn {command verb} dir
-@deffnx {command abbrev} di
@deffnx {command letter} D
Print hash directory.
@end deffn
@deffn {command verb} header
-@deffnx {command abbrev} hea
@deffnx {command letter} F
Print file header.
@end deffn
@deffn {command verb} hash @var{key}
-@deffnx {command abbrev} ha @var{key}
@deffnx {command letter} H @var{key}
Compute and display the hash value for the given @var{key}.
@end deffn
@deffn {command verb} cache
-@deffnx {command abbrev} ca
@deffnx {command letter} K
Print the bucket cache.
@end deffn
@deffn {command verb} status
-@deffnx {command abbrev} sta
@deffnx {command letter} S
Print current program status. The following example shows the
information displayed:
@example
Database file: junk.gdbm
Zero terminated keys: yes
Zero terminated data: yes
@end example
@end deffn
@deffn {command verb} version
-@deffnx {command abbrev} v
+@deffnx {command letter} v
Print the version of @command{gdbm}.
@end deffn
@deffn {command verb} data-zero
-@deffnx {command abbrev} da
@deffnx {command letter} Z
Toggle data nul-termination. Use @code{status} to examine the current
status.
@xref{nul-termination}.
@end deffn
@deffn {command verb} help
-@deffnx {command abbrev} hel
@deffnx {command letter} ?
Print a concise command summary, showing each command letter and verb
with its parameters and a short description of what it does. Optional
arguments are enclosed in square brackets.
@end deffn
diff --git a/doc/gdbm_dump.1 b/doc/gdbm_dump.1
new file mode 100644
index 0000000..bf68683
--- a/dev/null
+++ b/doc/gdbm_dump.1
@@ -0,0 +1,88 @@
+.\" This file is part of GDBM.
+.\" Copyright (C) 2013 Free Software Foundation, Inc.
+.\"
+.\" GDBM is free software; you can redistribute it and/or modify
+.\" it under the terms of the GNU General Public License as published by
+.\" the Free Software Foundation; either version 3, or (at your option)
+.\" any later version.
+.\"
+.\" GDBM 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 GDBM. If not, see <http://www.gnu.org/licenses/>. */
+.TH GDBM_DUMP 1 "May 8, 2013" "GDBM" "GDBM User Reference"
+.SH NAME
+gdbm_dump \- dump a GDBM database to a file
+.SH SYNOPSIS
+\fBgdbm_dump\fR [\fB\-H \fIFMT\fR] [\fB\-\-format\fR=\fIFMT\fR] \fIDB_FILE\fR [\fIFILE\fR]
+.sp
+\fBgdbm_dump\fR [\fB\-Vh\fR] [\fB\-\-help\fR] [\fB\-\-usage\fR] [\fB\-\-version\fR]
+.SH DESCRIPTION
+The
+.B gdbm_dump
+utility creates a dump of the specified
+.BR gdbm (3)
+database file. The name for the output dump file is supplied by the
+second argument (\fIFILE\fR). If not specified, the output goes to
+the standard error.
+.PP
+The created dump can be given as argument to the
+.BR gdbm_load (1)
+utility in order to re-create an exact copy of the \fIDB_FILE\fR.
+.SH OPTIONS
+.TP
+\fB\-H\fR, \fB\-\-format\fR=\fIFMT\fR
+Select dump format. The value \fBbinary\fR (or \fB0\fR) instructs
+.B gdbm_dump
+to produce a binary dump, compatible with earlier
+.B gdbm
+versions (up to version 1.9). The value \fBascii\fR (or \fB1\fR)
+instructs it to create an ASCII dump (this is the default). The
+latter is preferred because, apart from the actual data, it also
+contains meta-information which will allow
+.BR gdbm_load (1)
+to recreate an exact copy of the file.
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print a short usage summary.
+.TP
+\fB\-\-usage\fR
+Print a list of available options.
+.TP
+\fB\-V\fR, \fB\-\-version\fR
+Print program version
+.SH "SEE ALSO"
+.BR gdbm_load (1),
+.BR gdbmtool (1),
+.BR gdbm (3).
+.PP
+For a detailed description of
+.B gdbm_dump
+and other
+.B gdbm
+utilities, refer to the \fBGDBM Manual\fR available in
+Texinfo format. To access it, run:
+
+ \fBinfo gdbm\fR
+
+.SH "REPORTING BUGS"
+Report bugs to <bug\-gdbm@gnu.org>.
+.SH COPYRIGHT
+Copyright \(co 2013 Free Software Foundation, Inc
+.br
+.na
+License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
+.br
+.ad
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.\" Local variables:
+.\" eval: (add-hook 'write-file-hooks 'time-stamp)
+.\" time-stamp-start: ".TH GDBM[A-Z_-]* 1 \""
+.\" time-stamp-format: "%:B %:d, %:y"
+.\" time-stamp-end: "\""
+.\" time-stamp-line-limit: 20
+.\" end:
diff --git a/doc/gdbm_load.1 b/doc/gdbm_load.1
new file mode 100644
index 0000000..00aaac0
--- a/dev/null
+++ b/doc/gdbm_load.1
@@ -0,0 +1,96 @@
+.\" This file is part of GDBM.
+.\" Copyright (C) 2011, 2013 Free Software Foundation, Inc.
+.\"
+.\" GDBM is free software; you can redistribute it and/or modify
+.\" it under the terms of the GNU General Public License as published by
+.\" the Free Software Foundation; either version 3, or (at your option)
+.\" any later version.
+.\"
+.\" GDBM 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 GDBM. If not, see <http://www.gnu.org/licenses/>. */
+.TH GDBM_LOAD 1 "May 8, 2013" "GDBM" "GDBM User Reference"
+.SH NAME
+gdbm_load \- re-create a GDBM database from a dump file.
+.SH SYNOPSIS
+\fBgdbm_load\fR [\fB\-nr\fR] [\fB\-m\fR \fIMODE\fR]\
+ [\fB\-u\fR \fINAME\fR|\fIUID\fR[:\fINAME\fR|\fIGID\fR]]
+ [\fB\-\-mode\fR=\fIMODE\fR]\
+ [\fB\-\-no\-meta\fR] [\fB\-\-replace\fR]
+ [\fB\-\-user\fR=\fINAME\fR|\fIUID\fR[:\fINAME\fR|\fIGID\fR]]\
+ \fIFILE\fR [\fIDB_FILE\fR]
+
+.sp
+\fBgdbm_load\fR [\fB\-Vh\fR] [\fB\-\-help\fR] [\fB\-\-usage\fR] [\fB\-\-version\fR]
+.SH DESCRIPTION
+Create a
+.B gdbm
+database file
+.I DB_FILE
+from the dump file
+.IR FILE .
+If the
+.I FILE
+argument is not supplied, output the created database to the standard error.
+.PP
+If the input file is in ASCII dump format, the mode and ownership of
+the created database are restored from the information in the dump.
+This can be overridden using the command line options (see below).
+.SH OPTIONS
+.TP
+\fB\-m\fR, \fB\-\-mode\fR=\fIMODE\fR
+Set database file mode (octal number).
+.TP
+\fB\-n\fR, \fB\-\-no\-meta\fR
+Do not attempt to restore database meta-data (mode and ownership).
+.TP
+\fB\-r\fR, \fB\-\-replace\fR
+If the database exists, replace records in it.
+.TP
+\fB\-u\fR, \fB\-\-user\fR=\fINAME\fR|\fIUID\fR[:\fINAME\fR|\fIGID\fR]
+Set file ownership.
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print a short usage summary.
+.TP
+\fB\-\-usage\fR
+Print a list of available options.
+.TP
+\fB\-V\fR, \fB\-\-version\fR
+Print program version
+.SH "SEE ALSO"
+.BR gdbm_dump (1),
+.BR gdbmtool (1),
+.BR gdbm (3).
+.PP
+For a detailed description of
+.B gdbm_load
+and other
+.B gdbm
+utilities, refer to the \fBGDBM Manual\fR available in
+Texinfo format. To access it, run:
+
+ \fBinfo gdbm\fR
+
+.SH "REPORTING BUGS"
+Report bugs to <bug\-gdbm@gnu.org>.
+.SH COPYRIGHT
+Copyright \(co 2013 Free Software Foundation, Inc
+.br
+.na
+License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
+.br
+.ad
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.\" Local variables:
+.\" eval: (add-hook 'write-file-hooks 'time-stamp)
+.\" time-stamp-start: ".TH GDBM[A-Z_-]* 1 \""
+.\" time-stamp-format: "%:B %:d, %:y"
+.\" time-stamp-end: "\""
+.\" time-stamp-line-limit: 20
+.\" end:
diff --git a/doc/gdbmtool.1 b/doc/gdbmtool.1
new file mode 100644
index 0000000..e6a8f2a
--- a/dev/null
+++ b/doc/gdbmtool.1
@@ -0,0 +1,245 @@
+.\" This file is part of GDBM.
+.\" Copyright (C) 2013 Free Software Foundation, Inc.
+.\"
+.\" GDBM is free software; you can redistribute it and/or modify
+.\" it under the terms of the GNU General Public License as published by
+.\" the Free Software Foundation; either version 3, or (at your option)
+.\" any later version.
+.\"
+.\" GDBM 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 GDBM. If not, see <http://www.gnu.org/licenses/>. */
+.TH GDBM_DUMP 1 "May 8, 2013" "GDBM" "GDBM User Reference"
+.SH NAME
+gdbmtool \- examine and modify a GDBM database
+.SH SYNOPSIS
+\fBgdbmtool\fR [\fB\-lmnqrs\fR] [\fB\-b\fR \fISIZE\fR] [\fB\-c\fR \fISIZE\fR]\
+ [\fB\-g\fR \fIFILE\fR] [\fB\-\-block\-size\fR=\fISIZE\fR]
+ [\fB\-\-cache\-size\fR=\fISIZE\fR] [\fB\-\-newdb\fR]\
+ [\fB\-\-no\-lock\fR] [\fB\-\-no\-mmap\fR]
+ [\fB\-\-quiet\fR] [\fB\-\-read\-only\fR] [\fB\-\-synchronize\fR]\
+ [\fIDBFILE\fR]
+.sp
+\fBgdbmtool\fR [\fB\-Vh\fR] ][\fB\-\-help\fR] [\fB\-\-usage\fR] [\fB\-\-version\fR]
+.SH DESCRIPTION
+The
+.B gdbmtool
+utility allows you to view and modify an existing GDBM database or to
+create a new one.
+.PP
+The \fIDBFILE\fR argument supplies the name of the database to open.
+If not supplied, the default name
+.B junk.gdbm
+is used instead.
+If the named database does not exist, it will be created. An existing
+database can be cleared (i.e. all records removed from it) using the
+\fB\-\-newdb\fR option (see below).
+.PP
+After successful startup,
+.B gdbmtool
+starts a loop, in which it reads
+commands from the user, executes them and prints the results on the
+standard output. If the standard input is attached to a console,
+the program runs in interactive mode.
+.PP
+The program terminates when the
+.B quit
+command is given, or end-of-file is detected on its standard input.
+.PP
+A
+.B gdbmtool
+command consists of a command verb, optionally
+followed by one or more arguments, separated by any amount of white
+space. A command verb can be entered either in full or in an
+abbreviated form, as long as that abbreviation does not match any other
+verb. Many command verbs have also one-letter abbreviation which can
+be used instead.
+.SH OPTIONS
+.TP
+\fB\-b\fR, \fB\-\-block\-size\fR=\fISIZE\fR
+Set block size.
+.TP
+\fB\-c\fR, \fB\-\-cache\-size\fR=\fISIZE\fR
+Set cache size.
+.TP
+\fB\-l\fR, \fB\-\-no\-lock\fR
+Disable file locking.
+.TP
+\fB\-m\fR, \fB\-\-no\-mmap\fR
+Do not use
+.BR mmap (2).
+.TP
+\fB\-n\fR, \fB\-\-newdb\fR
+Create the database, truncating it if it already exists.
+.TP
+\fB\-q\fR, \fB\-\-quiet\fR
+Don't print initial banner.
+.TP
+\fB\-r\fR, \fB\-\-read\-only\fR
+Open database in read-only mode.
+.TP
+\fB\-s\fR, \fB\-\-synchronize\fR
+Synchronize to disk after each write.
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print a short usage summary.
+.TP
+\fB\-\-usage\fR
+Print a list of available options.
+.TP
+\fB\-V\fR, \fB\-\-version\fR
+Print program version
+.SH SHELL COMMANDS
+For command verbs that have single-letter abbreviations, these are
+printed after a comma. Either command verb or its abbreviation must
+be used, but not both.
+.TP
+.BR avail ", " A
+Print the "
+.BR "avail list" .
+.TP
+\fBbucket\fR, \fBB\fR \fINUM\fR
+Print the bucket number \fINUM\fR.
+.TP
+.BR cache ", " K
+Print the bucket cache.
+.TP
+.BR count ", " c
+Print the number of entries in the database.
+.TP
+.BR current ", " C
+Print the current bucket.
+.TP
+.BR data-zero ", " Z
+Toggle data nul-termination. Use
+.B status
+to examine the current status.
+.TP
+\fBdelete\fR, \fBd\fR \fIKEY\fR
+Delete entry with the given \fIKEY\fR.
+.TP
+.BR dir ", " D
+Print hash directory.
+.TP
+\fBexport\fR, \fBe\fR \fIFILE\-NAME\fR [\fBtruncate\fR] [\fBbinary\fR|\fBascii\fR]
+Export the database to the flat file \fIFILE\-NAME\fR. This is equivalent to
+.BR gdbm_dump (1).
+
+This command will not overwrite an existing file, unless the
+.B truncate
+parameter is also given. Another optional parameter determines the type of
+the dump (*note Flat files::). By default, ASCII dump will be created.
+.TP
+\fBfetch\fR, \fBf\fR \fIKEY\fR
+Fetch and display the record with the given \fIKEY\fR.
+.TP
+.BR first ", " 1
+Fetch and display the first record in the database. Subsequent
+records can be fetched using the
+.B next
+command (see below).
+.TP
+\fBhash\fR, \fBH\fR \fIKEY\fR
+Compute and display hash value for the given \fIKEY\fR.
+.TP
+.BR header ", " F
+Print file header.
+.TP
+.BR help ", " ?
+Print a concise command summary, showing each command letter and
+verb with its parameters and a short description of what it does.
+Optional arguments are enclosed in square brackets.
+.TP
+\fBimport\fR, \fBi\fR \fIFILE\-NAME\fR [\fBreplace\fR] [\fBnometa\fR]
+Import data from a flat dump file \fIFILE\-NAME\fR.
+If the
+.B replace
+argument is given, any records with the same keys as the already
+existing ones will replace them. The
+.B nometa
+argument turns off restoring meta-information from the dump file.
+.TP
+.BR key-zero ", " z
+Toggle key nul-termination. Use
+.B status
+to inspect the current state.
+.TP
+\fBlist\fR, \fBl\fR
+List the contents of the database.
+.TP
+\fBnext\fR, \fBn\fR [\fIKEY\fR]
+Sequential access: fetch and display the next record. If the \fIKEY\fR is
+given, the record following the one with this key will be fetched.
+.TP
+\fBprompt\fR \fITEXT\fR
+Changes the command prompt to the string \fITEXT\fR. The string can
+contain
+.BR "escape sequences" ,
+the special entities consisting of the
+.B %
+character followed by another character. These sequences are
+replaced in the generated prompt as follows:
+.sp
+.nf
+.ta 8n 20n
+.ul
+ Sequence Expansion
+ \fB%f\fR name of the db file
+ \fB%%\fR \fB%\fR
+.fi
+.TP
+.BR quit ", " q
+Close the database and quit the utility.
+.TP
+\fBread\fR, \fB<\fR \fIFILE\fR [\fBreplace\fR]
+Read entries from \fIFILE\fR and store them in the database. If the
+.B replace
+parameter is given, any existing records with matching keys will be replaced.
+.TP
+.BR reorganize ", " r
+Reorganize the database.
+.TP
+.BR status ", " S
+Print current program status. The following example shows the
+information displayed:
+.sp
+.nf
+.if +2
+Database file: junk.gdbm
+Zero terminated keys: yes
+Zero terminated data: yes
+.fi
+.TP
+\fBstore\fR, \fBs\fR \fIKEY\fR \fIDATA\fR
+Store the \fIDATA\fR with the given \fIKEY\fR in the database. If the
+\fIKEY\fR already exists, its data will be replaced.
+.TP
+.BR version ", " v
+Print the version of
+.BR gdbm .
+.SH "SEE ALSO"
+.BR gdbm_dump (1),
+.BR gdbm_load (1),
+.BR gdbm (3).
+.SH "REPORTING BUGS"
+Report bugs to <bug\-gdbm@gnu.org>.
+.SH COPYRIGHT
+Copyright \(co 2013 Free Software Foundation, Inc
+.br
+.na
+License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
+.br
+.ad
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.\" Local variables:
+.\" eval: (add-hook 'write-file-hooks 'time-stamp)
+.\" time-stamp-start: ".TH GDBM[A-Z_-]* 1 \""
+.\" time-stamp-format: "%:B %:d, %:y"
+.\" time-stamp-end: "\""
+.\" time-stamp-line-limit: 20
+.\" end:

Return to:

Send suggestions and report system problems to the System administrator.