Document flat format and related functions.

1 files changed, 122 insertions, 18 deletions

diff --git a/doc/gdbm.texinfo b/doc/gdbm.texinfo
index 27730f4..6211f67 100644
--- a/doc/gdbm.texinfo
+++ b/doc/gdbm.texinfo
@@ -24,2 +24,9 @@
 
+@c Merge all indices into a single one
+@syncodeindex fn cp
+@syncodeindex vr cp
+@syncodeindex ky cp
+@syncodeindex pg cp
+@syncodeindex tp cp
+
 @iftex
@@ -124,2 +131,3 @@ Functions:
 * Sync::                       Insure all writes to disk have competed.
+* Flat files::                 Export and import to Flat file format.
 * Errors::                     Convert internal error codes into English.
@@ -302,8 +310,8 @@ and
 @ifhtml
-@uref{http://www.manpagez.com/man/2/open},
+@uref{http://www.manpagez.com/man/2/open}),
 @end ifhtml
 @ifnothtml
-@pxref{open,,open a file,open(2), open(2) man page}
+@pxref{open,,open a file,open(2), open(2) man page}),
 @end ifnothtml
-), which is used if the file is created).
+which is used if the file is created).
 @item fatal_func
@@ -606,2 +614,79 @@ immediately after the set of changes have been made.
 
+@node Flat files
+@chapter Export and Import
+@cindex Flat file format
+@cindex export
+@cindex import
+@code{Gdbm} databases can be converted into a protable @dfn{flat
+format}.  This format can be used, for example, to migrate between
+the different versions of @code{gdbm} databases.  Generally speaking,
+flat files are safe to send over the network, and can be used to
+recreate the database on another machine.  The recreated database is
+guaranteed to be a byte-to-byte equivalent of the database from which
+the flat file was created.  This does not necessarily mean, however,
+that this file can be used in the same way as the original one.  For
+example, if the original database contained non-@acronym{ASCII} data
+(e.g.  @acronym{C} structures, integers etc.), the recreated database
+can be of any use only if the target machine has the same integer
+size and byte ordering as the source one and if its @acronym{C}
+compiler uses the same packing conventions as the one which generated
+@acronym{C} which populated the original database.  In general, such
+binary databases are not portable between machines, unless you follow
+some stringent rules on what data is written to them and how it is
+interpreted.
+
+@deftypefn {gdbm interface} int gdbm_export (GDBM_FILE @var{dbf}, @
+           const char *@var{exportfile}, int @var{flag}, int @var{mode})
+Create a flat file from the @code{gdbm} database.  The parameters are:
+
+@table @var
+@item dbf
+A pointer to the source database, returned by a call to
+@code{gdbm_open}.  The database must be open in @samp{GDBM_WRITER} mode.
+
+@item exportfile
+The name of the output file.
+
+@item flag
+@kwindex GDBM_WRCREAT
+@kwindex GDBM_NEWDB
+How to create the output file.  If @var{flag} is @samp{GDBM_WRCREAT},
+the file will be created if it does not exist already.  Otherwise, if
+it is @samp{GDBM_NEWDB}, it will be created if it does not exist, and
+truncated otherwise.
+
+@item mode
+The permissions to use when creating the output file.
+See @ifhtml
+@uref{http://www.manpagez.com/man/2/open},
+@end ifhtml
+@ifnothtml
+@ref{open,,open a file,open(2), open(2) man page},
+@end ifnothtml
+for a detailed discussion.
+@end table
+@end deftypefn
+
+@deftypefn {gdbm interface} int gdbm_import (GDBM_FILE @var{dbf}, @
+           const char *@var{importfile}, int @var{flag})
+Populates the database from an existing flat file.
+
+@table @var
+@item dbf
+A pointer to the source database, returned by a call to
+@code{gdbm_open}.  The database must be open in @samp{GDBM_WRITER} mode.
+
+@item importfile
+The name of the input flat file.  The file must exist.
+
+@item flag
+The @var{flag} argument to be passed to @code{gdbm_store} function
+when adding new records.  @xref{Store}, for a description of its
+effect.
+@end table
+@end deftypefn
+
+See also @ref{gdbmexport}, @ref{testgdbm export}, and
+@ref{testgdbm import}.
+
 @node Errors
@@ -830,3 +915,3 @@ error and exits immediately.
 @cindex pager, @command{testgdbm}
-@cindex @env{PAGER}.
+@cindex @env{PAGER}
 Some commands produce excessive amounts of output.  To help you follow
@@ -852,7 +937,10 @@ Print the number of entries in the database.
 Delete entry with a given @var{key}
+@anchor{testgdbm export}
 @item e @var{file-name} [truncate]
-Export the database (similar to @command{gdbmexport},
-@pxref{gdbmexport}) to file @var{file-name}.  This command will not
-overwrite an existing file, unless the word @samp{truncate} is given
-as its second argument.
+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}.
 
@@ -861,6 +949,6 @@ Fetch and display a record with the given @var{key}.
 
-@anchor{import}
+@anchor{testgdbm import}
 @item i @var{file-name} [replace]
 Import data from a flat dump file @var{file-name}
-(@pxref{gdbmexport}).  If the word @samp{replace} is given
+(@pxref{Flat files}).  If the word @samp{replace} is given
 as the second argument, any records with the same keys as the already
@@ -963,4 +1051,5 @@ The @command{gdbmexport} utility converts the database into a portable
 @dfn{flat format}.  Files in this format can be used to populate
-databases using the @code{i} command of @command{testgdbm} utility
-(@pxref{import}).  In many cases files in this format are suitable for
+databases using the @code{gdbm_import} function (@pxref{Flat files,
+gdbm_import}) 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.
@@ -994,3 +1083,3 @@ Display program version and licensing information, and exit.
 @node Variables
-@chapter Two useful variables.
+@chapter Useful global variables.
 
@@ -1011,2 +1100,19 @@ A string containing the version information.
 
+@deftypevar const char * const 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
+
+@defvr {Constant} _GDBM_MIN_ERRNO
+The minimum error code used by @code{gdbm}.
+@end defvr
+
+@defvr {Constant} _GDBM_MAX_ERRNO
+The maximum error code used by @code{gdbm}.
+@end defvr
+
 @node Error codes
@@ -1033,6 +1139,5 @@ the value of its @var{block_size} argument is incorrect.
 @item GDBM_FILE_OPEN_ERROR
-@c FIXME: Neither gdbm_export nor gdbm_import are described in this doc!
 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.
+@code{gdbm_import} functions (@pxref{Flat files}).
 
@@ -1145,5 +1250,4 @@ the file it tries to open has a wrong magic number.
 @item GDBM_BAD_OPEN_FLAGS
-@c FIXME: xref?
 Set by the @code{gdbm_export} function if supplied an invalid
-@var{flags} argument.
+@var{flags} argument.  @xref{Flat files}.
 @end table
@@ -1249,3 +1353,3 @@ You may contact the authors and maintainers by e-mail:
 @example
-@file{phil@@cs.wwu.edu}, @file{downsj@@downsj.com}, @file{gray@@gnu.org.ua}
+@email{phil@@cs.wwu.edu}, @email{downsj@@downsj.com}, @email{gray@@gnu.org.ua}
 @end example