aboutsummaryrefslogtreecommitdiff
path: root/doc/gdbm.texinfo
diff options
context:
space:
mode:
authorSergey Poznyakoff <gray@gnu.org.ua>2011-11-14 19:33:18 +0000
committerSergey Poznyakoff <gray@gnu.org.ua>2011-11-14 19:33:18 +0000
commit91751b0ce995e2b3b73fd60d4dbeade3cc4de123 (patch)
treecb9fb0fd73dac5b8cbb01aba21e5da2c21dc83d9 /doc/gdbm.texinfo
parentf1ee8328d4f4e347b6df4f839ff6f182603e2ffd (diff)
downloadgdbm-91751b0ce995e2b3b73fd60d4dbeade3cc4de123.tar.gz
gdbm-91751b0ce995e2b3b73fd60d4dbeade3cc4de123.tar.bz2
Minor changes
Diffstat (limited to 'doc/gdbm.texinfo')
-rw-r--r--doc/gdbm.texinfo167
1 files changed, 135 insertions, 32 deletions
diff --git a/doc/gdbm.texinfo b/doc/gdbm.texinfo
index ff93a1a..fcbc14e 100644
--- a/doc/gdbm.texinfo
+++ b/doc/gdbm.texinfo
@@ -662,3 +662,3 @@ 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
+(e.g.@: @acronym{C} structures, integers etc.), the recreated database
can be of any use only if the target machine has the same integer
@@ -671,5 +671,16 @@ 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:
+GDBM version @value{VERSION} supports two flat file formats. The
+@dfn{binary} flat file, as its name implies, keeps data in binary
+form. The @dfn{ascii} flat file, on the other hand, encodes all data
+in base64 and can be sent over transmission channels that normally
+allow only ASCII data, such as, e.g.@: SMTP. Apart from that, ASCII
+flat files contain original database file metadata (file name, mode
+and ownership), and can therefore be used to restore an exact copy of
+the database.
+
+@deftypefn {gdbm interface} int gdbm_dump (GDBM_FILE @var{dbf}, @
+ const char *@var{filename}, int @var{format}, @
+ int @var{open_flags}, int @var{mode})
+Dumps the database file to the named file in requested format.
+Arguments are:
@@ -677,15 +688,20 @@ Create a flat file from the @code{gdbm} database. The parameters are:
@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.
+A pointer to the source database, returned by a prior call to
+@code{gdbm_open}.
-@item exportfile
-The name of the output file.
+@item filename
+Name of the dump 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 format
+Dump format. Allowed values are: @samp{GDBM_DUMP_FMT_BINARY} to
+create a binary dump and @samp{GDBM_DUMP_FMT_ASCII} to create an ASCII
+dump file.
+
+@item open_flags
+How to create the output file. If @var{flag} is @samp{GDBM_WRCREAT}
+the file will be created if it does not exist. If it does exist,
+the @code{gdbm_dump} will fail.
+
+If @var{flag} is @samp{GDBM_NEWDB}, the function will create a new
+output file, replacing it if it already exists.
@@ -703,5 +719,53 @@ for a detailed discussion.
-@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.
+@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})
+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
+function will return a pointer to the newly created database in the
+memory location pointed to by @var{pdbf}. If the dump file carries no
+information about the original database file name, the function will
+set @code{gdbm_errno} to @samp{GDBM_NO_DBNAME} and return
+@samp{-1}, indicating failure.
+
+The @var{flag} has the same meaning as the @var{flag} argument
+to the @code{gdbm_store} function (@pxref{Store}).
+
+The function returns 0 upon successful completion or -1 on error. In
+the latter case, @code{gdbm_errno} will be set to one of the
+following values:
+
+@table @asis
+@item GDBM_FILE_OPEN_ERROR
+Input file (@var{filename}) cannot be opened. The @code{errno}
+variable can be used to get more detail about the failure.
+
+@item GDBM_MALLOC_ERROR
+Not enough memory to load data.
+
+@item GDBM_FILE_READ_ERROR
+Reading from @var{filename} failed. The @code{errno} variable can be
+used to get more detail about the failure.
+
+@item GDBM_ILLEGAL_DATA
+Input contained some illegal data.
+
+@item GDBM_ITEM_NOT_FOUND
+This error can occur only when the input file is in ASCII format. It
+indicates that the data part of the record about to be read lacked
+length specification. Application developers are advised to treat
+this error equally as @samp{GDBM_ILLEGAL_DATA}.
+@end table
+
+If any error, excepting @var{GDBM_FILE_OPEN_ERROR}, occurs and the
+input file is in ASCII format, the number of line in which the error
+occurred will be stored in the location pointed to by the
+@var{errline} parameter, unless it is @samp{NULL}.
+@end deftypefn
+
+@deftypefn {gdbm interface} int gdbm_dump_to_file (GDBM_FILE @var{dbf}, @
+ FILE *@var{fp}, int @var{format})
+This is an alternative entry point to @code{gdbm_dump} (which see).
+Arguments are:
@@ -710,16 +774,48 @@ Populates the database from an existing flat file.
A pointer to the source database, returned by a call to
-@code{gdbm_open}. The database must be open in @samp{GDBM_WRITER} mode.
+@code{gdbm_open}.
-@item importfile
-The name of the input flat file. The file must exist.
+@item fp
+File to write the data to.
-@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.
+@item format
+Format of the dump file. See the @var{format} argument to the
+@code{gdbm_dump} function.
@end table
@end deftypefn
+
+@deftypefn {gdbm interface} int gdbm_load_from_file (GDBM_FILE *@var{pdbf}, @
+ FILE *@var{fp}, int @var{replace}, 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
+@var{flag}, which is not needed in this case).
+@end deftypefn
+
+@deftypefn {gdbm interface} int gdbm_export (GDBM_FILE @var{dbf}, @
+ const char *@var{exportfile}, int @var{flag}, int @var{mode})
+This function is retained for compatibility with GDBM 1.10 and
+earlier. It dumps the database to a file in binary dump format and
+is entirely equivalent to
+
+@example
+gdbm_dump(@var{dbf}, @var{exportfile}, GDBM_DUMP_FMT_BINARY,
+ @var{flag}, @var{mode})
+@end example
+@end deftypefn
+
+@deftypefn {gdbm interface} int gdbm_import (GDBM_FILE @var{dbf}, @
+ const char *@var{importfile}, int @var{flag})
+This function is retained for compatibility with GDBM 1.10 and
+earlier. It loads the file @var{importfile}, which must be a binary
+flat file, into the database @var{dbf} and is equivalent to the
+following construct:
-See also @ref{gdbmexport}, @ref{testgdbm export}, and
-@ref{testgdbm import}.
+@example
+@var{dbf} = gdbm_open (@var{importfile}, 0,
+ @var{flag} == GDBM_REPLACE ? GDBM_WRCREAT :
+ GDBM_NEWDB, 0600, NULL);
+gdbm_load (&@var{dbf}, @var{exportfile}, GDBM_DUMP_FMT_BINARY,
+ @var{flag}, NULL)
+@end example
+@end deftypefn
@@ -798,3 +894,3 @@ been altered by another calls to @code{gdbm_setopt}.
@item GDBM_FASTMODE
-Enable or disable the @dfn{fast writes mode}, i.e. writes without
+Enable or disable the @dfn{fast writes mode}, i.e.@: writes without
subsequent synchronization. The @var{value} should point
@@ -817,3 +913,3 @@ turn it off.
Note, that this option is a reverse of @code{GDBM_FASTMODE},
-i.e. calling @code{GDBM_SETSYNCMODE} with @samp{TRUE} has the same effect
+i.e.@: calling @code{GDBM_SETSYNCMODE} with @samp{TRUE} has the same effect
as calling @code{GDBM_FASTMODE} with @samp{FALSE}.
@@ -1076,3 +1172,3 @@ data> @kbd{3}
However, such prompting is possible only in interactive mode. In
-non-interactive mode (e.g. when running a script), all arguments must
+non-interactive mode (e.g.@: when running a script), all arguments must
be supplied with each command, otherwise @command{testgdbm} will report an
@@ -1284,3 +1380,3 @@ 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
+non-@acronym{ASCII} data (e.g.@: @acronym{C} structures, integers
etc.). For such databases you will be better off by writing a
@@ -1405,3 +1501,3 @@ gdbm_version_cmp (a, b) @result{} -1
-This chapter summarizes the error codes which can be set by the
+This chapter summarizes error codes which can be set by the
functions in @code{gdbm} library.
@@ -1569,2 +1665,9 @@ these functions are: @code{gdbm_delete}, @code{gdbm_exists},
@code{gdbm_store}.
+
+@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.
@end table

Return to:

Send suggestions and report system problems to the System administrator.