summaryrefslogtreecommitdiffabout
path: root/doc
authorSergey Poznyakoff <gray@gnu.org.ua>2011-11-15 15:23:56 (GMT)
committer Sergey Poznyakoff <gray@gnu.org.ua>2011-11-15 15:23:56 (GMT)
commit5e3403fbd39b2cafdaa662768a61d8fb0f45e244 (patch) (side-by-side diff)
tree2d9f7bbe099046ad5c369eb225bbde3ab94e0bdf /doc
parentaf116bb7d7d5a53310e48d196ebe577b9a63f799 (diff)
downloadgdbm-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') (more/less context) (ignore whitespace changes)
-rw-r--r--doc/gdbm.texinfo869
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
@@ -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,382 +1071,6 @@ 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
-
-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
@chapter Useful global variables.
@@ -1976,6 +1617,472 @@ memory managed by the compatibility library. The application should
never free it.
@end deftypefn
+@node testgdbm
+@chapter Test and modify a GDBM database.
+@prindex testgdbm
+
+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
@chapter Problems and bugs.

Return to:

Send suggestions and report system problems to the System administrator.