aboutsummaryrefslogtreecommitdiff
path: root/doc/gdbm.texinfo
diff options
context:
space:
mode:
authorSergey Poznyakoff <gray@gnu.org.ua>2016-07-07 22:27:47 +0300
committerSergey Poznyakoff <gray@gnu.org.ua>2016-07-07 22:27:47 +0300
commit295a4f5dc8197b7bf7c5f2d023fb940dbc6d4ab8 (patch)
treefb43640973378024bb8dedae5b6b2d1ef93dc0f2 /doc/gdbm.texinfo
parent478e6eb666648a9e28f5e5706bf73a47599beeec (diff)
downloadgdbm-295a4f5dc8197b7bf7c5f2d023fb940dbc6d4ab8.tar.gz
gdbm-295a4f5dc8197b7bf7c5f2d023fb940dbc6d4ab8.tar.bz2
Switch to Git repository
Diffstat (limited to 'doc/gdbm.texinfo')
-rw-r--r--doc/gdbm.texinfo2567
1 files changed, 0 insertions, 2567 deletions
diff --git a/doc/gdbm.texinfo b/doc/gdbm.texinfo
deleted file mode 100644
index 6322a9b..0000000
--- a/doc/gdbm.texinfo
+++ /dev/null
@@ -1,2567 +0,0 @@
-\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