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
@@ -20,7 +20,7 @@ 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
diff --git a/doc/gdbm.3 b/doc/gdbm.3
index e3b90d4..c08ece3 100644
--- a/doc/gdbm.3
+++ b/doc/gdbm.3
@@ -1,5 +1,5 @@
.\" 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
@@ -13,11 +13,10 @@
.\"
.\" 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>
@@ -200,7 +199,7 @@ Insert only, generate an error if key exists;
.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.
@@ -245,7 +244,7 @@ To remove some data from the database:
\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
@@ -353,7 +352,7 @@ especially if used in conjunction with \fBGDBM_CENTFREE\fR. \fIvalue\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
@@ -399,12 +398,12 @@ 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
@@ -413,16 +412,18 @@ 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.
diff --git a/doc/gdbm.texinfo b/doc/gdbm.texinfo
index 9f0af5b..17f47f9 100644
--- a/doc/gdbm.texinfo
+++ b/doc/gdbm.texinfo
@@ -118,7 +118,7 @@ Functions:
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.
@@ -1617,35 +1617,35 @@ 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.
@@ -1656,10 +1656,10 @@ the database already exists, it will be deleted, so use it sparingly.
@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
@@ -1681,6 +1681,9 @@ 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.
@@ -1696,23 +1699,23 @@ 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
@@ -1727,35 +1730,35 @@ 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
@@ -1765,39 +1768,36 @@ by using @code{z} (@code{key-zero}, for keys) and @code{Z}
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
@@ -1806,107 +1806,105 @@ 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:
@@ -1919,12 +1917,11 @@ Zero terminated data: yes
@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.
@@ -1933,7 +1930,6 @@ status.
@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
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.