From 6658f41e38fec9e007a0fbd0883e030f6337e28d Mon Sep 17 00:00:00 2001 From: Sergey Poznyakoff Date: Wed, 8 May 2013 16:27:01 +0000 Subject: 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. --- ChangeLog | 19 +++++ configure.ac | 2 +- doc/Makefile.am | 2 +- doc/gdbm.3 | 29 +++---- doc/gdbm.texinfo | 134 +++++++++++++++--------------- doc/gdbm_dump.1 | 88 ++++++++++++++++++++ doc/gdbm_load.1 | 96 ++++++++++++++++++++++ doc/gdbmtool.1 | 245 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ src/.cvsignore | 1 + src/Makefile.am | 5 +- src/gdbm_dump.c | 8 +- src/gdbm_load.c | 6 ++ src/testgdbm.c | 107 ++++++++++++++++++++---- 13 files changed, 636 insertions(+), 106 deletions(-) create mode 100644 doc/gdbm_dump.1 create mode 100644 doc/gdbm_load.1 create mode 100644 doc/gdbmtool.1 diff --git a/ChangeLog b/ChangeLog index e7f1637..02cbe9d 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,22 @@ +2013-05-08 Sergey Poznyakoff + + 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 * configure.ac: (AC_INIT): Add webpage URL. 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 . */ -.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 @@ -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 . +Send bug reports to . .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 --- /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 . */ +.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 . +.SH COPYRIGHT +Copyright \(co 2013 Free Software Foundation, Inc +.br +.na +License GPLv3+: GNU GPL version 3 or later +.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 --- /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 . */ +.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 . +.SH COPYRIGHT +Copyright \(co 2013 Free Software Foundation, Inc +.br +.na +License GPLv3+: GNU GPL version 3 or later +.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 --- /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 . */ +.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 . +.SH COPYRIGHT +Copyright \(co 2013 Free Software Foundation, Inc +.br +.na +License GPLv3+: GNU GPL version 3 or later +.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 (¶m, 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) { -- cgit v1.2.1