diff options
author | Sergey Poznyakoff <gray@gnu.org.ua> | 2011-11-15 15:23:56 +0000 |
---|---|---|
committer | Sergey Poznyakoff <gray@gnu.org.ua> | 2011-11-15 15:23:56 +0000 |
commit | 5e3403fbd39b2cafdaa662768a61d8fb0f45e244 (patch) | |
tree | 2d9f7bbe099046ad5c369eb225bbde3ab94e0bdf /doc | |
parent | af116bb7d7d5a53310e48d196ebe577b9a63f799 (diff) | |
download | gdbm-5e3403fbd39b2cafdaa662768a61d8fb0f45e244.tar.gz gdbm-5e3403fbd39b2cafdaa662768a61d8fb0f45e244.tar.bz2 |
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.
Diffstat (limited to 'doc')
-rw-r--r-- | doc/gdbm.texinfo | 869 |
1 files changed, 488 insertions, 381 deletions
diff --git a/doc/gdbm.texinfo b/doc/gdbm.texinfo index 1e51322..ec6701f 100644 --- a/doc/gdbm.texinfo +++ b/doc/gdbm.texinfo @@ -114,2 +114,6 @@ Functions: +* Error codes:: Error codes returned by @code{gdbm} calls. +* Variables:: Two useful variables. +* Compatibility:: Compatibility with UNIX dbm and ndbm. + Programs @@ -120,2 +124,3 @@ Programs * gdbmexport:: Export a database into a portable format. +* Exit codes:: Exit codes returned by GDBM utilities. @@ -123,5 +128,2 @@ 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. @@ -716,3 +718,5 @@ for a detailed discussion. @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 @@ -729,2 +733,14 @@ 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 @@ -801,3 +817,4 @@ Format of the dump file. See the @var{format} argument to the @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 @@ -1056,378 +1073,2 @@ calls. -@node testgdbm -@chapter Test and modify a GDBM database. -@prindex testgdbm - -The @command{testgdbm} utility allows you to view and modify an -existing @acronym{GDBM} database or to create a new one. - -@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.: - -@example -$ testgdbm -f file.db -@end example - -@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. - -@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. - -@menu -* invocation:: -* shell:: -@end menu - -@node invocation -@section testgdbm invocation -@cindex command line options, @command{testgdbm} - -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 shell -@section testgdbm interactive mode -@cindex interactive mode, @command{testgdbm} - -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}: - -@example -testgdbm> _ -@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}, -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 -testgdbm> @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 -error and exit immediately. - -@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. - -@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. - -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} -@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 - -@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 -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 -FIXME - -@node gdbm_load -@chapter The @command{gdbm_load} utility -@prindex gdbm_load -FIXME - -@node gdbmexport -@chapter Export a database into a portable format. -@prindex gdbmexport - -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. - -The utility takes two mandatory arguments: the name of the database -file to convert and the output file name, e.g.: - -@example -$ gdbmexport junk.gdbm junk.flat -@end example - -In addition two options are understood: - -@table @option -@item -h -Display short usage summary and exit. - -@item -v -Display program version and licensing information, and exit. -@end table - @node Variables @@ -1978,2 +1619,468 @@ never free it. +@node testgdbm +@chapter Test and modify a GDBM database. +@prindex testgdbm + +The @command{testgdbm} utility allows you to view and modify an +existing @acronym{GDBM} database or to create a new one. + +@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.: + +@example +$ testgdbm -f file.db +@end example + +@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. + +@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. + +@menu +* invocation:: +* shell:: +@end menu + +@node invocation +@section testgdbm invocation +@cindex command line options, @command{testgdbm} + +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 shell +@section testgdbm interactive mode +@cindex interactive mode, @command{testgdbm} + +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}: + +@example +testgdbm> _ +@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}, +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 +testgdbm> @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 +error and exit immediately. + +@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. + +@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. + +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} +@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 + +@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 +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 +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. + +For example, the following invocation creates a dump of the database +@file{file.db} in the file @file{file.dump}: + +@example +$ gdbm_dump file.db file.dump +@end example + +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. + +The @command{gdbm_load} utility understands the following command line +options: + +@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. + +@item -h +@itemx --help +Print a concise help summary. + +@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 gdbm_load +@chapter The @command{gdbm_load} utility +@prindex gdbm_load + +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. + +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 input is in binary format. In that case, the name of the database +to create can be given as the second argument. + +In general, if two arguments are given, the second one is treated as +the name of the database to create, overriding the file name specified +in the flat file. + +The utility understands the following command line arguments: + +@table @option +@item -m @var{mode} +@item --mode=@var{mode} +Set file mode. The argument is the desired file mode in octal. + +@item -n +@itemx --no-meta +Do not restore file meta-data (ownership and mode) from the flat file. + +@item -r +@itemx --replace +Replace existing keys. + +@item -u @var{user}[:@var{group}] +@itemx --user=@var{user}[:@var{group}] +Set file owner. The @var{user} can be either a valid user name or +UID. Similarly, the @var{group} is either a valid group name or GID. +If @var{group} is not given, the main group of @var{user} is used. + +User and group parts can be separated by a dot, instead of the colon. + +@item -h +@itemx --help +Print a concise help summary. + +@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 gdbmexport +@chapter Export a database into a portable format. +@prindex gdbmexport + +The @command{gdbmexport} utility converts the database of an older +GDBM version into a binary flat format. + +The utility takes two mandatory arguments: the name of the database +file to convert and the output file name, e.g.: + +@example +$ gdbmexport junk.gdbm junk.flat +@end example + +In addition the following two options are understood: + +@table @option +@item -h +Display short usage summary and exit. + +@item -v +Display program version and licensing information, and exit. +@end table + +@node Exit codes +@chapter Exit codes +@cindex exit code + +All GDBM utilities return uniform exit codes. These are summarized in +the table below: + +@multitable @columnfractions 0.3 0.7 +@headitem Code @tab Meaning +@item 0 @tab Successful termination. +@item 1 @tab A fatal error occurred. +@item 2 @tab Program was unable to restore file ownership or mode. +@item 3 @tab Command line usage error. +@end multitable + @node Bugs |