summaryrefslogtreecommitdiffabout
Side-by-side diff
Diffstat (more/less context) (ignore whitespace changes)
-rw-r--r--ChangeLog19
-rw-r--r--configure.ac2
-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
-rw-r--r--src/.cvsignore1
-rw-r--r--src/Makefile.am5
-rw-r--r--src/gdbm_dump.c8
-rw-r--r--src/gdbm_load.c6
-rw-r--r--src/testgdbm.c107
13 files changed, 636 insertions, 106 deletions
diff --git a/ChangeLog b/ChangeLog
index e7f1637..02cbe9d 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,24 @@
2013-05-08 Sergey Poznyakoff <gray@gnu.org.ua>
+ 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.
+
+2013-05-08 Sergey Poznyakoff <gray@gnu.org.ua>
+
* configure.ac: (AC_INIT): Add webpage URL.
2013-05-08 Sergey Poznyakoff <gray@gnu.org.ua>
diff --git a/configure.ac b/configure.ac
index e43bc53..ce00344 100644
--- a/configure.ac
+++ b/configure.ac
@@ -22,7 +22,7 @@ AC_INIT([gdbm],
_GDBM_VERSION_MAJOR._GDBM_VERSION_MINOR[]m4_ifdef([_GDBM_VERSION_PATCH],._GDBM_VERSION_PATCH),
[bug-gdbm@gnu.org],,
[http://www.gnu.org/software/gdbm])
-AC_PREREQ(2.69)a
+AC_PREREQ(2.69)
AC_CONFIG_SRCDIR([src/gdbmdefs.h])
AC_CONFIG_AUX_DIR([build-aux])
AC_CONFIG_HEADERS([autoconf.h])
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:
diff --git a/src/.cvsignore b/src/.cvsignore
index 46838d7..70e7a26 100644
--- a/src/.cvsignore
+++ b/src/.cvsignore
@@ -7,5 +7,6 @@ gdbm.h
*.lo
libgdbm.la
testgdbm
+gdbmtool
gdbm_dump
gdbm_load
diff --git a/src/Makefile.am b/src/Makefile.am
index 2d7a81a..7b1a2d2 100644
--- a/src/Makefile.am
+++ b/src/Makefile.am
@@ -76,7 +76,8 @@ libgdbmapp_a_SOURCES =\
progname.c
# Programs
-bin_PROGRAMS = testgdbm gdbm_load gdbm_dump
-testgdbm_LDADD = ./libgdbmapp.a ./libgdbm.la
+bin_PROGRAMS = gdbmtool gdbm_load gdbm_dump
+gdbmtool_LDADD = ./libgdbmapp.a ./libgdbm.la
+gdbmtool_SOURCES = testgdbm.c
gdbm_load_LDADD = ./libgdbmapp.a ./libgdbm.la
gdbm_dump_LDADD = ./libgdbmapp.a ./libgdbm.la
diff --git a/src/gdbm_dump.c b/src/gdbm_dump.c
index 9120f04..d6318b1 100644
--- a/src/gdbm_dump.c
+++ b/src/gdbm_dump.c
@@ -22,7 +22,7 @@
char *parseopt_program_doc = "dump a GDBM database to a file";
char *parseopt_program_args = "DB_FILE [FILE]";
struct gdbm_option optab[] = {
- { 'H', "format", N_("0|1"), N_("select dump format") },
+ { 'H', "format", "binary|ascii|0|1", N_("select dump format") },
{ 0 }
};
@@ -36,6 +36,12 @@ main (int argc, char **argv)
char *dbname, *filename;
FILE *fp;
+#ifdef HAVE_SETLOCALE
+ setlocale (LC_ALL, "");
+#endif
+ bindtextdomain (PACKAGE, LOCALEDIR);
+ textdomain (PACKAGE);
+
set_progname (argv[0]);
for (opt = parseopt_first (argc, argv, optab);
diff --git a/src/gdbm_load.c b/src/gdbm_load.c
index deea9ca..7746b1b 100644
--- a/src/gdbm_load.c
+++ b/src/gdbm_load.c
@@ -73,6 +73,12 @@ main (int argc, char **argv)
unsigned long err_line, n;
char *end;
+#ifdef HAVE_SETLOCALE
+ setlocale (LC_ALL, "");
+#endif
+ bindtextdomain (PACKAGE, LOCALEDIR);
+ textdomain (PACKAGE);
+
set_progname (argv[0]);
for (opt = parseopt_first (argc, argv, optab);
diff --git a/src/testgdbm.c b/src/testgdbm.c
index 2ac3826..155c69e 100644
--- a/src/testgdbm.c
+++ b/src/testgdbm.c
@@ -1,6 +1,3 @@
-/* testgdbm.c - Driver program to test the database routines and to
- help debug gdbm. Uses inside information to show "system" information */
-
/* This file is part of GDBM, the GNU data base manager.
Copyright (C) 1990, 1991, 1993, 2007, 2011, 2013 Free Software Foundation,
Inc.
@@ -39,7 +36,8 @@
const char *progname; /* Program name */
-char *prompt = "testgdbm> ";
+#define DEFAULT_PROMPT "gdbmtool> "
+char *prompt;
char *file_name = NULL; /* Database file name */
GDBM_FILE gdbm_file = NULL; /* Database to operate upon */
@@ -48,6 +46,7 @@ datum key_data; /* Current key */
datum return_data; /* Current data */
int key_z = 1; /* Keys are nul-terminated strings */
int data_z = 1; /* Data are nul-terminated strings */
+int quiet_option = 0; /* Omit usual welcome banner at startup */
#define SIZE_T_MAX ((size_t)-1)
@@ -800,7 +799,77 @@ data_z_handler (struct handler_param *param)
data_z = !data_z;
fprintf (param->fp, _("Zero terminated data: %s\n"), boolstr (data_z));
}
+
+struct prompt_exp;
+
+void
+pe_file_name (struct prompt_exp *p)
+{
+ fwrite (file_name, strlen (file_name), 1, stdout);
+}
+
+struct prompt_exp
+{
+ int ch;
+ void (*fun) (struct prompt_exp *);
+ char *cache;
+};
+
+struct prompt_exp prompt_exp[] = {
+ { 'f', pe_file_name },
+ { 0 }
+};
+static void
+expand_char (int c)
+{
+ struct prompt_exp *p;
+
+ if (c && c != '%')
+ {
+ for (p = prompt_exp; p->ch; p++)
+ {
+ if (c == p->ch)
+ {
+ if (p->cache)
+ free (p->cache);
+ return p->fun (p);
+ }
+ }
+ }
+ putchar ('%');
+ putchar (c);
+}
+
+void
+outprompt ()
+{
+ char *s;
+
+ for (s = prompt; *s; s++)
+ {
+ if (*s == '%')
+ {
+ if (!*++s)
+ {
+ putchar ('%');
+ break;
+ }
+ expand_char (*s);
+ }
+ else
+ putchar (*s);
+ }
+
+ fflush (stdout);
+}
+
+void
+prompt_handler (struct handler_param *param)
+{
+ free (prompt);
+ prompt = estrdup (param->argv[0]);
+}
void help_handler (struct handler_param *param);
int help_begin (struct handler_param *param, size_t *exp_count);
@@ -891,6 +960,9 @@ struct command command_tab[] = {
{ S(help), '?',
help_begin, help_handler, NULL,
{ NULL, NULL, }, N_("print this help list") },
+ { S(prompt), 0,
+ NULL, prompt_handler, NULL,
+ { N_("text") }, N_("set command prompt") },
{ S(quit), 'q',
NULL, quit_handler, NULL,
{ NULL, NULL, }, N_("quit the program") },
@@ -1021,23 +1093,19 @@ getword (char *s, char **endp)
return p;
}
-/* The test program allows one to call all the routines plus the hash function.
- The commands are single letter commands. The user is prompted for missing
- pieces of information. See the help command (?) for a list of all
- commands. */
-
-char *parseopt_program_doc = "Test and modify a GDBM database";
-char *parseopt_program_args = N_("FILE");
+char *parseopt_program_doc = N_("examine and/or modify a GDBM database");
+char *parseopt_program_args = N_("DBFILE");
struct gdbm_option optab[] = {
{ 'b', "block-size", N_("SIZE"), N_("set block size") },
{ 'c', "cache-size", N_("SIZE"), N_("set cache size") },
{ 'g', NULL, "FILE", NULL, PARSEOPT_HIDDEN },
{ 'l', "no-lock", NULL, N_("disable file locking") },
- { 'm', "no-mmap", NULL, N_("disable file mmap") },
+ { 'm', "no-mmap", NULL, N_("do not use mmap") },
{ 'n', "newdb", NULL, N_("create database") },
{ 'r', "read-only", NULL, N_("open database in read-only mode") },
{ 's', "synchronize", NULL, N_("synchronize to disk after each write") },
+ { 'q', "quiet", NULL, N_("don't print initial banner") },
{ 0 }
};
@@ -1116,6 +1184,10 @@ main (int argc, char *argv[])
file_name = optarg;
break;
+ case 'q':
+ quiet_option = 1;
+ break;
+
default:
terror (EXIT_USAGE,
_("unknown option; try `%s -h' for more info\n"), progname);
@@ -1159,9 +1231,11 @@ main (int argc, char *argv[])
signal (SIGPIPE, SIG_IGN);
/* Welcome message. */
+ if (interactive && !quiet_option)
+ printf (_("\nWelcome to the gdbm tool. Type ? for help.\n\n"));
if (interactive)
- printf (_("\nWelcome to the gdbm test program. Type ? for help.\n\n"));
-
+ prompt = estrdup (DEFAULT_PROMPT);
+
memset (&param, 0, sizeof (param));
argmax = 0;
@@ -1181,10 +1255,7 @@ main (int argc, char *argv[])
input_line++;
if (interactive)
- {
- printf ("%s", prompt);
- fflush (stdout);
- }
+ outprompt ();
if (fgets (cmdbuf, sizeof cmdbuf, stdin) == NULL)
{

Return to:

Send suggestions and report system problems to the System administrator.