diff options
Diffstat (limited to 'doc/gdbm.texi')
-rw-r--r-- | doc/gdbm.texi | 2567 |
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 |