diff options
author | Sergey Poznyakoff <gray@gnu.org.ua> | 2013-05-08 16:27:01 +0000 |
---|---|---|
committer | Sergey Poznyakoff <gray@gnu.org.ua> | 2013-05-08 16:27:01 +0000 |
commit | 6658f41e38fec9e007a0fbd0883e030f6337e28d (patch) | |
tree | d7ecc0b72b23a01a2bfa10e8a7bb184d704269dc /doc | |
parent | c0cba983ab0c0bc1de630a200f902189ddddff09 (diff) | |
download | gdbm-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')
-rw-r--r-- | doc/Makefile.am | 2 | ||||
-rw-r--r-- | doc/gdbm.3 | 29 | ||||
-rw-r--r-- | doc/gdbm.texinfo | 134 | ||||
-rw-r--r-- | doc/gdbm_dump.1 | 88 | ||||
-rw-r--r-- | doc/gdbm_load.1 | 96 | ||||
-rw-r--r-- | doc/gdbmtool.1 | 245 |
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 @@ -11,25 +11,25 @@ # 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/>. */ # Documentation info_TEXINFOS = gdbm.texinfo gdbm_TEXINFOS=\ fdl.texi -man_MANS = gdbm.3 +man_MANS = gdbm.3 gdbm_dump.1 gdbm_load.1 gdbmtool.1 EXTRA_DIST = $(man_MANS) GENDOCS=gendocs.sh TEXI2DVI=texi2dvi -E # Make sure you set TEXINPUTS. # TEXINPUTS=/usr/share/texmf/pdftex/plain/misc/ is ok for most distributions .PHONY: manual manual: TEXINPUTS=$(srcdir):$(top_srcdir)/build-aux:$(TEXINPUTS) \ MAKEINFO="$(MAKEINFO) $(MAKEINFOFLAGS)" \ @@ -1,32 +1,31 @@ .\" This file is part of GDBM. -.\" Copyright (C) 2011 Free Software Foundation, Inc. +.\" Copyright (C) 2011, 2013 Free Software Foundation, Inc. .\" .\" GDBM is free software; you can redistribute it and/or modify .\" it under the terms of the GNU General Public License as published by .\" the Free Software Foundation; either version 3, or (at your option) .\" any later version. .\" .\" 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 3 "August 9, 2011" "GDBM" "GDBM User Reference" -.ds ve 1.9 +.TH GDBM 3 "May 8, 2013" "GDBM" "GDBM User Reference" .SH NAME -GDBM - The GNU database manager. Includes \fBdbm\fR and \fBndbm\fR -compatability. (Version \*(ve.) +GDBM \- The GNU database manager. Includes \fBdbm\fR and \fBndbm\fR +compatibility. .SH SYNOPSIS .nf .B #include <gdbm.h> .sp .BI "extern gdbm_error" " gdbm_errno"; .br .BI "extern char *" gdbm_version ; .br .BI "GDBM_FILE gdbm_open (const char *" name ", int " block_size ", " .ti +21 .BI "int " flags ", int " mode ", " .ti +21 @@ -191,25 +190,25 @@ database. .BI "int gdbm_store (GDBM_FILE " dbf ", datum " key ", datum " content ", int " flag ); \fIDbf\fR is the pointer returned by \fBgdbm_open\fR. \fIKey\fR is the key data. \fIContent\fR is the data to be associated with the \fIkey\fR. \fIFlag\fR can have one of the following values: .TP .B GDBM_INSERT Insert only, generate an error if key exists; .TP .B GDBM_REPLACE Replace contents if key exists. .PP -If a reader calls \fBgdbm_store\fR, the return value will be -1. +If a reader calls \fBgdbm_store\fR, the return value will be \-1. If called with \fBGDBM_INSERT\fR and \fIkey\fR is in the database, the return value will be 1. Otherwise, the return value is 0. \fINOTICE: If you store data for a key that is already in the data base, \fBgdbm\fI replaces the old data with the new data if called with \fBGDBM_REPLACE\fI. You do not get two data items for the same key and you do not get an error from \fBgdbm_store\fI. NOTICE: The size in \fBgdbm\fI is not restricted like in \fBdbm\fI or \fBndbm\fI. Your data can be as large as you want.\fR To search for some data, use: @@ -236,25 +235,25 @@ the key data to search for. If the \fIkey\fR is found within the database, the return value will be true. If nothing appropiate is found, false is returned. This routine is useful for checking for the existence of a record, without performing the memory allocation done by \fBgdbm_fetch\fR. .PP To remove some data from the database: .BI "int gdbm_delete (GDBM_FILE " dbf ", datum " key ); \fIDbf\fR is the pointer returned by \fBgdbm_open\fR. \fIKey\fR is the key data. -The return value is -1 if the item is not present or the requester is a reader. +The return value is \-1 if the item is not present or the requester is a reader. The return value is 0 if there was a successful delete. The next two routines allow for accessing all items in the database. This access is not key sequential, but it is guaranteed to visit every key in the database once. (The order has to do with the hash values.) .BI "datum gdbm_firstkey (GDBM_FILE " dbf ");" .br .BI "datum gdbm_nextkey (GDBM_FILE " dbf ", datum " key ); \fIDbf\fR is the pointer returned by \fBgdbm_open\fR. \fIKey\fR is the key data. @@ -344,25 +343,25 @@ be set to either TRUE or FALSE. .TP .B GDBM_COALESCEBLKS Set \fBfree block merging\fR to either on or off. The default is off, which is how previous versions of \fBGdbm\fR handled free blocks. If set, this option causes adjacent free blocks to be merged. This can become a CPU expensive process with time, though, especially if used in conjunction with \fBGDBM_CENTFREE\fR. \fIvalue\fR (see below) should be set to either TRUE or FALSE. \fINOTICE: This feature is still under study.\fR .PP \fIvalue\fR is the value to set \fIoption\fR to, specified as an integer pointer. \fIsize\fR is the size of the data pointed to by \fIvalue\fR. -The return value will be -1 upon failure, or 0 upon success. The global +The return value will be \-1 upon failure, or 0 upon success. The global variable \fIgdbm_errno\fR will be set upon failure. For instance, to set a database to use a cache of 10, after opening it with \fBgdbm_open\fR, but prior to accessing it in any way, the following code could be used: .sp .nf .in +5 int value = 10; ret = gdbm_setopt( dbf, GDBM_CACHESIZE, &value, sizeof(int)); .in @@ -390,48 +389,50 @@ defines gdbm_errno as an external variable.) There are a few more things of interest. First, \fBgdbm\fR files are not "sparse". You can copy them with the UNIX \fBcp(1)\fR command and they will not expand in the copying process. Also, there is a compatibility mode for use with programs that already use UNIX \fBdbm\fR. In this compatibility mode, no \fRgdbm\fR file pointer is required by the programmer, and only one file may be opened at a time. All users in compatibility mode are assumed to be writers. If the \fBgdbm\fR file is a read only, it will fail as a writer, but will also try to open it as a reader. All returned pointers in datum structures point to data that \fBgdbm\fR WILL free. They should be treated as static pointers (as standard UNIX \fBdbm\fR does). .SH LINKING -This library is accessed by specifying \fI-lgdbm\fR as the last +This library is accessed by specifying \fI\-lgdbm\fR as the last parameter to the compile line, e.g.: .sp .nf .in +5 -gcc -o prog prog.c -lgdbm +gcc \-o prog prog.c \-lgdbm .in .fi .PP If you wish to use the \fBdbm\fR or \fBndbm\fR compatibility routines, you must link in the \fIgdbm_compat\fR library as well. For example: .sp .nf .in +5 -gcc -o prog proc.c -lgdbm -lgdbm_compat +gcc \-o prog proc.c \-lgdbm \-lgdbm_compat .in .fi .\" .SH BUGS .SH "BUG REPORTS" -Send bug reports to <bug-gdbm@gnu.org>. +Send bug reports to <bug\-gdbm@gnu.org>. .SH "SEE ALSO" -dbm, ndbm -.SH AUTHOR +.BR gdbm_dump (1), +.BR gdbm_load (1), +.BR gdbmtool (1). +.SH AUTHORS by Philip A. Nelson, Jason Downs and Sergey Poznyakoff. .SH COPYRIGHT Copyright \(co 1990 - 2011 Free Software Foundation, Inc. GDBM is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 1, 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 diff --git a/doc/gdbm.texinfo b/doc/gdbm.texinfo index 9f0af5b..17f47f9 100644 --- a/doc/gdbm.texinfo +++ b/doc/gdbm.texinfo @@ -109,25 +109,25 @@ Functions: * Sync:: Insure all writes to disk have competed. * Flat files:: Export and import to Flat file format. * Errors:: Convert internal error codes into English. * Options:: Setting internal options. * Locking:: File locking. * Error codes:: Error codes returned by @code{gdbm} calls. * Variables:: Two useful variables. * Compatibility:: Compatibility with UNIX dbm and ndbm. Programs -* testgdbm:: Test and modify a GDBM database. +* gdbmtool:: Examine and modify a GDBM database. * gdbm_dump:: Dump the database into a flat file. * gdbm_load:: Load the database from a flat file. * gdbmexport:: Export a database into a portable format. * Exit codes:: Exit codes returned by GDBM utilities. Other topics: * Bugs:: Problems and bugs. * Resources:: Additional resources, * GNU Free Documentation License:: Document license. * Index:: Index @@ -1608,341 +1608,337 @@ the returned datum points to the memory managed by the compatibility library. The application should never free it. @end deftypefn @deftypefn {dbm} datum nextkey (datum @var{key}) Continues the iteration started by a call to @code{firstkey}. Returns the next key in the database. If the iteration covered all keys in the database, the @code{dptr} member of the returned datum is @samp{NULL}. Otherwise, the @code{dptr} member of the returned datum points to the memory managed by the compatibility library. The application should never free it. @end deftypefn -@node testgdbm -@chapter Test and modify a GDBM database. -@prindex testgdbm +@node gdbmtool +@chapter Examine and modify a GDBM database. +@prindex gdbmtool -The @command{testgdbm} utility allows you to view and modify an +The @command{gdbmtool} utility allows you to view and modify an existing @acronym{GDBM} database or to create a new one. -@cindex default database, @command{testgdbm} +@cindex default database, @command{gdbmtool} @flindex junk.gdbm When invoked without arguments, it tries to open a database file called @file{junk.gdbm}, located in the current working directory. You can change this default by supplying the name of the database to use as -the only argument to @command{testgdbm}, e.g.: +the only argument to @command{gdbmtool}, e.g.: @example -$ testgdbm file.db +$ gdbmtool file.db @end example -@cindex read-only mode, @command{testgdbm} -@cindex @option{-r}, @command{testgdbm} option -@cindex @option{--read-only}, @command{testgdbm} option +@cindex read-only mode, @command{gdbmtool} +@cindex @option{-r}, @command{gdbmtool} option +@cindex @option{--read-only}, @command{gdbmtool} option The database will be opened in read-write mode, unless the @option{-r} (@option{--read-only}) option is specified, in which case it will be opened only for reading. -@cindex creating a database, @command{testgdbm} -@cindex @option{-n}, @command{testgdbm} option -@cindex @option{--newdb}, @command{testgdbm} option -If the database does not exist, @command{testgdbm} will create it. +@cindex creating a database, @command{gdbmtool} +@cindex @option{-n}, @command{gdbmtool} option +@cindex @option{--newdb}, @command{gdbmtool} option +If the database does not exist, @command{gdbmtool} will create it. There is a special option @option{-n} (@option{--newdb}, which instructs the utility to create a new database. If it is used and if the database already exists, it will be deleted, so use it sparingly. @menu * invocation:: * shell:: @end menu @node invocation -@section testgdbm invocation -@cindex command line options, @command{testgdbm} +@section gdbmtool invocation +@cindex command line options, @command{gdbmtool} -The following table summarizes all @command{testgdbm} command line +The following table summarizes all @command{gdbmtool} command line options: @table @option @item -b @var{size} @itemx --block-size=@var{size} Set block size. @item -c @var{size} @itemx --cache-size=@var{size} Set cache size. @item -h @itemx --help Print a concise help summary. @item -n @itemx --newdb Create the database. @item -l @itemx --no-lock Disable file locking. @item -m @itemx --no-mmap Disable mmap. +@item -q +@itemx --quiet +Don't print the usual welcome banner at startup. @item -r @itemx --read-only Open the database in read-only mode. @item -s @itemx --synchronize Synchronize to the disk after each write. @item -V @itemx --version Print program version and licensing information and exit. @item --usage Print a terse invocation syntax summary along with a list of available command line options. @end table @node shell -@section testgdbm interactive mode -@cindex interactive mode, @command{testgdbm} +@section gdbmtool interactive mode +@cindex interactive mode, @command{gdbmtool} -After successful startup, @command{testgdbm} starts a loop, in which +After successful startup, @command{gdbmtool} starts a loop, in which it reads commands from the user, executes them and prints the results on the standard output. If the standard input is attached to a console, -@command{testgdbm} runs in interactive mode, which is indicated by its +@command{gdbmtool} runs in interactive mode, which is indicated by its @dfn{prompt}: @example -testgdbm> _ +gdbmtool> _ @end example The utility finishes when it reads the @samp{quit} command (see below) or detects end-of-file on its standard input, whichever occurs first. -A @command{testgdbm} command consists of a @dfn{command verb}, +A @command{gdbmtool} command consists of a @dfn{command verb}, optionally followed by one or two @dfn{arguments}, separated by any amount of white space. A command verb can be entered either in full or in an abbreviated form, as long as that abbreviation does not match any other verb. For example, @samp{co} can be used instead of @samp{count} and @samp{ca} instead of @samp{cache}. Furthermore, many command verbs also have single-letter forms, called @dfn{command letters}. An argument is any sequence of non-whitespace characters. Notice, that currently there is no way to enter arguments containing white space. This limitation will be removed in future releases. Each command takes at most two @dfn{formal parameters}, which can be optional or mandatory. If the number of actual arguments is less than the -number of mandatory parameters, @command{testgdbm} will prompt you to +number of mandatory parameters, @command{gdbmtool} will prompt you to supply missing arguments. For example, the @samp{store} command takes two mandatory parameters, so if you invoked it with no arguments, you would be prompted twice to supply the necessary data, as shown in example below: @example -testgdbm> @kbd{store} +gdbmtool> @kbd{store} key> @kbd{three} data> @kbd{3} @end example However, such prompting is possible only in interactive mode. In non-interactive mode (e.g.@: when running a script), all arguments must -be supplied with each command, otherwise @command{testgdbm} will report an +be supplied with each command, otherwise @command{gdbmtool} will report an error and exit immediately. @anchor{pager} -@cindex pager, @command{testgdbm} +@cindex pager, @command{gdbmtool} @cindex @env{PAGER} Some commands produce excessive amounts of output. To help you follow -it, @command{testgdbm} uses a pager utility to display such +it, @command{gdbmtool} uses a pager utility to display such output. The name of the pager utility is taken from the environment variable @env{PAGER}. The pager is invoked only in interactive mode and only if the estimated number of output lines is greater then the number of lines on your screen. @anchor{nul-termination} -Many of the @command{testgdbm} commands operate on database key and +Many of the @command{gdbmtool} commands operate on database key and data values. The utility assumes that both keys and data are @acronym{ASCII} strings, either nul-terminated or not. By default, it is assumed that strings are nul-terminated. You can change this by using @code{z} (@code{key-zero}, for keys) and @code{Z} (@code{data-zero}, for data) commands. The following table summarizes all available commands: @deffn {command verb} count -@deffnx {command abbrev} co @deffnx {command letter} c Print the number of entries in the database. @end deffn @deffn {command verb} delete @var{key} -@deffnx {command abbrev} de @var{key} @deffnx {command letter} d @var{key} -Delete entry with a given @var{key} +Delete entry with the given @var{key} @end deffn -@anchor{testgdbm export} +@anchor{gdbmtool export} @deffn {command verb} export @var{file-name} [truncate] [binary|ascii] -@deffnx {command abbrev} e @var{file-name} [truncate] [binary|ascii] +@deffnx {command letter} e @var{file-name} [truncate] [binary|ascii] Export the database to the flat file @var{file-name}. @xref{Flat files}, for a description of the flat file format and its purposes. This -command will not overwrite an existing file, unless the argument -@samp{truncate} is also given. Another optional argument determines -the type of dump (@pxref{Flat files}). By default, ASCII dump is -created. +command will not overwrite an existing file, unless the +@samp{truncate} parameter is also given. Another optional argument +determines the type of the dump (@pxref{Flat files}). By default, ASCII +dump is created. See also @ref{gdbmexport}. @end deffn @deffn {command verb} fetch @var{key} -@deffnx {command abbrev} fe @var{key} @deffnx {command letter} f @var{key} -Fetch and display a record with the given @var{key}. +Fetch and display the record with the given @var{key}. @end deffn -@anchor{testgdbm import} +@anchor{gdbmtool import} @deffn {command verb} import @var{file-name} [replace] [nometa] -@deffnx {command abbrev} i @var{file-name} [replace] [nometa] +@deffnx {command letter} i @var{file-name} [replace] [nometa] Import data from a flat dump file @var{file-name} (@pxref{Flat files}). If the word @samp{replace} is given as an argument, any records with the same keys as the already existing ones will replace them. The word @samp{nometa} turns off restoring meta-information from the dump file. @end deffn @deffn {command verb} list -@deffnx {command abbrev} l +@deffnx {command letter} l List the contents of the database (@pxref{pager}). @end deffn @deffn {command verb} next [@var{key}] -@deffnx {command abbrev} n [@var{key}] -Sequential access: fetch and display a next record. If @var{key} is -given, a record following one with this key will be fetched. -Otherwise, the key supplied by the latest @code{1}, @code{2} or -@var{n} command will be used. +@deffnx {command letter} n [@var{key}] +Sequential access: fetch and display the next record. If the @var{key} is +given, the record following the one with this key will be fetched. See also @code{first}, below. @xref{Sequential}, for more information on sequential access. @end deffn +@deffn {command verb} prompt @var{text} +Changes the command prompt to the string @var{text}. The string can +contain @dfn{escape sequences}, the special entities consisting of the +@samp{%} character followed by another character. These sequences are +replaced in the generated prompt as follows: + +@multitable @columnfractions 0.4 0.5 +@headitem Sequence @tab Expansion +@item %f @tab name of the db file +@item %% @tab % +@end multitable +@end deffn + @deffn {command verb} quit -@deffnx {command abbrev} q +@deffnx {command letter} q Close the database and quit the utility. @end deffn @deffn {command verb} store @var{key} @var{data} -@deffnx {command abbrev} sto @var{key} @var{data} @deffnx {command letter} s @var{key} @var{data} Store the @var{data} with @var{key} in the database. If @var{key} already exists, its data will be replaced. @end deffn @deffn {command verb} first -@deffnx {command abbrev} fi @deffnx {command letter} 1 Fetch and display the first record in the database. Subsequent -records can be fetched using @code{next} command (see above). +records can be fetched using the @code{next} command (see above). @xref{Sequential}, for more information on sequential access. @end deffn @deffn {command verb} read @var{file} [replace] -@deffnx {command abbrev} rea @var{file} [replace] @deffnx {command letter} < @var{file} [replace] Read entries from @var{file} and store them in the database. If the -word @samp{replace} is given as the second argument, any existing -records with matching keys will be replaced. +@samp{replace} parameter is given, any existing records with matching +keys will be replaced. @end deffn @deffn {command verb} reorganize -@deffnx {command abbrev} reo @deffnx {command letter} r Reorganize the database (@pxref{Reorganization}). @end deffn @deffn {command verb} key-zero -@deffnx {command abbrev} k @deffnx {command letter} z Toggle key nul-termination. Use @code{status} to inspect the current state. @xref{nul-termination}. @end deffn @deffn {command verb} avail -@deffnx {command abbrev} a @deffnx {command letter} A Print the @dfn{avail list}. @end deffn @deffn {command verb} bucket -@deffnx {command abbrev} b @deffnx {command letter} B Print the bucket number @var{num}. @end deffn @deffn {command verb} current -@deffnx {command abbrev} cu @deffnx {command letter} C Print the current bucket. @end deffn @deffn {command verb} dir -@deffnx {command abbrev} di @deffnx {command letter} D Print hash directory. @end deffn @deffn {command verb} header -@deffnx {command abbrev} hea @deffnx {command letter} F Print file header. @end deffn @deffn {command verb} hash @var{key} -@deffnx {command abbrev} ha @var{key} @deffnx {command letter} H @var{key} Compute and display the hash value for the given @var{key}. @end deffn @deffn {command verb} cache -@deffnx {command abbrev} ca @deffnx {command letter} K Print the bucket cache. @end deffn @deffn {command verb} status -@deffnx {command abbrev} sta @deffnx {command letter} S Print current program status. The following example shows the information displayed: @example Database file: junk.gdbm Zero terminated keys: yes Zero terminated data: yes @end example @end deffn @deffn {command verb} version -@deffnx {command abbrev} v +@deffnx {command letter} v Print the version of @command{gdbm}. @end deffn @deffn {command verb} data-zero -@deffnx {command abbrev} da @deffnx {command letter} Z Toggle data nul-termination. Use @code{status} to examine the current status. @xref{nul-termination}. @end deffn @deffn {command verb} help -@deffnx {command abbrev} hel @deffnx {command letter} ? Print a concise command summary, showing each command letter and verb with its parameters and a short description of what it does. Optional arguments are enclosed in square brackets. @end deffn @node gdbm_dump @chapter The @command{gdbm_dump} utility @prindex gdbm_dump The @command{gdbm_dump} utility creates a flat file dump of a GDBM database (@pxref{Flat files}). It takes one mandatory argument: the 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 <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 --- /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 --- /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. |