From 295a4f5dc8197b7bf7c5f2d023fb940dbc6d4ab8 Mon Sep 17 00:00:00 2001 From: Sergey Poznyakoff Date: Thu, 7 Jul 2016 22:27:47 +0300 Subject: Switch to Git repository --- .cvsignore | 16 - .gitignore | 35 + ChangeLog | 15 + compat/.cvsignore | 6 - compat/.gitignore | 6 + doc/.cvsignore | 26 - doc/.gitignore | 26 + doc/Makefile.am | 4 +- doc/gdbm.texi | 2567 +++++++++++++++++++++++++++++++++++++++++++++++++++++ doc/gdbm.texinfo | 2567 ----------------------------------------------------- export/.cvsignore | 5 - export/.gitignore | 5 + po/.cvsignore | 21 - po/.gitignore | 21 + src/.cvsignore | 14 - src/.gitignore | 14 + tests/.cvsignore | 26 - tests/.gitignore | 26 + 18 files changed, 2717 insertions(+), 2683 deletions(-) delete mode 100644 .cvsignore create mode 100644 .gitignore delete mode 100644 compat/.cvsignore create mode 100644 compat/.gitignore delete mode 100644 doc/.cvsignore create mode 100644 doc/.gitignore create mode 100644 doc/gdbm.texi delete mode 100644 doc/gdbm.texinfo delete mode 100644 export/.cvsignore create mode 100644 export/.gitignore delete mode 100644 po/.cvsignore create mode 100644 po/.gitignore delete mode 100644 src/.cvsignore create mode 100644 src/.gitignore delete mode 100644 tests/.cvsignore create mode 100644 tests/.gitignore diff --git a/.cvsignore b/.cvsignore deleted file mode 100644 index 760601c..0000000 --- a/.cvsignore +++ /dev/null @@ -1,16 +0,0 @@ -.emacs* -*.tar.* -ABOUT-NLS -Makefile -Makefile.in -aclocal.m4 -autoconf.h.in -autoconf.h -autom4te.cache -build-aux -config.log -config.status -configure -libtool -m4 -stamp-h1 diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..12a8466 --- /dev/null +++ b/.gitignore @@ -0,0 +1,35 @@ +*.a +*.la +*.lo +*.o +*.orig +*.pyc +*.rej +*.tar.bz2 +*.tar.gz +*.tar.xz +*~ +.deps +.emacs* +.libs +ABOUT-NLS +ChangeLog +INSTALL +Makefile +Makefile.in +TAGS +aclocal.m4 +autoconf.h +autoconf.h.in +autom4te.cache +build-aux +config.log +config.status +configure +configure.ac +core +gmon.out +libltdl +libtool +m4 +stamp-h1 diff --git a/ChangeLog b/ChangeLog index e08148b..51751d4 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,18 @@ +2016-07-07 Sergey Poznyakoff + + Switch to Git repository + + * .cvsignore: Rename to .gitignore + * compat/.cvsignore: Likewise. + * doc/.cvsignore: Likewise. + * export/.cvsignore: Likewise. + * po/.cvsignore: Likewise. + * src/.cvsignore: Likewise. + * tests/.cvsignore: Likewise. + + * doc/gdbm.texinfo: Rename to doc/gdbm.texi + * doc/Makefile.am: Update + 2016-07-06 Sergey Poznyakoff * doc/gdbm.texinfo: Normal installation prefix is /usr. diff --git a/compat/.cvsignore b/compat/.cvsignore deleted file mode 100644 index 62535c7..0000000 --- a/compat/.cvsignore +++ /dev/null @@ -1,6 +0,0 @@ -.deps -.libs -*.la -*.lo -Makefile -Makefile.in diff --git a/compat/.gitignore b/compat/.gitignore new file mode 100644 index 0000000..62535c7 --- /dev/null +++ b/compat/.gitignore @@ -0,0 +1,6 @@ +.deps +.libs +*.la +*.lo +Makefile +Makefile.in diff --git a/doc/.cvsignore b/doc/.cvsignore deleted file mode 100644 index e3d20a8..0000000 --- a/doc/.cvsignore +++ /dev/null @@ -1,26 +0,0 @@ -*.tar.* -Makefile -Makefile.in -gdbm.info -gdbm.dvi -gdbm.pdf -gdbm.ps -gdbm.html -gdbm.aux -gdbm.cp -gdbm.cps -gdbm.fl -gdbm.fn -gdbm.fns -gdbm.kw -gdbm.ky -gdbm.log -gdbm.pg -gdbm.pr -gdbm.toc -gdbm.tp -gdbm.vr -gdbm.vrs -manual -stamp-vti -version.texi diff --git a/doc/.gitignore b/doc/.gitignore new file mode 100644 index 0000000..e3d20a8 --- /dev/null +++ b/doc/.gitignore @@ -0,0 +1,26 @@ +*.tar.* +Makefile +Makefile.in +gdbm.info +gdbm.dvi +gdbm.pdf +gdbm.ps +gdbm.html +gdbm.aux +gdbm.cp +gdbm.cps +gdbm.fl +gdbm.fn +gdbm.fns +gdbm.kw +gdbm.ky +gdbm.log +gdbm.pg +gdbm.pr +gdbm.toc +gdbm.tp +gdbm.vr +gdbm.vrs +manual +stamp-vti +version.texi diff --git a/doc/Makefile.am b/doc/Makefile.am index 8773b75..1c83450 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -1,5 +1,5 @@ # This file is part of GDBM. -*- Makefile -*- -# Copyright (C) 2007, 2011, 2014, 2015 Free Software Foundation, Inc. +# Copyright (C) 2007, 2011, 2014-2016 Free Software Foundation, Inc. # # GDBM is free software; you can redistribute it and/or modify # it under the terms of the GNU General Public License as published by @@ -16,7 +16,7 @@ # Documentation -info_TEXINFOS = gdbm.texinfo +info_TEXINFOS = gdbm.texi gdbm_TEXINFOS=\ fdl.texi 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_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 point +to an integer: @samp{TRUE} to turn free block merging on, and @samp{FALSE} to +turn it off. + +@kwindex GDBM_GETCOALESCEBLKS +@item GDBM_GETCOALESCEBLKS +Return the current status of free block merging. The @var{value} should +point to an @code{int} where the status will be stored. + +@kwindex GDBM_SETMAXMAPSIZE +@item GDBM_SETMAXMAPSIZE +Sets maximum size of a memory mapped region. The @var{value} should +point to a value of type @code{size_t}, @code{unsigned long} or +@code{unsigned}. The actual value is rounded to the nearest page +boundary (the page size is obtained from +@code{sysconf(_SC_PAGESIZE)}). + +@kwindex GDBM_GETMAXMAPSIZE +@item GDBM_GETMAXMAPSIZE +Return the maximum size of a memory mapped region. The @var{value} should +point to a value of type @code{size_t} where to return the data. + +@kwindex GDBM_SETMMAP +@item GDBM_SETMMAP +Enable or disable memory mapping mode. The @var{value} should point +to an integer: @samp{TRUE} to enable memory mapping or @samp{FALSE} to +disable it. + +@kwindex GDBM_GETMMAP +@item GDBM_GETMMAP +Check whether memory mapping is enabled. The @var{value} should point +to an integer where to return the status. + +@kwindex GDBM_GETDBNAME +@item GDBM_GETDBNAME +Return the name of the database disk file. The @var{value} should +point to a variable of type @code{char**}. A pointer to the newly +allocated copy of the file name will be placed there. The caller is +responsible for freeing this memory when no longer needed. For +example: + +@example +char *name; + +if (gdbm_setopt (dbf, GDBM_GETDBNAME, &name, sizeof (name))) + @{ + fprintf (stderr, "gdbm_setopt failed: %s\n", + gdbm_strerror (gdbm_errno)); + @} +else + @{ + printf ("database name: %s\n", name); + free (name); + @} +@end example + +@end table + +The return value will be @samp{-1} upon failure, or @samp{0} upon +success. The global variable @code{gdbm_errno} will be set upon failure. + +For instance, to set a database to use a cache of 10, after opening it +with @code{gdbm_open}, but prior to accessing it in any way, the following +code could be used: + +@example +@group +int value = 10; +ret = gdbm_setopt (dbf, GDBM_CACHESIZE, &value, sizeof (int)); +@end group +@end example + +@node Locking +@chapter File Locking. +@cindex locking + +@kwindex GDBM_NOLOCK +With locking disabled (if @code{gdbm_open} was called with @samp{GDBM_NOLOCK}), +the user may want to perform their own file locking on the database file +in order to prevent multiple writers operating on the same file +simultaneously. + +In order to support this, the @code{gdbm_fdesc} routine is provided. + +@deftypefn {gdbm interface} int gdbm_fdesc (GDBM_FILE @var{dbf}) +Returns the file descriptor of the database @var{dbf}. This value +can be used as an argument to @code{flock}, @code{lockf} or similar +calls. +@end deftypefn + +@node Variables +@chapter Useful global variables. + +The following global variables and constants are available: + +@deftypevar gdbm_error gdbm_errno +This variable contains error code from the last failed @code{gdbm} +call. @xref{Error codes}, for a list of available error codes and +their descriptions. + +Use @code{gdbm_strerror} (@pxref{Errors}) to convert it to a +descriptive text. +@end deftypevar + +@deftypevar {const char *} 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 + +@cindex version number +@deftypevar {const char *} gdbm_version +A string containing the version information. +@end deftypevar + +@deftypevar {int const} gdbm_version_number[3] +This variable contains the @code{gdbm} version numbers: + +@multitable @columnfractions 0.4 0.5 +@headitem Index @tab Meaning +@item 0 @tab Major number +@item 1 @tab Minor number +@item 2 @tab Patchlevel number +@end multitable + +Additionally, the following constants are defined in the @file{gdbm.h} +file: + +@table @asis +@kwindex GDBM_VERSION_MAJOR +@item GDBM_VERSION_MAJOR +Major number. + +@kwindex GDBM_VERSION_MINOR +@item GDBM_VERSION_MINOR +Minor number. + +@kwindex GDBM_VERSION_PATCH +@item GDBM_VERSION_PATCH +Patchlevel number. +@end table + +These can be used to verify whether the header file matches the library. +@end deftypevar + +To compare two split-out version numbers, use the following function: + +@deftypefn {gdbm interface} int gdbm_version_cmp (int const @var{a}[3], @ + int const @var{b}[3]) +Compare two version numbers. Return @samp{-1} if @var{a} is less than +@var{b}, @samp{1} if @var{a} is greater than @var{b} and @samp{0} if +they are equal. + +Comparison is done from left to right, so that: + +@example +a = @{ 1, 8, 3 @}; +b = @{ 1, 8, 3 @}; +gdbm_version_cmp (a, b) @result{} 0 + +a = @{ 1, 8, 3 @}; +b = @{ 1, 8, 2 @}; +gdbm_version_cmp (a, b) @result{} 1 + +a = @{ 1, 8, 3 @}; +b = @{ 1, 9. 0 @}; +gdbm_version_cmp (a, b) @result{} -1 +@end example +@end deftypefn + +@node Error codes +@chapter Error codes +@cindex error codes + +This chapter summarizes error codes which can be set by the +functions in @code{gdbm} library. + +@table @asis +@kwindex GDBM_NO_ERROR +@item GDBM_NO_ERROR +No error occurred. + +@kwindex GDBM_MALLOC_ERROR +@item GDBM_MALLOC_ERROR +Memory allocation failed. Not enough memory. + +@kwindex GDBM_BLOCK_SIZE_ERROR +@item GDBM_BLOCK_SIZE_ERROR +This error is set by the @code{gdbm_open} function (@pxref{Open}), if +the value of its @var{block_size} argument is incorrect. + +@kwindex GDBM_FILE_OPEN_ERROR +@item GDBM_FILE_OPEN_ERROR +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 (@pxref{Flat files}). + +Inspect the value of the system @code{errno} variable to get more +detailed diagnostics. + +@kwindex GDBM_FILE_WRITE_ERROR +@item GDBM_FILE_WRITE_ERROR +Writing to a disk file failed. This can be set by +@code{gdbm_open} (@pxref{Open}), @code{gdbm_export} and +@code{gdbm_import} functions. + +Inspect the value of the system @code{errno} variable to get more +detailed diagnostics. + +@kwindex GDBM_FILE_SEEK_ERROR +@item GDBM_FILE_SEEK_ERROR +Positioning in a disk file failed. This can be set by +@code{gdbm_open} (@pxref{Open}) function. + +Inspect the value of the system @code{errno} variable to get a more +detailed diagnostics. + +@kwindex GDBM_FILE_READ_ERROR +@item GDBM_FILE_READ_ERROR +Reading from a disk file failed. This can be set by +@code{gdbm_open} (@pxref{Open}), @code{gdbm_export} and +@code{gdbm_import} functions. + +Inspect the value of the system @code{errno} variable to get a more +detailed diagnostics. + +@kwindex GDBM_BAD_MAGIC_NUMBER +@item GDBM_BAD_MAGIC_NUMBER +The file given as argument to @code{gdbm_open} function is not a valid +@code{gdbm} file: it has a wrong magic number. + +@kwindex GDBM_EMPTY_DATABASE +@item GDBM_EMPTY_DATABASE +The file given as argument to @code{gdbm_open} function is not a valid +@code{gdbm} file: it has zero length. + +@kwindex GDBM_CANT_BE_READER +@item GDBM_CANT_BE_READER +This error code is set by the @code{gdbm_open} function if it is not +able to lock file when called in @samp{GDBM_READER} mode (@pxref{Open, +GDBM_READER}). + +@kwindex GDBM_CANT_BE_WRITER +@item GDBM_CANT_BE_WRITER +This error code is set by the @code{gdbm_open} function if it is not +able to lock file when called in writer mode (@pxref{Open}). + +@kwindex GDBM_READER_CANT_DELETE +@item GDBM_READER_CANT_DELETE +Set by the @code{gdbm_delete} (@pxref{Delete}) if it attempted to +operate on a database that is open in read-only mode (@pxref{Open, +GDBM_READER}). + +@kwindex GDBM_READER_CANT_STORE +@item GDBM_READER_CANT_STORE +Set by the @code{gdbm_store} (@pxref{Store}) if it attempted to +operate on a database that is open in read-only mode (@pxref{Open, +GDBM_READER}). + +@kwindex GDBM_READER_CANT_REORGANIZE +@item GDBM_READER_CANT_REORGANIZE +Set by the @code{gdbm_reorganize} (@pxref{Reorganization}) if it attempted to +operate on a database that is open in read-only mode (@pxref{Open, +GDBM_READER}). + +@kwindex GDBM_UNKNOWN_UPDATE +@item GDBM_UNKNOWN_UPDATE +Currently unused. Reserved for future uses. + +@kwindex GDBM_ITEM_NOT_FOUND +@item GDBM_ITEM_NOT_FOUND +Requested item was not found. This error is set by @code{gdbm_delete} +(@pxref{Delete}) and @code{gdbm_fetch} (@pxref{Fetch}) when the requested +@var{key} value is not found in the database. + +@kwindex GDBM_REORGANIZE_FAILED +@item GDBM_REORGANIZE_FAILED +The @code{gdbm_reorganize} function is not +able to create a temporary database. @xref{Reorganization}. + +@kwindex GDBM_CANNOT_REPLACE +@item GDBM_CANNOT_REPLACE +Cannot replace existing item. This error is set by the +@code{gdbm_store} if the requested @var{key} value is found in the +database and the @var{flag} parameter is not @samp{GDBM_REPLACE}. +@xref{Store}, for a detailed discussion. + +@kwindex GDBM_ILLEGAL_DATA +@item GDBM_ILLEGAL_DATA +Either @var{key} or @var{content} parameter was wrong in a call to +to @code{gdbm_store} (@pxref{Store}). + +@kwindex GDBM_OPT_ALREADY_SET +@item GDBM_OPT_ALREADY_SET +Requested option can be set only once and was already set. This error +is returned by the @code{gdbm_setopt} function. @xref{Options, +GDBM_CACHESIZE}. + +@kwindex GDBM_OPT_ILLEGAL +@item GDBM_OPT_ILLEGAL +The @var{option} argument is not valid or the @var{value} argument +points to an invalid value in a call to @code{gdbm_setopt} function. +@xref{Options}. + +@kwindex GDBM_BYTE_SWAPPED +@item GDBM_BYTE_SWAPPED +The @code{gdbm_open} function (@pxref{Open}) attempts to open a +database which is created on a machine with different byte ordering. + +@kwindex GDBM_BAD_FILE_OFFSET +@item GDBM_BAD_FILE_OFFSET +The @code{gdbm_open} function (@pxref{Open}) sets this error code if +the file it tries to open has a wrong magic number. + +@kwindex GDBM_BAD_OPEN_FLAGS +@item GDBM_BAD_OPEN_FLAGS +Set by the @code{gdbm_export} function if supplied an invalid +@var{flags} argument. @xref{Flat files}. + +@kwindex GDBM_FILE_STAT_ERROR +@item GDBM_FILE_STAT_ERROR +Getting information about a disk file failed. The system @code{errno} +will give more details about the error. + +This error can be set by the following functions: @code{gdbm_open}, +@code{gdbm_reorganize}. + +@kwindex GDBM_FILE_EOF +@item GDBM_FILE_EOF +End of file was encountered where more data was expected to be +present. This error can occur when fetching data from the database +and usually means that the database is truncated or otherwise corrupted. + +This error can be set by any GDBM function that does I/O. Some of +these functions are: @code{gdbm_delete}, @code{gdbm_exists}, +@code{gdbm_fetch}, @code{gdbm_export}, @code{gdbm_import}, +@code{gdbm_reorganize}, @code{gdbm_firstkey}, @code{gdbm_nextkey}, +@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. + +@kwindex GDBM_ERR_FILE_OWNER +@item GDBM_ERR_FILE_OWNER +This error code is set by @code{gdbm_load} if it is unable to restore +database file owner. It is a mild error condition, meaning that the +data have been restored successfully, only changing the target file +owner failed. Inspect the system @code{errno} variable to get a more +detailed diagnostics. + +@kwindex GDBM_ERR_FILE_MODE +@item GDBM_ERR_FILE_MODE +This error code is set by @code{gdbm_load} if it is unable to restore +database file mode. It is a mild error condition, meaning that the data +have been restored successfully, only changing the target file owner +failed. Inspect the system @code{errno} variable to get a more +detailed diagnostics. + +@end table + +@node Compatibility +@chapter Compatibility with standard @code{dbm} and @code{ndbm}. + +@cindex compatibility layer +@code{Gdbm} includes a compatibility layer, which provides traditional +@samp{ndbm} and older @samp{dbm} functions. The layer is compiled and +installed if the @option{--enable-libgdbm-compat} option is used when +configuring the package. + +@findex ndbm.h +@findex dbm.h +@findex libgdbm_compat +The compatibility layer consists of two header files: @file{ndbm.h} +and @file{dbm.h} and the @file{libgdbm_compat} library. + +Older programs using @code{ndbm} or @code{dbm} interfaces can +use @file{libgdbm_compat} without any changes. To link a program with +the compatibility library, add the following two options to the +@command{cc} invocation: @option{-lgdbm -lgdbm_compat}. The @option{-L} +option may also be required, depending on where @code{gdbm} is +installed, e.g.: + +@example +cc ... -lgdbm -lgdbm_compat +@end example + +@cindex @samp{dir} file +@cindex @samp{pag} file +Databases created and manipulated by the compatibility interfaces +consist of two different files: @file{@var{file}.dir} and +@file{@var{file}.pag}. This is required by the @acronym{POSIX} +specification and corresponds to the traditional usage. Note, +however, that despite the similarity of the naming convention, +actual data stored in these files has not the same format as +in the databases created by other @code{dbm} or @code{ndbm} +libraries. In other words, you cannot access a standard UNIX +@code{dbm} file with GNU @code{dbm}! + +GNU @code{dbm} files are not @code{sparse}. You can copy them with +the usual @code{cp} command and they will not expand in the copying +process. + +@menu +* ndbm:: NDBM interface functions. +* dbm:: DBM interface functions. +@end menu + +@node ndbm +@section NDBM interface functions. +@cindex NDBM functions + +The functions below implement the @acronym{POSIX} @samp{ndbm} interface: + +@deftypefn {ndbm} {DBM *} dbm_open (char *@var{file}, int @var{flags}, int @var{mode}) +Opens a database. The @var{file} argument is the full name of the +database file to be opened. The function opens two files: +@file{@var{file}.pag} and @file{@var{file}.dir}. The @var{flags} and +@var{mode} arguments have the same meaning as the second and third +arguments of +@ifhtml +@uref{http://www.manpagez.com/man/2/open,,open(2)}, +@end ifhtml +@ifnothtml +@code{open} (@pxref{open,,open a file,open(2), open(2) man page}), +@end ifnothtml +except that a database opened for write-only access opens the files +for read and write access and the behavior of the @code{O_APPEND} flag is +unspecified. + +The function returns a pointer to the @code{DBM} structure describing +the database. This pointer is used to refer to this database in all +operations described below. + +Any error detected will cause a return value of @samp{NULL} and an +appropriate value will be stored in @code{gdbm_errno} +(@pxref{Variables}). +@end deftypefn + +@deftypefn {ndbm} void dbm_close (DBM *@var{dbf}) +Closes the database. The @var{dbf} argument must be a pointer +returned by an earlier call to @code{dbm_open}. +@end deftypefn + +@deftypefn {ndbm} datum dbm_fetch (DBM *@var{dbf}, datum @var{key}) +Reads a record from the database with the matching key. The @var{key} +argument supplies the key that is being looked for. + +If no matching record is found, the @code{dptr} member of the returned +datum is @samp{NULL}. Otherwise, the @code{dptr} member of the +returned datum points to the memory managed by the compatibility +library. The application should never free it. +@end deftypefn + +@deftypefn {ndbm} int dbm_store (DBM *@var{dbf}, datum @var{key}, @ + datum @var{content}, int @var{mode}) +Writes a key/value pair to the database. The argument @var{dbf} is a +pointer to the @code{DBM} structure returned from a call to +@code{dbm_open}. The @var{key} and @var{content} provide the values +for the record key and content. The @var{mode} argument controls +the behavior of @code{dbm_store} in case a matching record already +exists in the database. It can have one of the following two values: + +@table @code +@kwindex DBM_REPLACE +@item DBM_REPLACE +Replace existing record with the new one. + +@kwindex DBM_INSERT +@item DBM_INSERT +The existing record is left unchanged, and the function returns +@samp{1}. +@end table + +If no matching record exists in the database, new record will be +inserted no matter what the value of the @var{mode} is. +@end deftypefn + +@deftypefn {ndbm} int dbm_delete (DBM *@var{dbf}, datum @var{key}) +Deletes the record with the matching key from the database. If the +function succeeds, @samp{0} is returned. Otherwise, if no matching +record is found or if an error occurs, @samp{-1} is returned. +@end deftypefn + +@deftypefn {ndbm} datum dbm_firstkey (DBM *@var{dbf}) +Initializes iteration over the keys from the database and returns +the first key. Note, that the word @samp{first} does not imply any +specific ordering of the keys. + +If there are no records in the database, the @code{dptr} member of the +returned datum is @samp{NULL}. Otherwise, the @code{dptr} member of +the returned datum points to the memory managed by the compatibility +library. The application should never free it. +@end deftypefn + +@deftypefn {ndbm} datum dbm_nextkey (DBM *@var{dbf}) +Continues the iteration started by @code{dbm_firstkey}. Returns the +next key in the database. If the iteration covered all keys in the +database, the @code{dptr} member of the returned datum is @samp{NULL}. +Otherwise, the @code{dptr} member of the returned datum points to the +memory managed by the compatibility library. The application should +never free it. + +@cindex sequential access, using @samp{NDBM} +@cindex iteration loop, using @samp{NDBM} +The usual way of iterating over all the records in the database is: + +@example +for (key = dbm_firstkey (dbf); + key.ptr; + key = dbm_nextkey (dbf)) + @{ + /* do something with the key */ + @} +@end example + +The loop above should not try to delete any records from the database, +otherwise the iteration is not guaranteed to cover all the keys. +@xref{Sequential}, for a detailed discussion of this. +@end deftypefn + +@deftypefn {ndbm} int dbm_error (DBM *@var{dbf}) +Returns the error condition of the database: @samp{0} if no errors +occurred so far while manipulating the database, and a non-zero value +otherwise. +@end deftypefn + +@deftypefn {ndbm} void dbm_clearerr (DBM *@var{dbf}) +Clears the error condition of the database. +@end deftypefn + +@deftypefn {ndbm} int dbm_dirfno (DBM *@var{dbf}) +Returns the file descriptor of the @samp{dir} file of the database. +It is guaranteed to be different from the descriptor returned by +the @code{dbm_pagfno} function (see below). + +The application can lock this descriptor to serialize accesses to the +database. +@end deftypefn + +@deftypefn {ndbm} int dbm_pagfno (DBM *@var{dbf}) +Returns the file descriptor of the @samp{pag} file of the database. +See also @code{dbm_dirfno}. +@end deftypefn + +@deftypefn {ndbm} int dbm_rdonly (DBM *@var{dbf}) +Returns @samp{1} if the database @var{dbf} is open in a read-only mode +and @samp{0} otherwise. +@end deftypefn + +@node dbm +@section DBM interface functions. +@cindex DBM functions + +The functions below are provided for compatibility with the old +UNIX @samp{DBM} interface. Only one database at a time can be +manipulated using them. + +@deftypefn {dbm} int dbminit (char *@var{file}) +Opens a database. The @var{file} argument is the full name of the +database file to be opened. The function opens two files: +@file{@var{file}.pag} and @file{@var{file}.dir}. If any of +them does not exist, the function fails. It never attempts to create +the files. + +The database is opened in the read-write mode, if its disk permissions +permit. + +The application must ensure that the functions described below in +this section are called only after a successful call to @code{dbminit}. +@end deftypefn + +@deftypefn {dbm} int dbmclose (void) +Closes the database opened by an earlier call to @code{dbminit}. +@end deftypefn + +@deftypefn {dbm} datum fetch (datum @var{key}) +Reads a record from the database with the matching key. The @var{key} +argument supplies the key that is being looked for. + +If no matching record is found, the @code{dptr} member of the returned +datum is @samp{NULL}. Otherwise, the @code{dptr} member of the +returned datum points to the memory managed by the compatibility +library. The application should never free it. +@end deftypefn + +@deftypefn {dbm} int store (datum @var{key}, datum @var{content}) +Stores the key/value pair in the database. If a record with the +matching key already exists, its content will be replaced with the new +one. + +Returns @samp{0} on success and @samp{-1} on error. +@end deftypefn + +@deftypefn {dbm} int delete (datum @var{key}) +Deletes a record with the matching key. + +If the function succeeds, @samp{0} is returned. Otherwise, if no +matching record is found or if an error occurs, @samp{-1} is +returned. +@end deftypefn + +@deftypefn {dbm} datum firstkey (void) +Initializes iteration over the keys from the database and returns +the first key. Note, that the word @samp{first} does not imply any +specific ordering of the keys. + +If there are no records in the database, the @code{dptr} member of the +returned datum is @samp{NULL}. Otherwise, the @code{dptr} member of +the returned datum points to the memory managed by the compatibility +library. The application should never free it. +@end deftypefn + +@deftypefn {dbm} datum nextkey (datum @var{key}) +Continues the iteration started by a call to @code{firstkey}. Returns +the next key in the database. If the iteration covered all keys in the +database, the @code{dptr} member of the returned datum is @samp{NULL}. +Otherwise, the @code{dptr} member of the returned datum points to the +memory managed by the compatibility library. The application should +never free it. +@end deftypefn + +@node gdbmtool +@chapter Examine and modify a GDBM database. +@prindex gdbmtool + +The @command{gdbmtool} utility allows you to view and modify an +existing @acronym{GDBM} database or to create a new one. + +@cindex default database, @command{gdbmtool} +@flindex junk.gdbm +When invoked without arguments, it tries to open a database file called +@file{junk.gdbm}, located i