aboutsummaryrefslogtreecommitdiff
path: root/doc/gdbm.texi
diff options
context:
space:
mode:
Diffstat (limited to 'doc/gdbm.texi')
-rw-r--r--doc/gdbm.texi2567
1 files changed, 2567 insertions, 0 deletions
diff --git a/doc/gdbm.texi b/doc/gdbm.texi
new file mode 100644
index 0000000..6322a9b
--- /dev/null
+++ b/doc/gdbm.texi
@@ -0,0 +1,2567 @@
+\input texinfo @c -*- Texinfo -*-
+@comment $Id$
+@comment %**start of header (This is for running Texinfo on a region.)
+@setfilename gdbm.info
+@include version.texi
+@settitle GDBM manual
+
+@ifinfo
+@dircategory Programming & development tools
+@direntry
+* GDBM: (gdbm). The GNU database manager.
+* gdbm_dump: (gdbm) gdbm_dump. Dump the GDBM database into a flat file.
+* gdbm_load: (gdbm) gdbm_load. Load the database from a flat file.
+@end direntry
+@end ifinfo
+
+@c @setchapternewpage odd
+@comment %**end of header (This is for running Texinfo on a region.)
+
+@c Use @kwindex for keywords
+@defcodeindex kw
+@syncodeindex kw cp
+@c Use @flindex for files
+@defcodeindex fl
+@syncodeindex fl cp
+@c Use @prindex for programs
+@defcodeindex pr
+@syncodeindex pr cp
+
+@c Merge all indices into a single one
+@syncodeindex fn cp
+@syncodeindex vr cp
+@syncodeindex ky cp
+@syncodeindex pg cp
+@syncodeindex tp cp
+
+@iftex
+@finalout
+@end iftex
+
+@copying
+Published by the Free Software Foundation,
+51 Franklin Street, Fifth Floor
+Boston, MA 02110-1301, USA
+
+Copyright @copyright{} 1989-1999, 2007-2011 Free Software Foundation, Inc.
+
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.3 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, no Front-Cover, and no Back-Cover texts.
+A copy of the license is included in the section entitled ``GNU Free
+Documentation License.''
+@end copying
+
+@titlepage
+@sp 6
+@center @titlefont{GNU dbm}
+@sp 2
+@center A Database Manager
+@sp 2
+@center by Philip A. Nelson, Jason Downs and Sergey Poznyakoff
+@sp 4
+@center Manual by Pierre Gaumond, Philip A. Nelson, Jason Downs
+@center and Sergey Poznyakoff
+@sp 1
+@center Edition @value{EDITION}
+@sp 1
+@center for GNU @code{dbm}, Version @value{VERSION}
+@page
+@vskip 0pt plus 1filll
+@insertcopying
+@end titlepage
+
+@ifnothtml
+@page
+@summarycontents
+@page
+@end ifnothtml
+@contents
+
+@ifnottex
+@node Top
+@top The GNU database manager.
+
+GNU @code{dbm} is a library of functions implementing a hashed database
+on a disk file. This manual documents GNU @code{dbm} Version @value{VERSION}
+(@code{gdbm}). The software was originally written by Philip A.@:
+Nelson. This document was originally written by Pierre Gaumond from
+texts written by Phil.
+@end ifnottex
+
+@menu
+Introduction:
+
+* Copying:: Your rights.
+* Intro:: Introduction to GNU dbm.
+* List:: List of functions.
+
+Functions:
+
+* Open:: Opening the database.
+* Close:: Closing the database.
+* Count:: Counting records in the database.
+* Store:: Inserting and replacing records in the database.
+* Fetch:: Searching records in the database.
+* Delete:: Removing records from the database.
+* Sequential:: Sequential access to records.
+* Reorganization:: Database reorganization.
+* Sync:: Insure all writes to disk have competed.
+* Flat files:: Export and import to Flat file format.
+* Errors:: Convert internal error codes into English.
+* Options:: Setting internal options.
+* Locking:: File locking.
+* Variables:: Useful global variables.
+
+* Error codes:: Error codes returned by @code{gdbm} calls.
+* Compatibility:: Compatibility with UNIX dbm and ndbm.
+
+Programs
+
+* gdbmtool:: Examine 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:
+
+* Bugs:: Problems and bugs.
+* Resources:: Additional resources,
+
+* GNU Free Documentation License:: Document license.
+* Index:: Index
+@end menu
+
+@node Copying
+@chapter Copying Conditions.
+This library is @dfn{free}; this means that everyone is free to use
+it and free to redistribute it on a free basis. GNU @code{dbm} (@code{gdbm})
+is not in the public domain; it is copyrighted and there
+are restrictions on its distribution, but these restrictions are
+designed to permit everything that a good cooperating citizen would want
+to do. What is not allowed is to try to prevent others from further
+sharing any version of @code{gdbm} that they might get from
+you.@refill
+
+ Specifically, we want to make sure that you have the right to give
+away copies @code{gdbm}, that you receive
+source code or else can get it if you want it, that you can change these
+functions or use pieces of them in new free programs, and that you know
+you can do these things.@refill
+
+ To make sure that everyone has such rights, we have to forbid you to
+deprive anyone else of these rights. For example, if you distribute
+copies @code{gdbm}, you must give the recipients all
+the rights that you have. You must make sure that they, too, receive or
+can get the source code. And you must tell them their rights.@refill
+
+ Also, for our own protection, we must make certain that everyone finds
+out that there is no warranty for anything in the @code{gdbm} distribution.
+If these functions are modified by someone else and passed on, we want
+their recipients to know that what they have is not what we distributed,
+so that any problems introduced by others will not reflect on our
+reputation.@refill
+
+@code{Gdbm} is currently distributed under the terms of the GNU General
+Public License, Version 3. (@emph{NOT} under the GNU General Library
+Public License.) A copy the GNU General Public License is included with
+the distribution of @code{gdbm}.
+
+@node Intro
+@chapter Introduction to GNU @code{dbm}.
+
+GNU @code{dbm} (@code{gdbm}) is a library of database functions that use
+extensible hashing and works similar to the standard UNIX @code{dbm}
+functions. These routines are provided to a programmer needing to
+create and manipulate a hashed database. (@code{gdbm} is @emph{NOT} a
+complete database package for an end user.)
+
+The basic use of @code{gdbm} is to store key/data pairs in a data file.
+Each key must be unique and each key is paired with only one data item.
+The keys can not be directly accessed in sorted order. The basic unit
+of data in @code{gdbm} is the structure:
+
+@example
+ typedef struct @{
+ char *dptr;
+ int dsize;
+ @} datum;
+@end example
+
+This structure allows for arbitrary sized keys and data items.
+
+The key/data pairs are stored in a @code{gdbm} disk file, called a
+@code{gdbm} database. An application must open a @code{gdbm} database
+to be able manipulate the keys and data contained in the database.
+@code{gdbm} allows an application to have multiple databases open at the
+same time. When an application opens a @code{gdbm} database, it is
+designated as a @code{reader} or a @code{writer}. A @code{gdbm}
+database can be opened by at most one writer at a time. However, many readers
+may open the database simultaneously. Readers and writers can not
+open the @code{gdbm} database at the same time.
+
+@node List
+@chapter List of functions.
+
+The following is a quick list of the functions contained in the @code{gdbm}
+library. The include file @code{gdbm.h}, that can be included by the user,
+contains a definition of these functions.
+
+@example
+#include <gdbm.h>
+
+GDBM_FILE gdbm_open(name, block_size, flags, mode, fatal_func);
+void gdbm_close(dbf);
+int gdbm_store(dbf, key, content, flag);
+datum gdbm_fetch(dbf, key);
+int gdbm_delete(dbf, key);
+datum gdbm_firstkey(dbf);
+datum gdbm_nextkey(dbf, key);
+int gdbm_reorganize(dbf);
+void gdbm_sync(dbf);
+int gdbm_exists(dbf, key);
+char *gdbm_strerror(errno);
+int gdbm_setopt(dbf, option, value, size);
+int gdbm_fdesc(dbf);
+int gdbm_export (GDBM_FILE, const char *, int, int);
+int gdbm_export_to_file (GDBM_FILE dbf, FILE *fp);
+int gdbm_import (GDBM_FILE, const char *, int);
+int gdbm_import_from_file (GDBM_FILE dbf, FILE *fp, int flag);
+int gdbm_count (GDBM_FILE dbf, gdbm_count_t *pcount);
+int gdbm_version_cmp (int const a[], int const b[]);
+@end example
+
+The @code{gdbm.h} include file is often in the @file{/usr/include}
+directory. (The actual location of @code{gdbm.h} depends on your local
+installation of @code{gdbm}.)
+
+@node Open
+@chapter Opening the database.
+
+@cindex opening the database
+@cindex database, opening or creating
+@deftypefn {gdbm interface} GDBM_FILE gdbm_open (const char *@var{name}, int @var{block_size}, @
+ int @var{flags}, int @var{mode}, void (*fatal_func)(const char *))
+Initializes @code{gdbm} system. If the file has a size of zero bytes, a file
+initialization procedure is performed, setting up the initial structure in the
+file.
+
+The arguments are:
+
+@table @var
+@item name
+The name of the file (the complete name, @code{gdbm} does not append any
+characters to this name).
+@item block_size
+It is used during initialization to determine the size of various
+constructs. It is the size of a single transfer from disk to
+memory. This parameter is ignored if the file has been previously
+initialized. The minimum size is 512. If the value is less than 512,
+the file system block size is used, otherwise the value of
+@var{block_size} is used.
+@item flags
+@kwindex GDBM_READER
+@kwindex GDBM_WRITER
+@kwindex GDBM_WRCREAT
+@kwindex GDBM_NEWDB
+If @code{flags} is set to @samp{GDBM_READER}, the user wants to just read the
+database and any call to @code{gdbm_store} or @code{gdbm_delete} will fail.
+Many readers can access the database at the same time. If @code{flags} is
+set to @samp{GDBM_WRITER}, the user wants both read and write access
+to the database and requires exclusive access. If @code{flags} is set
+to @samp{GDBM_WRCREAT}, the user wants both read and write access to
+the database and wants it created if it does not already exist. If
+@code{flags} is set to @samp{GDBM_NEWDB}, the user want a new database
+created, regardless of whether one existed, and wants read and write
+access to the new database.
+
+@kwindex GDBM_SYNC
+@kwindex GDBM_NOLOCK
+@kwindex GDBM_NOMMAP
+The following may also be logically or'd into the database flags:
+@samp{GDBM_SYNC}, which causes all database operations to be
+synchronized to the disk, @samp{GDBM_NOLOCK}, which prevents the library
+from performing any locking on the database file, and @samp{GDBM_NOMMAP},
+which disables the memory mapping mechanism. The option @samp{GDBM_FAST} is
+now obsolete, since @code{gdbm} defaults to no-sync mode.
+
+@kwindex GDBM_CLOEXEC
+@cindex close-on-exec
+If the host @samp{open} call
+@ifhtml
+(@uref{http://www.manpagez.com/man/2/open, open(2)})
+@end ifhtml
+@ifnothtml
+(@pxref{open,,,open(2),open(2) man page})
+@end ifnothtml
+supports the @samp{O_CLOEXEC} flag, the @samp{GDBM_CLOEXEC} can be
+or'd into the flags, to enable the close-on-exec flag for the
+database file descriptor.
+@item mode
+File mode (see
+@ifhtml
+@uref{http://www.manpagez.com/man/2/chmod},
+@end ifhtml
+@ifnothtml
+@ref{chmod,,change permissions of a file,chmod(2),
+chmod(2) man page},
+@end ifnothtml
+and
+@ifhtml
+@uref{http://www.manpagez.com/man/2/open}),
+@end ifhtml
+@ifnothtml
+@pxref{open,,open a file,open(2), open(2) man page}),
+@end ifnothtml
+which is used if the file is created).
+@item fatal_func
+A function for @code{gdbm} to call if it detects a fatal error. The only
+parameter of this function is a string. If the value of @samp{NULL} is
+provided, @code{gdbm} will use a default function.
+@end table
+
+The return value, is the pointer needed by all other functions to
+access that @code{gdbm} file. If the return is the @samp{NULL} pointer,
+@code{gdbm_open} was not successful. The errors can be found in
+@code{gdbm_errno} variable (@pxref{Variables, gdbm_errno}). Available
+error codes are discussed in @ref{Error codes}.
+
+In all of the following calls, the parameter @var{dbf} refers to the pointer
+returned from @code{gdbm_open}.
+@end deftypefn
+
+@node Close
+@chapter Closing the database.
+@cindex closing database
+@cindex database, closing
+
+It is important that every file opened is also closed. This is needed to
+update the reader/writer count on the file:
+
+@deftypefn {gdbm interface} void gdbm_close (GDBM_FILE @var{dbf})
+This function closes the @code{gdbm} file and frees all memory
+associated with it. The parameter is:
+
+@table @var
+@item dbf
+The pointer returned by @code{gdbm_open}.
+@end table
+@end deftypefn
+
+@node Count
+@chapter Number of Records
+@cindex number of records
+@deftypefn {gdbm interface} int gdbm_count (GDBM_FILE @var{dbf}, @
+ gdbm_count_t *@var{pcount})
+Counts number of records in the database @var{dbf}. On success,
+stores it in the memory location pointed to by @var{pcount} and return
+0. On error, sets @code{gdbm_errno} (if relevant, also @code{errno})
+and returns -1.
+@end deftypefn
+
+@node Store
+@chapter Inserting and replacing records in the database.
+@cindex storing records
+@cindex records, storing
+
+@deftypefn {gdbm interface} int gdbm_store (GDBM_FILE @var{dbf}, datum @var{key}, @
+ datum @var{content}, int @var{flag})
+The function @code{gdbm_store} inserts or replaces records in the database.
+
+The parameters are:
+
+@table @var
+@item dbf
+The pointer returned by @code{gdbm_open}.
+@item key
+The search key.
+@item content
+The data to be associated with the key.
+@item flag
+@kwindex GDBM_REPLACE
+@kwindex GDBM_INSERT
+Defines the action to take when the key is already in the database. The value
+@samp{GDBM_REPLACE} (defined in @file{gdbm.h}) asks that the old data
+be replaced by the new @var{content}. The value @samp{GDBM_INSERT}
+asks that an error be returned and no action taken if the @var{key}
+already exists.
+@end table
+
+This function can return the following values:
+
+@table @asis
+@item -1
+The item was not stored in the database because the caller was not an
+official writer or either @var{key} or @var{content} have a
+@samp{NULL} @samp{dptr} field.
+
+Both @var{key} and @var{content} must have the @samp{dptr} field be a
+non-@samp{NULL} value. Since a @samp{NULL} @samp{dptr} field is used by
+other functions to indicate an error, it cannot be valid data.
+@item +1
+The item was not stored because the argument @var{flag} was
+@samp{GDBM_INSERT} and the @var{key} was already in the database.
+@item 0
+No error. The value of @var{content} is keyed by @var{key}. The file
+on disk is updated to reflect the structure of the new database before
+returning from this function.
+@end table
+@end deftypefn
+
+If you store data for a @var{key} that is already in the data base,
+@code{gdbm} replaces the old data with the new data if called with
+@samp{GDBM_REPLACE}. You do not get two data items for the same
+@code{key} and you do not get an error from @code{gdbm_store}.
+
+The size in @code{gdbm} is not restricted like @code{dbm} or @code{ndbm}. Your
+data can be as large as you want.
+
+@node Fetch
+@chapter Searching for records in the database.
+@cindex fetching records
+@cindex looking up records
+@cindex record, fetching
+
+@deftypefn {gdbm interface} datum gdbm_fetch (GDBM_FILE @var{dbf}, datum @var{key})
+Looks up a given @var{key} and returns the information associated with it.
+The @samp{dptr} field in the structure that is returned points to a
+memory block allocated by @code{malloc}. It is the caller's
+responsibility to free it when no longer needed.
+
+If the @samp{dptr} is @samp{NULL}, no data was found.
+
+The parameters are:
+
+@table @var
+@item dbf
+The pointer returned by @code{gdbm_open}.
+@item key
+The search key.
+@end table
+@end deftypefn
+
+An example of using this function:
+
+@example
+content = gdbm_fetch (dbf, key);
+if (content.dptr == NULL)
+ @{
+ fprintf(stderr, "key not found\n");
+ @}
+else
+ @{
+ /* do something with content.dptr */
+ @}
+@end example
+
+@cindex records, testing existence
+You may also search for a particular key without retrieving it:
+
+@deftypefn {gdbm interface} int gdbm_exists (GDBM_FILE @var{dbf}, datum @var{key})
+Returns @samp{true} (@samp{1}) if the @var{key} exists in @var{dbf}
+and @samp{false} (@samp{0}) otherwise.
+
+The parameters are:
+
+@table @var
+@item dbf
+The pointer returned by @code{gdbm_open}.
+@item key
+The search key.
+@end table
+@end deftypefn
+
+@node Delete
+@chapter Removing records from the database.
+@cindex deleting records
+@cindex record, deleting
+
+To remove some data from the database, use the @code{gdbm_delete}
+function.
+
+@deftypefn {gdbm interface} int gdbm_delete (GDBM_FILE @var{dbf}, datum @var{key})
+Deletes the data associated with the given @var{key}, if it exists in
+the database @var{dbf}. The file on disk is updated to reflect the
+structure of the new database before returning from this function.
+
+The parameters are:
+
+@table @var
+@item dbf
+The pointer returned by @code{gdbm_open}.
+@item datum key
+The search key.
+@end table
+
+The function returns @samp{-1} if the item is not present or the
+requester is a reader. The return of @samp{0} marks a successful delete.
+@end deftypefn
+
+@node Sequential
+@chapter Sequential access to records.
+@cindex sequential access
+@cindex iterating over records
+@cindex records, iterating over
+
+The next two functions allow for accessing all items in the database. This
+access is not @code{key} sequential, but it is guaranteed to visit every
+@code{key} in the database once. The order has to do with the hash values.
+@code{gdbm_firstkey} starts the visit of all keys in the database.
+@code{gdbm_nextkey} finds and reads the next entry in the hash structure for
+@code{dbf}.
+
+@deftypefn {gdbm interface} datum gdbm_firstkey (GDBM_FILE @var{dbf})
+Initiate sequential access to the database @var{dbf}. The returned
+value is the first key accessed in the database. If the @samp{dptr}
+field in the returned datum is @samp{NULL}, the database contains no
+data.
+
+Otherwise, @samp{dptr} points to a memory block obtained from
+@code{malloc}, which holds the key value. The caller is responsible
+for freeing this memory block when no longer needed.
+@end deftypefn
+
+@deftypefn {gdbm interface} datum gdbm_nextkey (GDBM_FILE @var{dbf}, datum @var{prev})
+This function continues the iteration over the keys in @var{dbf},
+initiated by @code{gdbm_firstkey}. The parameter @var{prev} holds the
+value returned from a previous call to @code{gdbm_nextkey} or
+@code{gdbm_firstkey}.
+
+The function returns next key from the database. If the @samp{dptr}
+field in the returned datum is @samp{NULL}, all keys in the database
+has been visited.
+
+Otherwise, @samp{dptr} points to a memory block obtained from
+@code{malloc}, which holds the key value. The caller is responsible
+for freeing this memory block when no longer needed.
+@end deftypefn
+
+@cindex iteration loop
+These functions were intended to visit the database in read-only algorithms,
+for instance, to validate the database or similar operations. The
+usual algorithm for sequential access is:
+
+@example
+@group
+ key = gdbm_firstkey (dbf);
+ while (key.dptr)
+ @{
+ datum nextkey;
+
+ /* do something with the key */
+ ...
+
+ /* Obtain the next key */
+ nextkey = gdbm_nextkey (dbf, key);
+ /* Reclaim the memory used by the key */
+ free (key.dptr);
+ /* Use nextkey in the next iteration. */
+ key = nextkey;
+ @}
+@end group
+@end example
+
+@cindex iteration and @code{gdbm_delete}
+@cindex deletion in iteration loops
+@cindex @code{gdbm_delete} and sequential access
+Care should be taken when the @code{gdbm_delete} function is used in
+such a loop. File visiting is based on a @dfn{hash table}. The
+@code{gdbm_delete} function re-arranges the hash table to make sure
+that any collisions in the table do not leave some item
+@dfn{un-findable}. The original key order is @emph{not} guaranteed to
+remain unchanged in all instances. So it is possible that some key
+will not be visited if a loop like the following is executed:
+
+@example
+@group
+ key = gdbm_firstkey (dbf);
+ while (key.dptr)
+ @{
+ datum nextkey;
+ if (some condition)
+ @{
+ gdbm_delete (dbf, key);
+ @}
+ nextkey = gdbm_nextkey (dbf, key);
+ free (key.dptr);
+ key = nextkey;
+ @}
+@end group
+@end example
+
+@node Reorganization
+@chapter Database reorganization.
+@cindex database reorganization
+@cindex reorganization, database
+
+The following function should be used very seldom.
+
+@deftypefn {gdbm interface} int gdbm_reorganize (GDBM_FILE @var{dbf})
+Reorganizes the database.
+
+The parameter is:
+
+@table @var
+@item dbf
+The pointer returned by @code{gdbm_open}.
+@end table
+@end deftypefn
+
+If you have had a lot of deletions and would like to shrink the space
+used by the @code{gdbm} file, this function will reorganize the database.
+This results, in particular, in shortening the length of a @code{gdbm}
+file by removing the space occupied by deleted records.
+
+This reorganization requires creating a new file and inserting all the elements
+in the old file @var{dbf} into the new file. The new file is then renamed to
+the same name as the old file and @var{dbf} is updated to contain all the
+correct information about the new file. If an error is detected, the return
+value is negative. The value zero is returned after a successful
+reorganization.
+
+@node Sync
+@chapter Database Synchronization
+@cindex database synchronization
+@cindex synchronization, database
+
+@kwindex GDBM_SYNC
+Unless your database was opened with the @samp{GDBM_SYNC} flag,
+@code{gdbm} does not wait for writes to be flushed to the disk before
+continuing. This allows for faster writing of databases at the risk
+of having a corrupted database if the application terminates in an
+abnormal fashion. The following function allows the programmer to
+make sure the disk version of the database has been completely updated
+with all changes to the current time.
+
+@deftypefn {gdbm interface} void gdbm_sync (GDBM_FILE @var{dbf})
+Synchronizes the changes in @var{dbf} with its disk file. The
+parameter is a pointer returned by @code{gdbm_open}.
+
+This function would usually be called after a complete set of changes
+have been made to the database and before some long waiting time.
+The @code{gdbm_close} function automatically calls the equivalent of
+@code{gdbm_sync} so no call is needed if the database is to be closed
+immediately after the set of changes have been made.
+@end deftypefn
+
+@node Flat files
+@chapter Export and Import
+@cindex Flat file format
+@cindex export
+@cindex import
+@code{Gdbm} databases can be converted into so-called @dfn{flat
+format} files. Such files cannot be used for searching, their sole
+purpose is to keep the data from the database for restoring it when
+the need arrives. There are two flat file formats, which differ in
+the way they represent the data and in the amount of meta-information
+stored. Both formats 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.
+
+The GDBM version @value{VERSION} supports two flat file formats. The
+@dfn{binary} flat file format was first implemented in GDBM version
+1.9.1. This format stores only key/data pairs, it does not keep
+information about the database file itself. As its name implies,
+files in this format are binary files.
+
+The @dfn{ascii} flat file format encodes all data in base64 and stores
+not only key/data pairs, but also the original database file metadata,
+such as file name, mode and ownership. Files in this format can be
+sent without additional encapsulation over transmission channels that
+normally allow only ASCII data, such as, e.g.@: SMTP. Due to additional
+metadata they allow for restoring an exact copy of the database,
+including file ownership and privileges, which is especially important
+if the database in question contained some security-related data.
+
+We call a process of creating a flat file from a database
+@dfn{exporting} or @dfn{dumping} this database. The reverse process,
+creating the database from a flat file is called @dfn{importing} or
+@dfn{loading} 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:
+
+@table @var
+@item dbf
+A pointer to the source database, returned by a prior call to
+@code{gdbm_open}.
+
+@item filename
+Name of the dump file.
+
+@item format
+Output file 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.
+
+@item mode
+The permissions to use when creating the output file.
+@ifhtml
+See @uref{http://www.manpagez.com/man/2/open},
+@end ifhtml
+@ifnothtml
+See @ref{open,,open a file,open(2), open(2) man page},
+@end ifnothtml
+for a detailed discussion.
+@end table
+@end deftypefn
+
+@anchor{gdbm_load function}
+@deftypefn {gdbm interface} int gdbm_load (GDBM_FILE *@var{pdbf}, @
+ 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
+function will return, in the memory location pointed to by @var{pdbf},
+a pointer to the newly created database. 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 @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.
+
+If a fatal error occurs, @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
+
+Mild errors mean that the function was able to successfully load and
+restore the data, but was unable to change database file metadata
+afterward. The table below lists possible values for @code{gdbm_errno}
+in this case. To get more detail, inspect the system @code{errno} variable.
+
+@table @asis
+@kwindex GDBM_ERR_FILE_OWNER
+@item GDBM_ERR_FILE_OWNER
+The function was unable to restore database file owner.
+
+@kwindex GDBM_ERR_FILE_MODE
+@item GDBM_ERR_FILE_MODE
+The function was unable to restore database file mode (permission bits).
+@end table
+
+If an error occurs while loading data from an input file 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}.
+
+If the line information is not available or applicable, @var{errline}
+will be set to @samp{0}.
+@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:
+
+@table @var
+@item dbf
+A pointer to the source database, returned by a call to
+@code{gdbm_open}.
+
+@item fp
+File to write the data to.
+
+@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}, 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
+@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_export_to_file (GDBM_FILE @var{dbf}, FILE *@var{fp})
+This is an alternative entry point to @code{gdbm_export}. This
+function writes to file @var{fp} a binary dump of the database @var{dbf}.
+@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:
+
+@example
+@var{dbf} = gdbm_open (@var{importfile}, 0,
+ @var{flag} == GDBM_REPLACE ?
+ GDBM_WRCREAT : GDBM_NEWDB,
+ 0600, NULL);
+gdbm_load (&@var{dbf}, @var{exportfile}, 0, @var{flag}, NULL)
+@end example
+@end deftypefn
+
+@deftypefn {gdbm interface} int gdbm_import_from_file (GDBM_FILE @var{dbf}, @
+ FILE *@var{fp}, int @var{flag})
+An alternative entry point to @code{gdbm_import}. Reads the binary
+dump from the file @var{fp} and stores the key/value pairs to
+@var{dbf}. @xref{Store}, for a description of @var{flag}.
+
+This function is equivalent to:
+
+@example
+@var{dbf} = gdbm_open (@var{importfile}, 0,
+ @var{flag} == GDBM_REPLACE ?
+ GDBM_WRCREAT : GDBM_NEWDB,
+ 0600, NULL);
+gdbm_load_from_file (@var{dbf}, @var{fp}, @var{flag}, 0, NULL);
+@end example
+@end deftypefn
+
+@node Errors
+@chapter Error strings.
+@cindex error strings
+
+To convert a @code{gdbm} error code into English text, use this
+routine:
+
+@deftypefn {gdbm interface} {const char *} gdbm_strerror (gdbm_error @var{errno})
+Converts @var{errno} (which is an integer value) into a human-readable
+descriptive text. Returns a pointer to a static string. The caller
+must not alter or free the returned pointer.
+
+The @var{errno} argument is usually the value of the global variable
+@code{gdbm_errno}. @xref{Variables, gdbm_errno}.
+@end deftypefn
+
+@node Options
+@chapter Setting options
+@cindex database options
+@cindex options, database
+
+@code{Gdbm} supports the ability to set certain options on an already
+open database.
+
+@deftypefn {gdbm interface} int gdbm_setopt (GDBM_FILE @var{dbf}, int @var{option}, @
+ void *@var{value}, int @var{size})
+Sets an option on the database or returns the value of an option.
+
+The parameters are:
+
+@table @var
+@item dbf
+The pointer returned by @code{gdbm_open}.
+@item option
+The option to be set or retrieved.
+@item value
+A pointer to the value to which @var{option} will be set or where to
+place the option value (depending on the option).
+@item size
+The length of the data pointed to by @var{value}.
+@end table
+@end deftypefn
+
+The valid options are:
+
+@table @asis
+@kwindex GDBM_CACHESIZE
+@kwindex GDBM_SETCACHESIZE
+@item GDBM_SETCACHESIZE
+@itemx GDBM_CACHESIZE
+Set the size of the internal bucket cache. This option may only be
+set once on each GDBM_FILE descriptor, and is set automatically to 100
+upon the first access to the database. The @var{value} should point
+to a @code{size_t} holding the desired cache size.
+
+The @samp{GDBM_CACHESIZE} option is provided for compatibility with
+earlier versions.
+
+@kwindex GDBM_GETCACHESIZE
+@item GDBM_GETCACHESIZE
+Return the size of the internal bucket cache. The @var{value} should
+point to a @code{size_t} variable, where the size will be stored.
+
+@kwindex GDBM_GETFLAGS
+@item GDBM_GETFLAGS
+Return the flags describing the state of the database. The @var{value} should
+point to a @code{int} variable where to store the flags. The return
+is the same as the flags used when opening the database (@pxref{Open,
+gdbm_open}), except that it reflects the current state (which may have
+been altered by another calls to @code{gdbm_setopt}.
+
+@kwindex GDBM_FASTMODE
+@item GDBM_FASTMODE
+Enable or disable the @dfn{fast writes mode}, i.e.@: writes without
+subsequent synchronization. The @var{value} should point
+to an integer: @samp{TRUE} to enable fast mode, and @samp{FALSE} to
+disable it.
+
+This option is retained for compatibility with previous versions of
+@code{gdbm}. Its effect is the reverse of @code{GDBM_SETSYNCMODE}
+(see below).
+
+@kwindex GDBM_SETSYNCMODE
+@kwindex GDBM_SYNCMODE
+@item GDBM_SETSYNCMODE
+@itemx GDBM_SYNCMODE
+Turn on or off file system synchronization operations. This
+setting defaults to off. The @var{value} should point
+to an integer: @samp{TRUE} to turn synchronization on, and @samp{FALSE} to
+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
+as calling @code{GDBM_FASTMODE} with @samp{FALSE}.
+
+The @samp{GDBM_SYNCMODE} option is provided for compatibility with
+earlier versions.
+
+@kwindex GDBM_GETSYNCMODE
+@item GDBM_GETSYNCMODE
+Return the current synchronization status. The @var{value} should
+point to an @code{int} where the status will be stored.
+
+@kwindex GDBM_SETCENTFREE
+@kwindex GDBM_CENTFREE
+@item GDBM_SETCENTFREE
+@itemx GDBM_CENTFREE
+@emph{NOTICE: This feature is still under study.}
+
+Set central free block pool to either on or off. The default is off,
+which is how previous versions of @code{gdbm} handled free blocks. If
+set, this option causes all subsequent free blocks to be placed in the
+@emph{global} pool, allowing (in theory) more file space to be reused
+more quickly. The @var{value} should point to an integer: @samp{TRUE} to
+turn central block pool on, and @samp{FALSE} to turn it off.
+
+The @samp{GDBM_CENTFREE} option is provided for compatibility with
+earlier versions.
+
+@kwindex GDBM_SETCOALESCEBLKS
+@kwindex GDBM_COALESCEBLKS
+@item GDBM_SETCOALESCEBLKS
+@itemx GDBM_COALESCEBLKS
+@emph{NOTICE: This feature is still under study.}
+
+Set free block merging to either on or off. The default is off, which
+is how previous versions of @code{gdbm} handled free blocks. If set,
+this option causes adjacent free blocks to be merged. This can become
+a @acronym{CPU} expensive process with time, though, especially if
+used in conjunction with GDBM_CENTFREE. The @var{value} should