From 5e3403fbd39b2cafdaa662768a61d8fb0f45e244 Mon Sep 17 00:00:00 2001 From: Sergey Poznyakoff Date: Tue, 15 Nov 2011 15:23:56 +0000 Subject: Update the docs. Improve dump/load utilities. * doc/gdbm.texinfo: Reorganize the material. Document gdbm_load and gdbm_dump utilities. * src/gdbm.h.in (GDBM_META_MASK_MODE) (GDBM_META_MASK_OWNER): New constant. (gdbm_load,gdbm_load_from_file): Take an additional argument: meta_flags, which masks out restoring certain meta-data. * src/gdbm_dump.c: Remove -b option. The -H option takes symbolic format names. Use the standard exit codes. * src/gdbm_load.c: New options: --mode, --user and --no-meta. Use the standard exit codes. * src/gdbmapp.h (EXIT_OK, EXIT_FATAL, EXIT_MILD) (EXIT_USAGE): New constants. * src/gdbmload.c (gdbm_load,gdbm_load_from_file): Take an additional argument, which masks out restoring certain meta-data. --- doc/gdbm.texinfo | 1621 +++++++++++++++++++++++++++++------------------------- 1 file changed, 864 insertions(+), 757 deletions(-) (limited to 'doc') diff --git a/doc/gdbm.texinfo b/doc/gdbm.texinfo index 1e51322..ec6701f 100644 --- a/doc/gdbm.texinfo +++ b/doc/gdbm.texinfo @@ -112,18 +112,20 @@ Functions: * 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. * 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: -* Error codes:: Error codes returned by @code{gdbm} calls. -* Variables:: Two useful variables. -* Compatibility:: Compatibility with UNIX dbm and ndbm. * Bugs:: Problems and bugs. * Resources:: Additional resources, @@ -714,7 +716,9 @@ for a detailed discussion. @anchor{gdbm_load function} @deftypefn {gdbm interface} int gdbm_load (GDBM_FILE *@var{pdbf}, @ - const char *@var{filename}, int @var{flag}, unsigned long *@var{errline}) + const char *@var{filename}, int @var{flag}, @ + int @var{meta_mask}, @ + unsigned long *@var{errline}) Loads data from the dump file @var{filename} into the database pointed to by @var{pdbf}. The latter can point to @samp{NULL}, in which case the function will try to create a new database. If it succeeds, the @@ -727,6 +731,18 @@ set @code{gdbm_errno} to @samp{GDBM_NO_DBNAME} and return The @var{flag} has the same meaning as the @var{flag} argument to the @code{gdbm_store} function (@pxref{Store}). +The @var{meta_mask} argument can be used to disable restoring certain +bits of file's meta-data from the information in the input dump file. +It is a binary OR of zero or more of the following: + +@table @asis +@item GDBM_META_MASK_MODE +Do not restore file mode. + +@item GDBM_META_MASK_OWNER +Do not restore file owner. +@end table + The function returns 0 upon successful completion or -1 on fatal errors and 1 on mild (non-fatal) errors. @@ -799,7 +815,8 @@ Format of the dump file. See the @var{format} argument to the @end deftypefn @deftypefn {gdbm interface} int gdbm_load_from_file (GDBM_FILE *@var{pdbf}, @ - FILE *@var{fp}, int @var{replace}, unsigned long *@var{line}) + FILE *@var{fp}, int @var{replace}, int @var{meta_mask}, @ + unsigned long *@var{line}) This is an alternative entry point to @code{gdbm_dump}. It writes the output to @var{fp} which must be a file open for writing. The rest of arguments is the same as for @code{gdbm_load} (excepting of course @@ -1054,927 +1071,1017 @@ can be used as an argument to @code{flock}, @code{lockf} or similar calls. @end deftypefn -@node testgdbm -@chapter Test and modify a GDBM database. -@prindex testgdbm +@node Variables +@chapter Useful global variables. -The @command{testgdbm} utility allows you to view and modify an -existing @acronym{GDBM} database or to create a new one. +The following global variables and constants are available: -@cindex default database, @command{testgdbm} -@cindex @option{-g}, @command{testgdbm} option -@cindex @option{-f}, @command{testgdbm} option -@cindex @option{--file}, @command{testgdbm} option -@flindex junk.gdbm -When invoked without options, it tries to open a database file called -@file{junk.gdbm}, located in the current working directory. You can -change this default using the @option{--file} (@option{-f}) command -line option@footnote{For compatibility with earlier versions, the -@option{-g} option acts as an alias to @option{-f}}. This -option takes a single argument, specifying the file name to open, e.g.: +@deftypevar gdbm_error gdbm_errno +This variable contains error code from the last failed @code{gdbm} +call. @xref{Error codes}, for a list of available error codes and +their descriptions. -@example -$ testgdbm -f file.db -@end example +Use @code{gdbm_strerror} (@pxref{Errors}) to convert it to a +descriptive text. +@end deftypevar -@cindex read-only mode, @command{testgdbm} -@cindex @option{-r}, @command{testgdbm} option -@cindex @option{--read-only}, @command{testgdbm} 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. +@deftypevar {const char *} gdbm_errlist[] +This variable is an array of error descriptions, which is used by +@code{gdbm_strerror} to convert error codes to human-readable text +(@pxref{Errors}). You can access it directly, if you wish so. It +contains @code{_GDBM_MAX_ERRNO + 1} elements and can be directly +indexed by the error code to obtain a corresponding descriptive +text. +@end deftypevar -@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. -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. +@defvr {Constant} _GDBM_MIN_ERRNO +The minimum error code used by @code{gdbm}. +@end defvr -@menu -* invocation:: -* shell:: -@end menu +@defvr {Constant} _GDBM_MAX_ERRNO +The maximum error code used by @code{gdbm}. +@end defvr -@node invocation -@section testgdbm invocation -@cindex command line options, @command{testgdbm} +@cindex version number +@deftypevar {const char *} gdbm_version +A string containing the version information. +@end deftypevar -The following table summarizes all @command{testgdbm} command line -options: +@deftypevar {int const} gdbm_version_number[3] +This variable contains the @code{gdbm} version numbers: -@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 -f @var{file} -@itemx -g @var{file} -@itemx --file=@var{file} -Operate on @var{file} instead of the default @file{junk.gdbm}. -@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 -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 +@multitable @columnfractions 0.4 0.5 +@headitem Index @tab Meaning +@item 0 @tab Major number +@item 1 @tab Minor number +@item 2 @tab Patchlevel number +@end multitable -@node shell -@section testgdbm interactive mode -@cindex interactive mode, @command{testgdbm} +Additionally, the following constants are defined in the @file{gdbm.h} +file: -After successful startup, @command{testgdbm} 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 -@dfn{prompt}: +@table @asis +@kwindex GDBM_VERSION_MAJOR +@item GDBM_VERSION_MAJOR +Major number. -@example -testgdbm> _ -@end example +@kwindex GDBM_VERSION_MINOR +@item GDBM_VERSION_MINOR +Minor number. -The utility finishes when it reads the @samp{quit} command (see below) or -detects end-of-file on its standard input, whichever occurs first. +@kwindex GDBM_VERSION_PATCH +@item GDBM_VERSION_PATCH +Patchlevel number. +@end table -A @command{testgdbm} 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}. +These can be used to verify whether the header file matches the library. +@end deftypevar -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. +To compare two split-out version numbers, use the following function: -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 -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: +@deftypefn {gdbm interface} int gdbm_version_cmp (int const @var{a}[3], @ + int const @var{b}[3]) +Compare two version numbers. Return @samp{-1} if @var{a} is less than +@var{b}, @samp{1} if @var{a} is greater than @var{b} and @samp{0} if +they are equal. + +Comparison is done from left to right, so that: @example -testgdbm> @kbd{store} -key> @kbd{three} -data> @kbd{3} -@end example +a = @{ 1, 8, 3 @}; +b = @{ 1, 8, 3 @}; +gdbm_version_cmp (a, b) @result{} 0 -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 -error and exit immediately. +a = @{ 1, 8, 3 @}; +b = @{ 1, 8, 2 @}; +gdbm_version_cmp (a, b) @result{} 1 -@anchor{pager} -@cindex pager, @command{testgdbm} -@cindex @env{PAGER} -Some commands produce excessive amounts of output. To help you follow -it, @command{testgdbm} 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. +a = @{ 1, 8, 3 @}; +b = @{ 1, 9. 0 @}; +gdbm_version_cmp (a, b) @result{} -1 +@end example +@end deftypefn -@anchor{nul-termination} -Many of the @command{testgdbm} 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. +@node Error codes +@chapter Error codes +@cindex error codes -The following table summarizes all available commands: +This chapter summarizes error codes which can be set by the +functions in @code{gdbm} library. -@deffn {command verb} count -@deffnx {command abbrev} co -@deffnx {command letter} c -Print the number of entries in the database. -@end deffn +@table @asis +@kwindex GDBM_NO_ERROR +@item GDBM_NO_ERROR +No error occurred. -@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} -@end deffn +@kwindex GDBM_MALLOC_ERROR +@item GDBM_MALLOC_ERROR +Memory allocation failed. Not enough memory. -@anchor{testgdbm export} -@deffn {command verb} export @var{file-name} [truncate] -@deffnx {command abbrev} e @var{file-name} [truncate] -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 word -@samp{truncate} is given as its second argument. +@kwindex GDBM_BLOCK_SIZE_ERROR +@item GDBM_BLOCK_SIZE_ERROR +This error is set by the @code{gdbm_open} function (@pxref{Open}), if +the value of its @var{block_size} argument is incorrect. -See also @ref{gdbmexport}. -@end deffn +@kwindex GDBM_FILE_OPEN_ERROR +@item GDBM_FILE_OPEN_ERROR +The library was not able to open a disk file. This can be set by +@code{gdbm_open} (@pxref{Open}), @code{gdbm_export} and +@code{gdbm_import} functions (@pxref{Flat files}). -@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}. -@end deffn - -@anchor{testgdbm import} -@deffn {command verb} import @var{file-name} [replace] -@deffnx {command abbrev} i @var{file-name} [replace] -Import data from a flat dump file @var{file-name} -(@pxref{Flat files}). If the word @samp{replace} is given -as the second argument, any records with the same keys as the already -existing ones will replace them. -@end deffn +Inspect the value of the system @code{errno} variable to get more +detailed diagnostics. -@deffn {command verb} list -@deffnx {command abbrev} l -List the contents of the database (@pxref{pager}). -@end deffn +@kwindex GDBM_FILE_WRITE_ERROR +@item GDBM_FILE_WRITE_ERROR +Writing to a disk file failed. This can be set by +@code{gdbm_open} (@pxref{Open}), @code{gdbm_export} and +@code{gdbm_import} functions. -@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. +Inspect the value of the system @code{errno} variable to get more +detailed diagnostics. -See also @code{first}, below. +@kwindex GDBM_FILE_SEEK_ERROR +@item GDBM_FILE_SEEK_ERROR +Positioning in a disk file failed. This can be set by +@code{gdbm_open} (@pxref{Open}) function. -@xref{Sequential}, for more information on sequential access. -@end deffn +Inspect the value of the system @code{errno} variable to get a more +detailed diagnostics. -@deffn {command verb} quit -@deffnx {command abbrev} q -Close the database and quit the utility. -@end deffn +@kwindex GDBM_FILE_READ_ERROR +@item GDBM_FILE_READ_ERROR +Reading from a disk file failed. This can be set by +@code{gdbm_open} (@pxref{Open}), @code{gdbm_export} and +@code{gdbm_import} functions. -@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 +Inspect the value of the system @code{errno} variable to get a more +detailed diagnostics. -@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). -@xref{Sequential}, for more information on sequential access. -@end deffn +@kwindex GDBM_BAD_MAGIC_NUMBER +@item GDBM_BAD_MAGIC_NUMBER +The file given as argument to @code{gdbm_open} function is not a valid +@code{gdbm} file: it has a wrong magic number. -@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. -@end deffn +@kwindex GDBM_EMPTY_DATABASE +@item GDBM_EMPTY_DATABASE +The file given as argument to @code{gdbm_open} function is not a valid +@code{gdbm} file: it has zero length. -@deffn {command verb} reorganize -@deffnx {command abbrev} reo -@deffnx {command letter} r -Reorganize the database (@pxref{Reorganization}). -@end deffn +@kwindex GDBM_CANT_BE_READER +@item GDBM_CANT_BE_READER +This error code is set by the @code{gdbm_open} function if it is not +able to lock file when called in @samp{GDBM_READER} mode (@pxref{Open, +GDBM_READER}). -@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 +@kwindex GDBM_CANT_BE_WRITER +@item GDBM_CANT_BE_WRITER +This error code is set by the @code{gdbm_open} function if it is not +able to lock file when called in writer mode (@pxref{Open}). -@deffn {command verb} avail -@deffnx {command abbrev} a -@deffnx {command letter} A -Print the @dfn{avail list}. -@end deffn +@kwindex GDBM_READER_CANT_DELETE +@item GDBM_READER_CANT_DELETE +Set by the @code{gdbm_delete} (@pxref{Delete}) if it attempted to +operate on a database that is open in read-only mode (@pxref{Open, +GDBM_READER}). -@deffn {command verb} bucket -@deffnx {command abbrev} b -@deffnx {command letter} B -Print the bucket number @var{num}. -@end deffn +@kwindex GDBM_READER_CANT_STORE +@item GDBM_READER_CANT_STORE +Set by the @code{gdbm_store} (@pxref{Store}) if it attempted to +operate on a database that is open in read-only mode (@pxref{Open, +GDBM_READER}). -@deffn {command verb} current -@deffnx {command abbrev} cu -@deffnx {command letter} C -Print the current bucket. -@end deffn +@kwindex GDBM_READER_CANT_REORGANIZE +@item GDBM_READER_CANT_REORGANIZE +Set by the @code{gdbm_reorganize} (@pxref{Reorganization}) if it attempted to +operate on a database that is open in read-only mode (@pxref{Open, +GDBM_READER}). -@deffn {command verb} dir -@deffnx {command abbrev} di -@deffnx {command letter} D -Print hash directory. -@end deffn +@kwindex GDBM_UNKNOWN_UPDATE +@item GDBM_UNKNOWN_UPDATE +Currently unused. Reserved for future uses. -@deffn {command verb} header -@deffnx {command abbrev} hea -@deffnx {command letter} F -Print file header. -@end deffn +@kwindex GDBM_ITEM_NOT_FOUND +@item GDBM_ITEM_NOT_FOUND +Requested item was not found. This error is set by @code{gdbm_delete} +(@pxref{Delete}) and @code{gdbm_fetch} (@pxref{Fetch}) when the requested +@var{key} value is not found in the database. -@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 +@kwindex GDBM_REORGANIZE_FAILED +@item GDBM_REORGANIZE_FAILED +The @code{gdbm_reorganize} function is not +able to create a temporary database. @xref{Reorganization}. -@deffn {command verb} cache -@deffnx {command abbrev} ca -@deffnx {command letter} K -Print the bucket cache. -@end deffn +@kwindex GDBM_CANNOT_REPLACE +@item GDBM_CANNOT_REPLACE +Cannot replace existing item. This error is set by the +@code{gdbm_store} if the requested @var{key} value is found in the +database and the @var{flag} parameter is not @samp{GDBM_REPLACE}. +@xref{Store}, for a detailed discussion. -@deffn {command verb} status -@deffnx {command abbrev} sta -@deffnx {command letter} S -Print current program status. The following example shows the -information displayed: +@kwindex GDBM_ILLEGAL_DATA +@item GDBM_ILLEGAL_DATA +Either @var{key} or @var{content} parameter was wrong in a call to +to @code{gdbm_store} (@pxref{Store}). -@example -Database file: junk.gdbm -Zero terminated keys: yes -Zero terminated data: yes -@end example -@end deffn +@kwindex GDBM_OPT_ALREADY_SET +@item GDBM_OPT_ALREADY_SET +Requested option can be set only once and was already set. This error +is returned by the @code{gdbm_setopt} function. @xref{Options, +GDBM_CACHESIZE}. -@deffn {command verb} version -@deffnx {command abbrev} v -Print the version of @command{gdbm}. -@end deffn +@kwindex GDBM_OPT_ILLEGAL +@item GDBM_OPT_ILLEGAL +The @var{option} argument is not valid or the @var{value} argument +points to an invalid value in a call to @code{gdbm_setopt} function. +@xref{Options}. -@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. +@kwindex GDBM_BYTE_SWAPPED +@item GDBM_BYTE_SWAPPED +The @code{gdbm_open} function (@pxref{Open}) attempts to open a +database which is created on a machine with different byte ordering. -@xref{nul-termination}. -@end deffn +@kwindex GDBM_BAD_FILE_OFFSET +@item GDBM_BAD_FILE_OFFSET +The @code{gdbm_open} function (@pxref{Open}) sets this error code if +the file it tries to open has a wrong magic number. -@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 +@kwindex GDBM_BAD_OPEN_FLAGS +@item GDBM_BAD_OPEN_FLAGS +Set by the @code{gdbm_export} function if supplied an invalid +@var{flags} argument. @xref{Flat files}. -@node gdbm_dump -@chapter The @command{gdbm_dump} utility -@prindex gdbm_dump -FIXME +@kwindex GDBM_FILE_STAT_ERROR +@item GDBM_FILE_STAT_ERROR +Getting information about a disk file failed. The system @code{errno} +will give more details about the error. -@node gdbm_load -@chapter The @command{gdbm_load} utility -@prindex gdbm_load -FIXME +This error can be set by the following functions: @code{gdbm_open}, +@code{gdbm_reorganize}. -@node gdbmexport -@chapter Export a database into a portable format. -@prindex gdbmexport +@kwindex GDBM_FILE_EOF +@item GDBM_FILE_EOF +End of file was encountered where more data was expected to be +present. This error can occur when fetching data from the database +and usually means that the database is truncated or otherwise corrupted. -The @command{gdbmexport} utility converts the database into a binary -flat format. Files in this format can be used to populate -databases using the @code{gdbm_load} function (@pxref{Flat files, -gdbm_load}) or the @code{i} command of @command{testgdbm} utility -(@pxref{testgdbm import}). In many cases files in this format are suitable for -sending over the network to populate the database on another machine. -The only exception to this are databases whose records contain -non-@acronym{ASCII} data (e.g.@: @acronym{C} structures, integers -etc.). For such databases you will be better off by writing a -specialized utility to convert them to an architecture-independent -format. - -If @command{gdbmexport} is linked with @file{libgdbm} -version 1.8.3, it can be used to convert databases from old to new -format. +This error can be set by any GDBM function that does I/O. Some of +these functions are: @code{gdbm_delete}, @code{gdbm_exists}, +@code{gdbm_fetch}, @code{gdbm_export}, @code{gdbm_import}, +@code{gdbm_reorganize}, @code{gdbm_firstkey}, @code{gdbm_nextkey}, +@code{gdbm_store}. -The utility takes two mandatory arguments: the name of the database -file to convert and the output file name, e.g.: +@kwindex GDBM_NO_DBNAME +@item GDBM_NO_DBNAME +Output database name is not specified. This error code is set by +@code{gdbm_load} (@pxref{gdbm_load function,,gdbm_load}) if the first +argument points to @samp{NULL} and the input file does not specify the +database name. -@example -$ gdbmexport junk.gdbm junk.flat -@end example - -In addition two options are understood: +@kwindex GDBM_ERR_FILE_OWNER +@item GDBM_ERR_FILE_OWNER +This error code is set by @code{gdbm_load} if it is unable to restore +database file owner. It is a mild error condition, meaning that the +data have been restored successfully, only changing the target file +owner failed. Inspect the system @code{errno} variable to get a more +detailed diagnostics. -@table @option -@item -h -Display short usage summary and exit. +@kwindex GDBM_ERR_FILE_MODE +@item GDBM_ERR_FILE_MODE +This error code is set by @code{gdbm_load} if it is unable to restore +database file mode. It is a mild error condition, meaning that the data +have been restored successfully, only changing the target file owner +failed. Inspect the system @code{errno} variable to get a more +detailed diagnostics. -@item -v -Display program version and licensing information, and exit. @end table -@node Variables -@chapter Useful global variables. - -The following global variables and constants are available: +@node Compatibility +@chapter Compatibility with standard @code{dbm} and @code{ndbm}. -@deftypevar gdbm_error gdbm_errno -This variable contains error code from the last failed @code{gdbm} -call. @xref{Error codes}, for a list of available error codes and -their descriptions. +@cindex compatibility layer +@code{Gdbm} includes a compatibility layer, which provides traditional +@samp{ndbm} and older @samp{dbm} functions. The layer is compiled and +installed if the @option{--enable-libgdbm-compat} option is used when +configuring the package. -Use @code{gdbm_strerror} (@pxref{Errors}) to convert it to a -descriptive text. -@end deftypevar +@findex ndbm.h +@findex dbm.h +@findex libgdbm_compat +The compatibility layer consists of two header files: @file{ndbm.h} +and @file{dbm.h} and the @file{libgdbm_compat} library. -@deftypevar {const char *} gdbm_errlist[] -This variable is an array of error descriptions, which is used by -@code{gdbm_strerror} to convert error codes to human-readable text -(@pxref{Errors}). You can access it directly, if you wish so. It -contains @code{_GDBM_MAX_ERRNO + 1} elements and can be directly -indexed by the error code to obtain a corresponding descriptive -text. -@end deftypevar +Older programs using @code{ndbm} or @code{dbm} interfaces can +use @file{libgdbm_compat} without any changes. To link a program with +the compatibility library, add the following two options to the +@command{cc} invocation: @option{-lgdbm -lgdbm_compat}. The @option{-L} +option may also be required, depending on where @code{gdbm} is +installed, e.g.: -@defvr {Constant} _GDBM_MIN_ERRNO -The minimum error code used by @code{gdbm}. -@end defvr +@example +cc ... -L/usr/local/lib -lgdbm -lgdbm_compat +@end example -@defvr {Constant} _GDBM_MAX_ERRNO -The maximum error code used by @code{gdbm}. -@end defvr +@cindex @samp{dir} file +@cindex @samp{pag} file +Databases created and manipulated by the compatibility interfaces +consist of two different files: @file{@var{file}.dir} and +@file{@var{file}.pag}. This is required by the @acronym{POSIX} +specification and corresponds to the traditional usage. Note, +however, that despite the similarity of the naming convention, +actual data stored in these files has not the same format as +in the databases created by other @code{dbm} or @code{ndbm} +libraries. In other words, you cannot access a standard UNIX +@code{dbm} file with GNU @code{dbm}! -@cindex version number -@deftypevar {const char *} gdbm_version -A string containing the version information. -@end deftypevar +GNU @code{dbm} files are not @code{sparse}. You can copy them with +the usual @code{cp} command and they will not expand in the copying +process. -@deftypevar {int const} gdbm_version_number[3] -This variable contains the @code{gdbm} version numbers: +@menu +* ndbm:: NDBM interface functions. +* dbm:: DBM interface functions. +@end menu -@multitable @columnfractions 0.4 0.5 -@headitem Index @tab Meaning -@item 0 @tab Major number -@item 1 @tab Minor number -@item 2 @tab Patchlevel number -@end multitable +@node ndbm +@section NDBM interface functions. +@cindex NDBM functions -Additionally, the following constants are defined in the @file{gdbm.h} -file: +The functions below implement the @acronym{POSIX} @samp{ndbm} interface: -@table @asis -@kwindex GDBM_VERSION_MAJOR -@item GDBM_VERSION_MAJOR -Major number. +@deftypefn {ndbm} {DBM *} dbm_open (char *@var{file}, int @var{flags}, int @var{mode}) +Opens a database. The @var{file} argument is the full name of the +database file to be opened. The function opens two files: +@file{@var{file}.pag} and @file{@var{file}.dir}. The @var{flags} and +@var{mode} arguments have the same meaning as the second and third +arguments of +@ifhtml +@uref{http://www.manpagez.com/man/2/open,,open(2)}, +@end ifhtml +@ifnothtml +@code{open} (@pxref{open,,open a file,open(2), open(2) man page}), +@end ifnothtml +except that a database opened for write-only access opens the files +for read and write access and the behavior of the @code{O_APPEND} flag is +unspecified. -@kwindex GDBM_VERSION_MINOR -@item GDBM_VERSION_MINOR -Minor number. +The function returns a pointer to the @code{DBM} structure describing +the database. This pointer is used to refer to this database in all +operations described below. -@kwindex GDBM_VERSION_PATCH -@item GDBM_VERSION_PATCH -Patchlevel number. -@end table +Any error detected will cause a return value of @samp{NULL} and an +appropriate value will be stored in @code{gdbm_errno} +(@pxref{Variables}). +@end deftypefn -These can be used to verify whether the header file matches the library. -@end deftypevar +@deftypefn {ndbm} void dbm_close (DBM *@var{dbf}) +Closes the database. The @var{dbf} argument must be a pointer +returned by an earlier call to @code{dbm_open}. +@end deftypefn -To compare two split-out version numbers, use the following function: +@deftypefn {ndbm} datum dbm_fetch (DBM *@var{dbf}, datum @var{key}) +Reads a record from the database with the matching key. The @var{key} +argument supplies the key that is being looked for. -@deftypefn {gdbm interface} int gdbm_version_cmp (int const @var{a}[3], @ - int const @var{b}[3]) -Compare two version numbers. Return @samp{-1} if @var{a} is less than -@var{b}, @samp{1} if @var{a} is greater than @var{b} and @samp{0} if -they are equal. +If no matching record is found, 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 -Comparison is done from left to right, so that: +@deftypefn {ndbm} int dbm_store (DBM *@var{dbf}, datum @var{key}, @ + datum @var{content}, int @var{mode}) +Writes a key/value pair to the database. The argument @var{dbf} is a +pointer to the @code{DBM} structure returned from a call to +@code{dbm_open}. The @var{key} and @var{content} provide the values +for the record key and content. The @var{mode} argument controls +the behavior of @code{dbm_store} in case a matching record already +exists in the database. It can have one of the following two values: -@example -a = @{ 1, 8, 3 @}; -b = @{ 1, 8, 3 @}; -gdbm_version_cmp (a, b) @result{} 0 +@table @code +@kwindex DBM_REPLACE +@item DBM_REPLACE +Replace existing record with the new one. -a = @{ 1, 8, 3 @}; -b = @{ 1, 8, 2 @}; -gdbm_version_cmp (a, b) @result{} 1 +@kwindex DBM_INSERT +@item DBM_INSERT +The existing record is left unchanged, and the function returns +@samp{1}. +@end table -a = @{ 1, 8, 3 @}; -b = @{ 1, 9. 0 @}; -gdbm_version_cmp (a, b) @result{} -1 -@end example +If no matching record exists in the database, new record will be +inserted no matter what the value of the @var{mode} is. +@end deftypefn + +@deftypefn {ndbm} int dbm_delete (DBM *@var{dbf}, datum @var{key}) +Deletes the record with the matching key from the database. If the +function succeeds, @samp{0} is returned. Otherwise, if no matching +record is found or if an error occurs, @samp{-1} is returned. @end deftypefn -@node Error codes -@chapter Error codes -@cindex error codes +@deftypefn {ndbm} datum dbm_firstkey (DBM *@var{dbf}) +Initializes iteration over the keys from the database and returns +the first key. Note, that the word @samp{first} does not imply any +specific ordering of the keys. -This chapter summarizes error codes which can be set by the -functions in @code{gdbm} library. +If there are no records 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 -@table @asis -@kwindex GDBM_NO_ERROR -@item GDBM_NO_ERROR -No error occurred. +@deftypefn {ndbm} datum dbm_nextkey (DBM *@var{dbf}) +Continues the iteration started by @code{dbm_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. -@kwindex GDBM_MALLOC_ERROR -@item GDBM_MALLOC_ERROR -Memory allocation failed. Not enough memory. +@cindex sequential access, using @samp{NDBM} +@cindex iteration loop, using @samp{NDBM} +The usual way of iterating over all the records in the database is: -@kwindex GDBM_BLOCK_SIZE_ERROR -@item GDBM_BLOCK_SIZE_ERROR -This error is set by the @code{gdbm_open} function (@pxref{Open}), if -the value of its @var{block_size} argument is incorrect. +@example +for (key = dbm_firstkey (dbf); + key.ptr; + key = dbm_nextkey (dbf)) + @{ + /* do something with the key */ + @} +@end example -@kwindex GDBM_FILE_OPEN_ERROR -@item GDBM_FILE_OPEN_ERROR -The library was not able to open a disk file. This can be set by -@code{gdbm_open} (@pxref{Open}), @code{gdbm_export} and -@code{gdbm_import} functions (@pxref{Flat files}). +The loop above should not try to delete any records from the database, +otherwise the iteration is not guaranteed to cover all the keys. +@xref{Sequential}, for a detailed discussion of this. +@end deftypefn -Inspect the value of the system @code{errno} variable to get more -detailed diagnostics. +@deftypefn {ndbm} int dbm_error (DBM *@var{dbf}) +Returns the error condition of the database: @samp{0} if no errors +occurred so far while manipulating the database, and a non-zero value +otherwise. +@end deftypefn -@kwindex GDBM_FILE_WRITE_ERROR -@item GDBM_FILE_WRITE_ERROR -Writing to a disk file failed. This can be set by -@code{gdbm_open} (@pxref{Open}), @code{gdbm_export} and -@code{gdbm_import} functions. - -Inspect the value of the system @code{errno} variable to get more -detailed diagnostics. +@deftypefn {ndbm} void dbm_clearerr (DBM *@var{dbf}) +Clears the error condition of the database. +@end deftypefn -@kwindex GDBM_FILE_SEEK_ERROR -@item GDBM_FILE_SEEK_ERROR -Positioning in a disk file failed. This can be set by -@code{gdbm_open} (@pxref{Open}) function. +@deftypefn {ndbm} int dbm_dirfno (DBM *@var{dbf}) +Returns the file descriptor of the @samp{dir} file of the database. +It is guaranteed to be different from the descriptor returned by +the @code{dbm_pagfno} function (see below). -Inspect the value of the system @code{errno} variable to get a more -detailed diagnostics. +The application can lock this descriptor to serialize accesses to the +database. +@end deftypefn -@kwindex GDBM_FILE_READ_ERROR -@item GDBM_FILE_READ_ERROR -Reading from a disk file failed. This can be set by -@code{gdbm_open} (@pxref{Open}), @code{gdbm_export} and -@code{gdbm_import} functions. +@deftypefn {ndbm} int dbm_pagfno (DBM *@var{dbf}) +Returns the file descriptor of the @samp{pag} file of the database. +See also @code{dbm_dirfno}. +@end deftypefn -Inspect the value of the system @code{errno} variable to get a more -detailed diagnostics. +@deftypefn {ndbm} int dbm_rdonly (DBM *@var{dbf}) +Returns @samp{1} if the database @var{dbf} is open in a read-only mode +and @samp{0} otherwise. +@end deftypefn -@kwindex GDBM_BAD_MAGIC_NUMBER -@item GDBM_BAD_MAGIC_NUMBER -The file given as argument to @code{gdbm_open} function is not a valid -@code{gdbm} file: it has a wrong magic number. +@node dbm +@section DBM interface functions. +@cindex DBM functions -@kwindex GDBM_EMPTY_DATABASE -@item GDBM_EMPTY_DATABASE -The file given as argument to @code{gdbm_open} function is not a valid -@code{gdbm} file: it has zero length. +The functions below are provided for compatibility with the old +UNIX @samp{DBM} interface. Only one database at a time can be +manipulated using them. -@kwindex GDBM_CANT_BE_READER -@item GDBM_CANT_BE_READER -This error code is set by the @code{gdbm_open} function if it is not -able to lock file when called in @samp{GDBM_READER} mode (@pxref{Open, -GDBM_READER}). +@deftypefn {dbm} int dbminit (char *@var{file}) +Opens a database. The @var{file} argument is the full name of the +database file to be opened. The function opens two files: +@file{@var{file}.pag} and @file{@var{file}.dir}. If any of +them does not exist, the function fails. It never attempts to create +the files. -@kwindex GDBM_CANT_BE_WRITER -@item GDBM_CANT_BE_WRITER -This error code is set by the @code{gdbm_open} function if it is not -able to lock file when called in writer mode (@pxref{Open}). +The database is opened in the read-write mode, if its disk permissions +permit. -@kwindex GDBM_READER_CANT_DELETE -@item GDBM_READER_CANT_DELETE -Set by the @code{gdbm_delete} (@pxref{Delete}) if it attempted to -operate on a database that is open in read-only mode (@pxref{Open, -GDBM_READER}). +The application must ensure that the functions described below in +this section are called only after a successful call to @code{dbminit}. +@end deftypefn -@kwindex GDBM_READER_CANT_STORE -@item GDBM_READER_CANT_STORE -Set by the @code{gdbm_store} (@pxref{Store}) if it attempted to -operate on a database that is open in read-only mode (@pxref{Open, -GDBM_READER}). +@deftypefn {dbm} int dbmclose (void) +Closes the database opened by an earlier call to @code{dbminit}. +@end deftypefn -@kwindex GDBM_READER_CANT_REORGANIZE -@item GDBM_READER_CANT_REORGANIZE -Set by the @code{gdbm_reorganize} (@pxref{Reorganization}) if it attempted to -operate on a database that is open in read-only mode (@pxref{Open, -GDBM_READER}). +@deftypefn {dbm} datum fetch (datum @var{key}) +Reads a record from the database with the matching key. The @var{key} +argument supplies the key that is being looked for. -@kwindex GDBM_UNKNOWN_UPDATE -@item GDBM_UNKNOWN_UPDATE -Currently unused. Reserved for future uses. +If no matching record is found, 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 -@kwindex GDBM_ITEM_NOT_FOUND -@item GDBM_ITEM_NOT_FOUND -Requested item was not found. This error is set by @code{gdbm_delete} -(@pxref{Delete}) and @code{gdbm_fetch} (@pxref{Fetch}) when the requested -@var{key} value is not found in the database. +@deftypefn {dbm} int store (datum @var{key}, datum @var{content}) +Stores the key/value pair in the database. If a record with the +matching key already exists, its content will be replaced with the new +one. -@kwindex GDBM_REORGANIZE_FAILED -@item GDBM_REORGANIZE_FAILED -The @code{gdbm_reorganize} function is not -able to create a temporary database. @xref{Reorganization}. +Returns @samp{0} on success and @samp{-1} on error. +@end deftypefn -@kwindex GDBM_CANNOT_REPLACE -@item GDBM_CANNOT_REPLACE -Cannot replace existing item. This error is set by the -@code{gdbm_store} if the requested @var{key} value is found in the -database and the @var{flag} parameter is not @samp{GDBM_REPLACE}. -@xref{Store}, for a detailed discussion. +@deftypefn {dbm} int delete (datum @var{key}) +Deletes a record with the matching key. -@kwindex GDBM_ILLEGAL_DATA -@item GDBM_ILLEGAL_DATA -Either @var{key} or @var{content} parameter was wrong in a call to -to @code{gdbm_store} (@pxref{Store}). +If the function succeeds, @samp{0} is returned. Otherwise, if no +matching record is found or if an error occurs, @samp{-1} is +returned. +@end deftypefn -@kwindex GDBM_OPT_ALREADY_SET -@item GDBM_OPT_ALREADY_SET -Requested option can be set only once and was already set. This error -is returned by the @code{gdbm_setopt} function. @xref{Options, -GDBM_CACHESIZE}. +@deftypefn {dbm} datum firstkey (void) +Initializes iteration over the keys from the database and returns +the first key. Note, that the word @samp{first} does not imply any +specific ordering of the keys. -@kwindex GDBM_OPT_ILLEGAL -@item GDBM_OPT_ILLEGAL -The @var{option} argument is not valid or the @var{value} argument -points to an invalid value in a call to @code{gdbm_setopt} function. -@xref{Options}. +If there are no records 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 -@kwindex GDBM_BYTE_SWAPPED -@item GDBM_BYTE_SWAPPED -The @code{gdbm_open} function (@pxref{Open}) attempts to open a -database which is created on a machine with different byte ordering. +@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 -@kwindex GDBM_BAD_FILE_OFFSET -@item GDBM_BAD_FILE_OFFSET -The @code{gdbm_open} function (@pxref{Open}) sets this error code if -the file it tries to open has a wrong magic number. +@node testgdbm +@chapter Test and modify a GDBM database. +@prindex testgdbm -@kwindex GDBM_BAD_OPEN_FLAGS -@item GDBM_BAD_OPEN_FLAGS -Set by the @code{gdbm_export} function if supplied an invalid -@var{flags} argument. @xref{Flat files}. +The @command{testgdbm} utility allows you to view and modify an +existing @acronym{GDBM} database or to create a new one. -@kwindex GDBM_FILE_STAT_ERROR -@item GDBM_FILE_STAT_ERROR -Getting information about a disk file failed. The system @code{errno} -will give more details about the error. +@cindex default database, @command{testgdbm} +@cindex @option{-g}, @command{testgdbm} option +@cindex @option{-f}, @command{testgdbm} option +@cindex @option{--file}, @command{testgdbm} option +@flindex junk.gdbm +When invoked without options, it tries to open a database file called +@file{junk.gdbm}, located in the current working directory. You can +change this default using the @option{--file} (@option{-f}) command +line option@footnote{For compatibility with earlier versions, the +@option{-g} option acts as an alias to @option{-f}}. This +option takes a single argument, specifying the file name to open, e.g.: -This error can be set by the following functions: @code{gdbm_open}, -@code{gdbm_reorganize}. +@example +$ testgdbm -f file.db +@end example -@kwindex GDBM_FILE_EOF -@item GDBM_FILE_EOF -End of file was encountered where more data was expected to be -present. This error can occur when fetching data from the database -and usually means that the database is truncated or otherwise corrupted. +@cindex read-only mode, @command{testgdbm} +@cindex @option{-r}, @command{testgdbm} option +@cindex @option{--read-only}, @command{testgdbm} 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. -This error can be set by any GDBM function that does I/O. Some of -these functions are: @code{gdbm_delete}, @code{gdbm_exists}, -@code{gdbm_fetch}, @code{gdbm_export}, @code{gdbm_import}, -@code{gdbm_reorganize}, @code{gdbm_firstkey}, @code{gdbm_nextkey}, -@code{gdbm_store}. +@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. +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. -@kwindex GDBM_NO_DBNAME -@item GDBM_NO_DBNAME -Output database name is not specified. This error code is set by -@code{gdbm_load} (@pxref{gdbm_load function,,gdbm_load}) if the first -argument points to @samp{NULL} and the input file does not specify the -database name. +@menu +* invocation:: +* shell:: +@end menu -@kwindex GDBM_ERR_FILE_OWNER -@item GDBM_ERR_FILE_OWNER -This error code is set by @code{gdbm_load} if it is unable to restore -database file owner. It is a mild error condition, meaning that the -data have been restored successfully, only changing the target file -owner failed. Inspect the system @code{errno} variable to get a more -detailed diagnostics. +@node invocation +@section testgdbm invocation +@cindex command line options, @command{testgdbm} -@kwindex GDBM_ERR_FILE_MODE -@item GDBM_ERR_FILE_MODE -This error code is set by @code{gdbm_load} if it is unable to restore -database file mode. It is a mild error condition, meaning that the data -have been restored successfully, only changing the target file owner -failed. Inspect the system @code{errno} variable to get a more -detailed diagnostics. +The following table summarizes all @command{testgdbm} 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 -f @var{file} +@itemx -g @var{file} +@itemx --file=@var{file} +Operate on @var{file} instead of the default @file{junk.gdbm}. +@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 -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 Compatibility -@chapter Compatibility with standard @code{dbm} and @code{ndbm}. +@node shell +@section testgdbm interactive mode +@cindex interactive mode, @command{testgdbm} -@cindex compatibility layer -@code{Gdbm} includes a compatibility layer, which provides traditional -@samp{ndbm} and older @samp{dbm} functions. The layer is compiled and -installed if the @option{--enable-libgdbm-compat} option is used when -configuring the package. +After successful startup, @command{testgdbm} 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 +@dfn{prompt}: -@findex ndbm.h -@findex dbm.h -@findex libgdbm_compat -The compatibility layer consists of two header files: @file{ndbm.h} -and @file{dbm.h} and the @file{libgdbm_compat} library. +@example +testgdbm> _ +@end example -Older programs using @code{ndbm} or @code{dbm} interfaces can -use @file{libgdbm_compat} without any changes. To link a program with -the compatibility library, add the following two options to the -@command{cc} invocation: @option{-lgdbm -lgdbm_compat}. The @option{-L} -option may also be required, depending on where @code{gdbm} is -installed, e.g.: +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}, +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 +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 -cc ... -L/usr/local/lib -lgdbm -lgdbm_compat +testgdbm> @kbd{store} +key> @kbd{three} +data> @kbd{3} @end example -@cindex @samp{dir} file -@cindex @samp{pag} file -Databases created and manipulated by the compatibility interfaces -consist of two different files: @file{@var{file}.dir} and -@file{@var{file}.pag}. This is required by the @acronym{POSIX} -specification and corresponds to the traditional usage. Note, -however, that despite the similarity of the naming convention, -actual data stored in these files has not the same format as -in the databases created by other @code{dbm} or @code{ndbm} -libraries. In other words, you cannot access a standard UNIX -@code{dbm} file with GNU @code{dbm}! +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 +error and exit immediately. -GNU @code{dbm} files are not @code{sparse}. You can copy them with -the usual @code{cp} command and they will not expand in the copying -process. +@anchor{pager} +@cindex pager, @command{testgdbm} +@cindex @env{PAGER} +Some commands produce excessive amounts of output. To help you follow +it, @command{testgdbm} 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. -@menu -* ndbm:: NDBM interface functions. -* dbm:: DBM interface functions. -@end menu +@anchor{nul-termination} +Many of the @command{testgdbm} 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. -@node ndbm -@section NDBM interface functions. -@cindex NDBM functions +The following table summarizes all available commands: -The functions below implement the @acronym{POSIX} @samp{ndbm} interface: +@deffn {command verb} count +@deffnx {command abbrev} co +@deffnx {command letter} c +Print the number of entries in the database. +@end deffn -@deftypefn {ndbm} {DBM *} dbm_open (char *@var{file}, int @var{flags}, int @var{mode}) -Opens a database. The @var{file} argument is the full name of the -database file to be opened. The function opens two files: -@file{@var{file}.pag} and @file{@var{file}.dir}. The @var{flags} and -@var{mode} arguments have the same meaning as the second and third -arguments of -@ifhtml -@uref{http://www.manpagez.com/man/2/open,,open(2)}, -@end ifhtml -@ifnothtml -@code{open} (@pxref{open,,open a file,open(2), open(2) man page}), -@end ifnothtml -except that a database opened for write-only access opens the files -for read and write access and the behavior of the @code{O_APPEND} flag is -unspecified. +@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} +@end deffn + +@anchor{testgdbm export} +@deffn {command verb} export @var{file-name} [truncate] +@deffnx {command abbrev} e @var{file-name} [truncate] +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 word +@samp{truncate} is given as its second argument. + +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}. +@end deffn + +@anchor{testgdbm import} +@deffn {command verb} import @var{file-name} [replace] +@deffnx {command abbrev} i @var{file-name} [replace] +Import data from a flat dump file @var{file-name} +(@pxref{Flat files}). If the word @samp{replace} is given +as the second argument, any records with the same keys as the already +existing ones will replace them. +@end deffn + +@deffn {command verb} list +@deffnx {command abbrev} 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. + +See also @code{first}, below. + +@xref{Sequential}, for more information on sequential access. +@end deffn + +@deffn {command verb} quit +@deffnx {command abbrev} 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). +@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. +@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 -The function returns a pointer to the @code{DBM} structure describing -the database. This pointer is used to refer to this database in all -operations described below. +@deffn {command verb} dir +@deffnx {command abbrev} di +@deffnx {command letter} D +Print hash directory. +@end deffn -Any error detected will cause a return value of @samp{NULL} and an -appropriate value will be stored in @code{gdbm_errno} -(@pxref{Variables}). -@end deftypefn +@deffn {command verb} header +@deffnx {command abbrev} hea +@deffnx {command letter} F +Print file header. +@end deffn -@deftypefn {ndbm} void dbm_close (DBM *@var{dbf}) -Closes the database. The @var{dbf} argument must be a pointer -returned by an earlier call to @code{dbm_open}. -@end deftypefn +@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 -@deftypefn {ndbm} datum dbm_fetch (DBM *@var{dbf}, datum @var{key}) -Reads a record from the database with the matching key. The @var{key} -argument supplies the key that is being looked for. +@deffn {command verb} cache +@deffnx {command abbrev} ca +@deffnx {command letter} K +Print the bucket cache. +@end deffn -If no matching record is found, 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 +@deffn {command verb} status +@deffnx {command abbrev} sta +@deffnx {command letter} S +Print current program status. The following example shows the +information displayed: -@deftypefn {ndbm} int dbm_store (DBM *@var{dbf}, datum @var{key}, @ - datum @var{content}, int @var{mode}) -Writes a key/value pair to the database. The argument @var{dbf} is a -pointer to the @code{DBM} structure returned from a call to -@code{dbm_open}. The @var{key} and @var{content} provide the values -for the record key and content. The @var{mode} argument controls -the behavior of @code{dbm_store} in case a matching record already -exists in the database. It can have one of the following two values: +@example +Database file: junk.gdbm +Zero terminated keys: yes +Zero terminated data: yes +@end example +@end deffn -@table @code -@kwindex DBM_REPLACE -@item DBM_REPLACE -Replace existing record with the new one. +@deffn {command verb} version +@deffnx {command abbrev} v +Print the version of @command{gdbm}. +@end deffn -@kwindex DBM_INSERT -@item DBM_INSERT -The existing record is left unchanged, and the function returns -@samp{1}. -@end table +@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. -If no matching record exists in the database, new record will be -inserted no matter what the value of the @var{mode} is. -@end deftypefn - -@deftypefn {ndbm} int dbm_delete (DBM *@var{dbf}, datum @var{key}) -Deletes the record with the matching key from the database. If the -function succeeds, @samp{0} is returned. Otherwise, if no matching -record is found or if an error occurs, @samp{-1} is returned. -@end deftypefn +@xref{nul-termination}. +@end deffn -@deftypefn {ndbm} datum dbm_firstkey (DBM *@var{dbf}) -Initializes iteration over the keys from the database and returns -the first key. Note, that the word @samp{first} does not imply any -specific ordering of the keys. +@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 -If there are no records 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 gdbm_dump +@chapter The @command{gdbm_dump} utility +@prindex gdbm_dump -@deftypefn {ndbm} datum dbm_nextkey (DBM *@var{dbf}) -Continues the iteration started by @code{dbm_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. +The @command{gdbm_dump} utility creates a flat file dump of a GDBM +database (@pxref{Flat files}). It takes one mandatory argument: the +name of the source database file. The second argument, if given, +specifies the name of the output file. If not given, +@command{gdbm_dump} will produce the dump on the standard output. -@cindex sequential access, using @samp{NDBM} -@cindex iteration loop, using @samp{NDBM} -The usual way of iterating over all the records in the database is: +For example, the following invocation creates a dump of the database +@file{file.db} in the file @file{file.dump}: @example -for (key = dbm_firstkey (dbf); - key.ptr; - key = dbm_nextkey (dbf)) - @{ - /* do something with the key */ - @} +$ gdbm_dump file.db file.dump @end example -The loop above should not try to delete any records from the database, -otherwise the iteration is not guaranteed to cover all the keys. -@xref{Sequential}, for a detailed discussion of this. -@end deftypefn +By default the utility creates dumps in ASCII format (@pxref{Flat +files,ASCII}). Another format can be requested using the +@option{--format} (@option{-H}) option. -@deftypefn {ndbm} int dbm_error (DBM *@var{dbf}) -Returns the error condition of the database: @samp{0} if no errors -occurred so far while manipulating the database, and a non-zero value -otherwise. -@end deftypefn +The @command{gdbm_load} utility understands the following command line +options: -@deftypefn {ndbm} void dbm_clearerr (DBM *@var{dbf}) -Clears the error condition of the database. -@end deftypefn +@table @option +@item -H @var{fmt} +@itemx --format=@var{fmt} +Select output format. Valid values for @var{fmt} are: @samp{binary} +or @samp{0} to select binary dump format, and @samp{ascii} or @samp{1} +to select ASCII format. -@deftypefn {ndbm} int dbm_dirfno (DBM *@var{dbf}) -Returns the file descriptor of the @samp{dir} file of the database. -It is guaranteed to be different from the descriptor returned by -the @code{dbm_pagfno} function (see below). +@item -h +@itemx --help +Print a concise help summary. -The application can lock this descriptor to serialize accesses to the -database. -@end deftypefn +@item -V +@itemx --version +Print program version and licensing information and exit. -@deftypefn {ndbm} int dbm_pagfno (DBM *@var{dbf}) -Returns the file descriptor of the @samp{pag} file of the database. -See also @code{dbm_dirfno}. -@end deftypefn +@item --usage +Print a terse invocation syntax summary along with a list of available +command line options. +@end table -@deftypefn {ndbm} int dbm_rdonly (DBM *@var{dbf}) -Returns @samp{1} if the database @var{dbf} is open in a read-only mode -and @samp{0} otherwise. -@end deftypefn +@node gdbm_load +@chapter The @command{gdbm_load} utility +@prindex gdbm_load -@node dbm -@section DBM interface functions. -@cindex DBM functions +The @command{gdbm_load} utility restores a GDBM database from a flat +file. The utility requires at least one argument: the name of the +input flat file. If it is @samp{-}, the standard input will be read. +The format of the input file is detected automatically. -The functions below are provided for compatibility with the old -UNIX @samp{DBM} interface. Only one database at a time can be -manipulated using them. +By default the utility attempts to restore the database under its +original name, as stored in the input file. It will fail to do so if +the inpu