diff options
author | Sergey Poznyakoff <gray@gnu.org.ua> | 2016-07-07 22:27:47 +0300 |
---|---|---|
committer | Sergey Poznyakoff <gray@gnu.org.ua> | 2016-07-07 22:27:47 +0300 |
commit | 295a4f5dc8197b7bf7c5f2d023fb940dbc6d4ab8 (patch) | |
tree | fb43640973378024bb8dedae5b6b2d1ef93dc0f2 /doc/gdbm.texinfo | |
parent | 478e6eb666648a9e28f5e5706bf73a47599beeec (diff) | |
download | gdbm-295a4f5dc8197b7bf7c5f2d023fb940dbc6d4ab8.tar.gz gdbm-295a4f5dc8197b7bf7c5f2d023fb940dbc6d4ab8.tar.bz2 |
Switch to Git repository
Diffstat (limited to 'doc/gdbm.texinfo')
-rw-r--r-- | doc/gdbm.texinfo | 2567 |
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 |