diff options
author | Sergey Poznyakoff <gray@gnu.org> | 2021-10-17 11:40:16 +0300 |
---|---|---|
committer | Sergey Poznyakoff <gray@gnu.org> | 2021-10-17 12:21:08 +0300 |
commit | 1733320d47df1d18d622e6b3565d3d6c51b9deeb (patch) | |
tree | 13b4027313ec3a9e3df13d8497616df7f89702ab /doc/gdbm.3 | |
parent | e3866a39dd09ebee2c891228d766661ce14d09c7 (diff) | |
download | gdbm-1733320d47df1d18d622e6b3565d3d6c51b9deeb.tar.gz gdbm-1733320d47df1d18d622e6b3565d3d6c51b9deeb.tar.bz2 |
Update the docs
* Makefile.am: Use plain git log to format the ChangeLog.
* git2chg.awk: Remove.
* NOTE-WARNING: Update.
* README: Likewise.
* README-alpha: Likewise.
* README-hacking: Likewise.
* doc/gdbm.3: Likewise.
* doc/gdbm.texi
Diffstat (limited to 'doc/gdbm.3')
-rw-r--r-- | doc/gdbm.3 | 1182 |
1 files changed, 911 insertions, 271 deletions
@@ -13,7 +13,7 @@ .\" .\" You should have received a copy of the GNU General Public License .\" along with GDBM. If not, see <http://www.gnu.org/licenses/>. */ -.TH GDBM 3 "July 31, 2021" "GDBM" "GDBM User Reference" +.TH GDBM 3 "October 17, 2021" "GDBM" "GDBM User Reference" .SH NAME GDBM \- The GNU database manager. Includes \fBdbm\fR and \fBndbm\fR compatibility. @@ -25,6 +25,8 @@ compatibility. .br .BI "extern char *" gdbm_version ; .br +.BI "extern int " gdbm_version[3] ; +.br .BI "GDBM_FILE gdbm_open (const char *" name ", int " block_size ", " .ti +21 .BI "int " flags ", int " mode ", " @@ -68,87 +70,52 @@ compatibility. .BI "int gdbm_failure_atomic (GDBM_FILE " dbf ", const char *" even ", const char *" odd ");" .br .BI "int gdbm_latest_snapshot (const char *" even ", const char *" odd ", const char **" result ");" -.PP -.SS DBM Compatibility routines: -.PP -.B #include <dbm.h> -.sp -.BI "int dbminit (const char *" name ");" -.br -.BI "int store (datum " key ", datum " content ); -.br -.BI "datum fetch (datum " key ); -.br -.BI "int delete (datum " key ); -.br -.BI "datum firstkey (void);" -.br -.BI "datum nextkey (datum " key ); -.br -.BI "int dbmclose (void);" -.PP -.SS NDBM Compatibility routines: -.PP -.B #include <ndbm.h> -.sp -.BI "DBM *dbm_open (const char *" name ", int " flags ", int " mode ); -.br -.BI "void dbm_close (DBM *" file ); -.br -.BI "datum dbm_fetch (DBM *" file ", datum " key ); -.br -.BI "int dbm_store (DBM *" file ", datum " key ", datum " content ", int " flags ); -.br -.BI "int dbm_delete (DBM *" file ", datum " key ); -.br -.BI "datum dbm_firstkey (DBM *" file ); -.br -.BI "datum dbm_nextkey (DBM *" file ", datum " key ); -.br -.BI "int dbm_error (DBM *" file ); -.br -.BI "int dbm_clearerr (DBM *" file ); -.br -.BI "int dbm_pagfno (DBM *" file ); -.br -.BI "int dbm_dirfno (DBM *" file ); -.br -.BI "int dbm_rdonly (DBM *" file ); -.SH DESCRIPTION -\fBGNU dbm\fR is a library of routines that manages data files that contain -key/data pairs. The access provided is that of storing, -retrieval, and deletion by key and a non-sorted traversal of all -keys. A process is allowed to use multiple data files at the -same time. - +.SH NOTICE This manpage is a short description of the \fBGDBM\fR library. -For a detailed discussion, including examples of the configuration and -usage recommendations, refer to the \fBGDBM Manual\fR available in +For a detailed discussion, including examples and usage +recommendations, refer to the \fBGDBM Manual\fR available in Texinfo format. To access it, run: \fBinfo gdbm\fR +The documentation is also available online at + + \fBhttps://www.gnu.org/software/gdbm/manual\fR + Should any discrepancies occur between this manpage and the \fBGDBM Manual\fR, the later shall be considered the authoritative source. - +.SH DESCRIPTION +\fBGNU dbm\fR is a library of routines that manages data files that contain +key/data pairs. The access provided is that of storing, +retrieval, and deletion by key and a non-sorted traversal of all +keys. A process is allowed to use multiple data files at the +same time. +.SS Opening a database A process that opens a gdbm file is designated as a "reader" or a "writer". Only one writer may open a gdbm file and many readers may open the file. Readers and writers can not open the gdbm file at the same time. The procedure for opening a gdbm file is: - +.PP .BI "GDBM_FILE gdbm_open (const char *" name ", int " block_size ", " .ti +21 .BI "int " flags ", int " mode ", " .ti +21 .BI "void (*" fatal_func ")(const char *))"; - +.PP \fIName\fR is the name of the file (the complete name, -gdbm does not append any characters to this name). \fIBlock_size\fR is -the size of a single transfer from disk to memory. This parameter is -ignored unless the file is a new file. The minimum size is 512. If -it is less than 512, dbm will use the stat block size for the file system. -\fIRead_write\fR can have one of the following values: +\fBgdbm\fR does not append any characters to this name). +.PP +\fIBlock_size\fR is the size of a single transfer from disk to +memory. If the value is less than 512, the file system block size is +used instead. The size is adjusted so that the block can hold exact +number of directory entries, so that the effective block size can be +slightly greater than requested. This adjustment is disabled if the +\fBGDBM_BSEXACT\fR \fIflag\fR is used. +.PP +The \fIflags\fR parameter is a bitmask, composed of the \fIaccess +mode\fR and one or more modifier flags. The \fIaccess mode\fR bit +designates the process as a reader or writer and must be one of the following: .TP .B GDBM_READER reader @@ -162,21 +129,37 @@ writer - if database does not exist create new one .B GDBM_NEWDB writer - create new database regardless if one exists .PP -The \fBGDBM_NOMMAP\fR added to \fIread_write\fR by bitwise or instructs -\fBgdbm_open\fR to disable the use of -.BR mmap (2). +Additional flags (\fImodifiers\fR) can be combined with these values +by bitwise \fBOR\fR. Not all of them are meaningful with all access +modes. .PP -For the last three (writers of the database) the following may be added -added to \fIread_write\fR by bitwise or: +Flags that are valid for any value of access mode are: .TP -.B GDBM_SYNC -Causes all database operations to be synchronized to the disk, +.B GDBM_CLOEXEC +Set the \fIclose-on-exec\fR flag on the database file descriptor. .TP .B GDBM_NOLOCK Prevents the library from performing any locking on the database file. .TP -.B GDBM_CLOEXEC -Set the close-on-exec flag on the database file descriptor. +.B GDBM_NOMMAP +Instructs \fBgdbm_open\fR to disable the use of +.BR mmap (2). +.TP +.B GDBM_PREREAD +When mapping GDBM file to memory, read its contents immediately, +instead of when needed (\fIprefault reading\fR). This can be +advantageous if you open a \fIread-only\fR database and are going to +do a lot of look-ups on it. In this case entire database will be +read at once and searches will operate on an in-memory copy. In +contrast, \fBGDBM_PREREAD\fR should not be used if you open a database +(even in read-only mode) only to retrieve a couple of keys. +.sp +Finally, never use \fBGDBM_PREREAD\fR when opening a database for +updates, especially for inserts: this will degrade performance. +.sp +This flag has no effect if \fBGDBM_NOMMAP\fR is given, or if the +operating system does not support prefault reading. It is known to +work on Linux and FreeBSD kernels. .TP .B GDBM_XVERIFY Enable additional consistency checks. With this flag, eventual @@ -184,123 +167,281 @@ corruptions of the database are discovered when opening it, instead of when a corrupted structure is read during normal operation. However, on large databases, it can slow down the opening process. .PP -The option +The following additional flags are valid when the database is opened +for writing (\fBGDBM_WRITER\fR, \fBGDBM_WRCREAT\fR, or +\fBGDBM_NEWDB\fR): +.TP +.B GDBM_SYNC +Causes all database operations to be synchronized to the disk. +.sp +\fBNOTE\fR: this option entails severe performance degradation and +does not necessarily ensure that the resulting database state is +consistent, therefore we discourage its use. For a discussion of how +to ensure database consistency with minimal performance overhead, see +.B CRASH TOLERANCE +below. +.TP .B GDBM_FAST -is now obsolete, since gdbm defaults to no-sync mode. +A reverse of \fBGDBM_SYNC\fR: synchronize writes only when needed. +This is the default. This flag is provided only for compatibility +with previous versions of GDBM. +.PP +The following flags can be used together with \fBGDBM_NEWDB\fR. They +also take effect when used with \fBGDBM_WRCREAT\fR, if the requested +database file doesn't exist: +.TP +.B GDBM_BSEXACT +If this flag is set and the requested \fIblock_size\fR value cannot +be used, \fBgdbm_open\fR will refuse to create the database. In this +case it will set the \fBgdbm_errno\fR variable to +\fBGDBM_BLOCK_SIZE_ERROR\fR and return \fBNULL\fR. +.sp +Without this flag, \fBgdbm_open\fR will silently adjust the +\fIblock_size\fR to a usable value, as described above. +.TP +.B GDBM_NUMSYNC +Create new database in \fIextended database format\fR, a format best +suited for effective crash recovery. For a detailed discussion, see +the +.B CRASH RECOVERY +chapter below. +.PP +\fIMode\fR is the file mode (see +.BR chmod (2) +and +.BR open (2)). +It is used if the file is created. +.PP +\fIFatal_func\fR is a function to be called when \fBgdbm\fR if +it encounters a fatal error. This parameter is deprecated and must +always be \fBNULL\fR. .PP -\fIMode\fR is the file mode (see \fBchmod(2)\fR and \fBopen(2)\fR) if the -file is created. \fI(*Fatal_func) ()\fR is a function for dbm to call -if it detects a fatal error. The only parameter of this function is a string. -If the value of 0 is provided, \fBgdbm\fR will use a default function. - The return value is the pointer needed by all other routines to -access that gdbm file. If the return is the \fBNULL\fR pointer, \fBgdbm_open\fR -was not successful. The errors can be found in \fIgdbm_errno\fR for gdbm -errors and in \fIerrno\fR for system errors. (For error codes, see -gdbmerrno.h.) - -In all of the following calls, the parameter \fIdbf\fR refers to the pointer -returned from \fBgdbm_open\fR. - -It is important that every file opened is also closed. This is needed to -update the reader/writer count on the file. This is done by: - +access that gdbm file. If the return is the \fBNULL\fR pointer, +\fBgdbm_open\fR was not successful. In this case, the reason of the +failure can be found in the \fIgdbm_errno\fR variable. If the +following call returns \fItrue\fR (non-zero value): +.sp +.nf +.in +5 + gdbm_check_syserr(gdbm_open) +.in +.fi +.PP +the system \fIerrno\fR variable must be examined in order to obtain more +detail about the failure. +.PP +.BI "GDBM_FILE gdbm_fd_open (int " FD ", const char *" name ", int " block_size ", " +.ti +21 +.BI "int " flags ", int " mode ", " +.ti +21 +.BI "void (*" fatal_func ")(const char *))"; +.PP +This is an alternative entry point to \fBgdbm_open\fR. \fIFD\fR is a +valid file descriptor obtained as a result of a call to +.BR open (2) +or +.BR creat (2). +The function opens (or creates) a \fGDBM\fR database this descriptor +refers to. The descriptor is not \fBdup\fR'ed, and will be closed +when the returned \fBGDBM_FILE\fR is closed. Use +.B dup (2) +if that is not desirable. +.PP +In case of error, the function behaves like \fBgdbm_open\fR and +\fBdoes not close\fR \fIFD\fR. This can be altered by the following +value passed in \fIflags\fR: +.TP +.B GDBM_CLOERROR +Close \fIFD\fR before exiting on error. +The rest of arguments are the same as for \fBgdbm_open\fR. +.SS Calling convention +.PP +All \fBGDBM\fR functions take as their first parameter the +\fIdatabase handle\fR (\fBGDBM_FILE\fR), returned from \fBgdbm_open\fR +or \fBgdbm_fd_open\fR. +.PP +Any value stored in the \fBGDBM\fR database is described by +\fIdatum\fR, an aggregate type defined as: +.sp +.nf +.in +5 +typedef struct +{ + char *dptr; + int dsize; +} datum; +.in +.fi +.PP +The \fIdptr\fR field points to the actual data. Its type is +\fBchar *\fR for historical reasons. Actually it should have been +typed +\fBvoid *\fR. Programmers are free to store data of arbitrary +complexity, both scalar and aggregate, in this field. +.PP +The \fIdsize\fR field contains the number of bytes stored in +\fBdptr\fR. +.PP +The \fBdatum\fR type is used to describe both \fIkeys\fR and +\fIcontent\fR (values) in the database. Values of this type can +be passed as arguments or returned from \fBGDBM\fR function calls. +.PP +\fBGDBM\fR functions that return \fBdatum\fR indicate failure by setting +its \fIdptr\fR field to \fBNULL\fR. +.PP +Functions returning integer value, indicate success by returning +0 and failure by returning a non-zero value (the only exception to this +rule is \fBgdbm_exists\fR, for which the return value is reversed). +.PP +If the returned value indicates failure, the \fBgdbm_errno\fR variable +contains an integer value indicating what went wrong. A similar value +is associated with the \fIdbf\fR handle and can be accessed using the +\fBgdbm_last_errno\fR function. Immediately after return from a +function, both values are exactly equal. Subsequent \fBGDBM\fR calls +with another \fIdbf\fR as argument may alter the value of the global +\fBgdbm_errno\fR, but the value returned by \fBgdbm_last_errno\fR will +always indicate the most recent code of an error that occurred for +\fIthat particular database\fR. Programmers are encouraged to use +such per-database error codes. +.PP +Sometimes the actual reason of the failure can be clarified by +examining the system \fBerrno\fR value. To make sure its value is +meaningful for a given \fBGDBM\fR error code, use the +\fBgdbm_check_syserr\fR function. The function takes error code as +argument and returns 1 if the \fBerrno\fR is meaningful for that +error, or 0 if it is irrelevant. +.PP +Similarly to \fBgdbm_errno\fR, the latest \fBerrno\fR value associated +with a particular database can be obtained using the +\fBgdbm_last_syserr\fR function. +.PP +The \fBgdbm_clear_error\fR clears the error indicator (both \fBGDBM\fR +and system error codes) associated with a database handle. +.PP +Some critical errors leave the database in a \fIstructurally +inconsistent state\fR. If that happens, all subsequent \fBGDBM\fR calls +accessing that database will fail with the \fBGDBM\fR error code of +\fBGDBM_NEED_RECOVERY\fR (a special function \fBgdbm_needs_recovery\fR +is also provided, which returns true if the database handle given as +its argument is structurally inconsistent). To return such +databases to consistent state, use the \fBgdbm_recover\fR function +(see below). +.PP +The \fBGDBM_NEED_RECOVERY\fR error cannot be cleared using +\fBgdbm_clear_error\fR. +.SS Error functions +This section describes the error handling functions outlined above. +.TP +.BI "gdbm_error gdbm_last_errno (GDBM_FILE " dbf ")" +Returns the error code of the most recent failure encountered when operating +on \fIdbf\fR. +.TP +.BI "int gdbm_last_syserr (GDBM_FILE " dbf ")" +Returns the value of the system \fBerrno\fR variable associated with +the most recent failure that occurred on \fIdbf\fR. +.sp +Notice that not all \fBgdbm_error\fR codes have a relevant system +error code. Use the following function to determine if a given code has. +.TP +.BI "int gdbm_check_syserr (gdbm_error " err ")" +Returns \fB1\fR, if system \fBerrno\fR value should be checked to get more +info on the error described by GDBM code \fIerr\fR. +.TP +.BI "void gdbm_clear_error (GDBM_FILE " dbf ")" +Clears the error state for the database \fIdbf\fR. This function is +called implicitly upon entry to any GDBM function that operates on +\fBGDBM_FILE\fR. +.sp +The \fBGDBM_NEED_RECOVERY\fR error cannot be cleared. +.TP +.BI "int gdbm_needs_recovery (GDBM_FILE " dbf ")" +Return \fB1\fR if the database file \fIdbf\fR is in inconsistent state +and needs recovery. +.TP +.BI "const char *gdbm_strerror (gdbm_error " err ")" +Returns a textual description of the error code \fIerr\fR. +.TP +.BI "const char *gdbm_db_strerror (GDBM_FILE " dbf ")" +Returns a textual description of the recent error in database +\fIdbf\fR. This description includes the system \fBerrno\fR value, if +relevant. +.SS Closing the database +It is important that every database file opened is also closed. This +is needed to update the reader/writer count on the file. This is done by: +.TP .BI "int gdbm_close (GDBM_FILE " dbf ");" - -The database is used by 3 primary routines. The first stores data in the -database. - -.BI "int gdbm_store (GDBM_FILE " dbf ", datum " key ", datum " content ", int " flag ); - -\fIDbf\fR is the pointer returned by \fBgdbm_open\fR. \fIKey\fR is the -key data. \fIContent\fR is the data to be associated with the \fIkey\fR. -\fIFlag\fR can have one of the following values: +.SS Database lookups .TP -.B GDBM_INSERT -Insert only, generate an error if key exists; +.BI "int gdbm_exists (GDBM_FILE " dbf ", datum " key ); +If the \fIkey\fR is found within the database, the return value +will be \fItrue\fR (\fB1\fR). If nothing appropriate is found, \fIfalse\fR +(\fB0\fR) is returned and \fBgdbm_errno\fR set to \fBGDBM_NO_ERROR\fR. +.sp +On error, returns 0 and sets \fBgdbm_errno\fR. .TP -.B GDBM_REPLACE -Replace contents if key exists. -.PP -If a reader calls \fBgdbm_store\fR, the return value will be \-1. -If called with \fBGDBM_INSERT\fR and \fIkey\fR is in the database, the return -value will be 1. Otherwise, the return value is 0. - -\fINOTICE: If you store data for a key that is already in the data base, -\fBgdbm\fI replaces the old data with the new data if called with \fBGDBM_REPLACE\fI. -You do not get two data items for the same key and you do not get an -error from \fBgdbm_store\fI. - -NOTICE: The size in \fBgdbm\fI is not restricted like in \fBdbm\fI or \fBndbm\fI. Your data -can be as large as you want.\fR - -To search for some data, use: - .BI "datum gdbm_fetch (GDBM_FILE " dbf ", datum " key ); - \fIDbf\fR is the pointer returned by \fBgdbm_open\fR. \fIKey\fR is the key data. - +.sp If the \fIdptr\fR element of the return value is \fBNULL\fR, the \fBgdbm_errno\fR variable should be examined. The value of \fBGDBM_ITEM_NOT_FOUND\fR means no data was found for that \fIkey\fR. Other value means an error occurred. - +.sp Otherwise the return value is a pointer to the found data. The storage space for the \fIdptr\fR element is allocated using -\fBmalloc(3)\fR. \fBGdbm\fI does not automatically free this data. +\fBmalloc(3)\fR. \fBGDBM\fR does not automatically free this data. It is the programmer's responsibility to free this storage when it is no longer needed. - -To search for some data, without retrieving it: - -.BI "int gdbm_exists (GDBM_FILE " dbf ", datum " key ); - -\fIDbf\fR is the pointer returned by \fBgdbm_open\fR. \fIKey\fR is -the key data to search for. - -If the \fIkey\fR is found within the database, the return value -will be true. If nothing appropriate is found, false is returned. -This routine is useful for checking for the existence of a record, -without performing the memory allocation done by \fBgdbm_fetch\fR. -.PP -To remove some data from the database: - -.BI "int gdbm_delete (GDBM_FILE " dbf ", datum " key ); - -\fIDbf\fR is the pointer returned by \fBgdbm_open\fR. \fIKey\fR is the -key data. - -The return value is \-1 if the item is not present or the requester is a reader. -The return value is 0 if there was a successful delete. - -The next two routines allow for accessing all items in the database. This -access is not key sequential, but it is guaranteed to visit every key in -the database once. (The order has to do with the hash values.) - +.SS Iterating over the database +The following two routines allow for iterating over all items in the +database. Such iteration is not key sequential, but it is +guaranteed to visit every key in the database exactly once. (The +order has to do with the hash values.) +.TP .BI "datum gdbm_firstkey (GDBM_FILE " dbf ");" -.br +Returns first key in the database. +.TP .BI "datum gdbm_nextkey (GDBM_FILE " dbf ", datum " key ); - -\fIDbf\fR is the pointer returned by \fBgdbm_open\fR. \fIKey\fR is the -key data. - -The return values are both of type \fBdatum\fR. If the \fIdptr\fR -element of the return value is \fBNULL\fR, inspect the -\fBgdbm_errno\fR. If it is \fBGDBM_ITEM_NOT_FOUND\fR, there is no -first key or next key. Otherwise, an error occurred. - -Again, notice that \fIdptr\fR points to data allocated by \fBmalloc(3)\fR -and \fBgdbm\fR will not free it for you. - -These functions were intended to visit the database in read-only algorithms, -for instance, to validate the database or similar operations. - -File `visiting' is based on a `hash table'. \fIgdbm_delete\fR re-arranges the -hash table to make sure that any collisions in the table do not leave some item -`un-findable'. The original key order is NOT guaranteed to remain unchanged in -ALL instances. It is possible that some key will not be visited if a loop like -the following is executed: +Given a \fIkey\fR, returns the database key that follows it. End of +iteration is marked by returning \fIdatum\fR with \fIdptr\fR field set +to \fBNULL\fR and setting the \fBgdbm_errno\fR value to +\fBGDBM_ITEM_NOT_FOUND\fR. +.PP +After successful return from both functions, \fIdptr\fR points to data +allocated by +.BR malloc (3). +It is the caller responsibility to free the data when no longer +needed. +.PP +A typical iteration loop looks like: +.sp +.nf +.in +5 +datum key, nextkey, content; +key = gdbm_firstkey (dbf); +while (key.dptr) + { + content = gdbm_fetch (dbf, key); + /* Do something with key and/or content */ + nextkey = gdbm_nextkey (dbf, key); + free (key.dptr); + key = nextkey; + } +.in +.fi +.PP +These functions are intended to visit the database in read-only +algorithms. Avoid any database modifications within the iteration loop. +File \fIvisiting\fR is based on a hash table. The \fBgdbm_delete\fR and, +in most cases, \fBgdbm_store\fR, functions rearrange the hash table to +make sure that any collisions in the table do not leave some item +`un-findable'. Thus, a call to either of these functions changes +the order in which the keys are ordered. Therefore, these functions +should not be used when iterating over all the keys in the database. +For example, the following loop is wrong: it is possible that some keys +will not be visited or will be visited twice if it is executed: .sp .nf .in +5 @@ -315,131 +456,282 @@ while (key.dptr) } .in .fi +.SS Updating the database +.TP +.BI "int gdbm_store (GDBM_FILE " dbf ", datum " key ", datum " content ", int " flag ); +\fIDbf\fR is the pointer returned by \fBgdbm_open\fR. \fIKey\fR is the +key data. \fIContent\fR is the data to be associated with the \fIkey\fR. +\fIFlag\fR can have one of the following values: +.RS 4 +.TP +.B GDBM_INSERT +Insert only, generate an error if key exists; +.TP +.B GDBM_REPLACE +Replace contents if key exists. +.RE +.IP +The function returns 0 on success and \-1 on failure. If the key +already exists in the database and the \fIflag\fR is +\fBGDBM_INSERT\fR, the function does not modify the database. It sets +\fBgdbm_errno\fR to \fBGDBM_CANNOT_REPLACE\fR and returns 1. +.TP +.BI "int gdbm_delete (GDBM_FILE " dbf ", datum " key ); +Looks up and deletes the given \fIkey\fR from the database \fIdbf\fR. +.sp +The return value is 0 if there was a successful delete or \-1 on +error. In the latter case, the \fBgdbm_errno\fR value +\fBGDBM_ITEM_NOT_FOUND\fR indicates that the key is not present in the +database. Other \fBgdbm_errno\fR values indicate failure. +.SS Recovering structural consistency +If a function leaves the database in structurally inconsistent state, +it can be recovered using the \fBgdbm_recover\fR function. +.TP +.BI "int gdbm_recover (GDBM_FILE " dbf ", gdbm_recovery * " rcvr ", int " flags ")" +Check the database file DBF and fix eventual inconsistencies. The +\fIrcvr\fR argument can be used both to control the recovery and to +return additional statistics about the process, as indicated by +\fIflags\fR. For a detailed discussion of these arguments and their +usage, see the \fBGDBM Manual\fR, chapter \fBRecovering structural +consistency\fR. +.sp +You can pass \fBNULL\fR as \fIrcvr\fR and \fB0\fR as \fIflags\fR, if +no such control is needed. +.sp +By default, this function first checks the database for +inconsistencies and attempts recovery only if some were found. The +special \fIflags\fR bit \fBGDBM_RCVR_FORCE\fR instructs +\fBgdbm_recovery\fR to skip this check and to perform database +recovery unconditionally. +.SS Export and import +\fBGDBM\fR database files can be exported (dumped) to so called \fIflat +files\fR or imported (loaded) from them. A flat file contains exactly +the same data as the original database, but it cannot be used for +searches or updates. Its purpose is to keep the data from the +database for restoring it when the need arrives. As such, flat files +are used for backup purposes, and for sending databases over the wire. .PP -The following routine should be used very infrequently. - -.BI "int gdbm_reorganize (GDBM_FILE " dbf ");" +As of \fBGDBM\fR version 1.21, there are two flat file formats. The +\fBASCII\fR 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. +This is the preferred format. +.PP +Another flat file format is the \fBbinary\fR format. It stores only +key/data pairs and does not keep information about the database file +itself. It cannot be used to copy databases between different +architectures. The binary format was introduced in \fBGDBM\fR version +1.9.1 and is retained mainly for backward compatibility. +.PP +The following functions are used to export or import \fBGDBM\fR +database files. +.TP +.BI "int gdbm_dump (GDBM_FILE " dbf ", const char *" filename "," +.PD 0 +.TP +.ti +15 +.BI "int " format ", int " open_flag ", int " mode ")" +.PD +Dumps the database file \fIdbf\fR to the file \fIfilename\fR in +requested \fIformat\fR. Allowed values for \fIformat\fR are: +.BR GDBM_DUMP_FMT_ASCII , +to create an ASCII dump file, and +.BR GDBM_DUMP_FMT_BINARY , +to create a binary dump. -If you have had a lot of deletions and would like to shrink the space -used by the \fBgdbm\fR file, this routine will reorganize the database. -\fBGdbm\fR will not shorten the length of a \fBgdbm\fR file except by -using this reorganization. (Deleted file space will be reused.) +The value of \fIopen_flag\fR tells \fBgdbm_dump\fR what to do if +\fIfilename\fR already exists. If it is \fBGDBM_NEWDB\fR, the +function will create a new output file, replacing it if it already +exists. If its value is \fBGDBM_WRCREAT\fR, the file will be created +if it does not exist. If it does exist, \fBgdbm_dump\fR will return +error. -Unless your database was opened with the \fBGDBM_SYNC\fR flag, \fBgdbm\fR does not -wait for writes to be flushed to the disk before continuing. -The following routine can be used to guarantee that the database is -physically written to the disk file. +The file mode to use when creating the output file is defined by the +\fImode\fR parameter. Its meaning is the same as for +.BR open (2). +.TP +.BI "int gdbm_load (GDBM_FILE *" pdbf ", const char *" filename "," +.PD 0 +.TP +.ti +15 +.BI "int " flag ", int " meta_mask ", unsigned long *" errline ")" +.PD +Loads data from the dump file \fIfilename\fR into the database pointed +to by \fIpdbf\fR. If \fIpdbf\fR is \fBNULL\fR, the function will try +to create a new database. On success, the new \fBGDBM_FILE\fR object +will be stored in the memory location pointed to by \fIpdbf\fR. If +the dump file carries no information about the original database file +name, the function will set \fBgdbm_errno\fR to \fBGDBM_NO_DBNAME\fR +and return -1, indicating failure. -.BI "int gdbm_sync (GDBM_FILE " dbf ");" +Otherwise, if \fIpdbf\fR points to an already open \fBGDBM_FILE\fR, +the function will load data from \fIfilename\fR into that database. +The \fIflag\fR parameter controls the function behavior if a key +from the dump file already exists in the database. See the +\fBgdbm_store\fR function for its possible values. + +The \fImeta_mask\fR parameter 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: +.RS +4 +.TP +.B GDBM_META_MASK_MODE +Do not restore file mode. +.TP +.B GDBM_META_MASK_OWNER +Do not restore file owner. +.RE +.SS Other functions +.TP +.BI "int gdbm_reorganize (GDBM_FILE " dbf ");" +If you have had a lot of deletions and would like to shrink the space +used by the \fBGDBM\fR file, this routine will reorganize the +database. +.TP +.BI "int gdbm_sync (GDBM_FILE " dbf ");" +Synchronizes the changes in \fIdbf\fR with its disk file. +.sp It will not return until the disk file state is synchronized with the in-memory state of the database. +.TP +.BI "int gdbm_setopt (GDBM_FILE " dbf ", int " option ", void *" value ", int " size ); +Query or change some parameter of an already opened database. The +\fIoption\fR argument defines what parameter to set or retrieve. If +the \fIset\fR operation is requested, \fIvalue\fR points to the new +value. Its actual data type depends on \fIoption\fR. If the +\fIget\fR operation is requested, \fIvalue\fR points to a memory +region where to store the return value. In both cases, \fIsize\fR +contains the actual size of the memory pointed to by \fIvalue\fR. +.sp +Possible values of \fIoption\fR are: +.RS +4 +.TP +.B GDBM_SETCACHESIZE +.TQ +.B GDBM_CACHESIZE +Set the size of the internal bucket cache. The \fIvalue\fR should +point to a \fBsize_t\fR holding the desired cache size, or the +constant \fBGDBM_CACHE_AUTO\fR, to select the best cache size +automatically. -To convert a \fBgdbm\fR error code into English text, use this routine: - -.BI "const char *gdbm_strerror (gdbm_error " errno ); - -\fBGdbm\fR now supports the ability to set certain options on an -already open database. - -.BI "int gdbm_setopt (GDBM_FILE " dbf ", int " option ", int " value ", int " size ); +By default, a newly open database is configured to adapt the cache +size to the number of index buckets in the database file. This +provides for the best performance. -Where \fIdbf\fR is the return value from a previous call to \fBgdbm_open\fR, -and \fIoption\fR specifies which option to set. The valid options are -currently: +Use this option if you wish to limit the memory usage at the expense +of performance. If you chose to do so, please bear in mind that cache +becomes effective when its size is greater then 2/3 of the number of +index bucket counts in the database. The best performance results are +achieved when cache size equals the number of buckets. .TP -.B GDBM_CACHESIZE -Set the size of the internal bucket cache. By default, the cache size -is selected to provide for the optimal performance. Use this option, -if you wish to limit the memory usage at the expense of performance. -.sp -Use the -.B GDBM_CACHE_AUTO -constant to return to the default. +.B GDBM_GETCACHESIZE +Return the size of the internal bucket cache. The \fIvalue\fR should +point to a \fBsize_t\fR variable, where the size will be stored. +.TP +.B GDBM_GETFLAGS +Return the flags describing current state of the database. The +\fIvalue\fR should point to an \fBint\fR variable where to store the +flags. On success, its value will be similar to the flags used when +opening the database, except that it will reflect the current state +(which may have been altered by another calls to \fBgdbm_setopt\fR). .TP .B GDBM_FASTMODE - Set \fBfast mode\fR to either on or off. This allows \fBfast mode\fR to -be toggled on an already open and active database. \fIvalue\fR (see below) -should be set to either TRUE or FALSE. \fIThis option is now obsolete.\fR +Enable or disable the \fIfast writes mode\fR, similar to the +\fBGDBM_FAST\fR option to \fBgdbm_open\fR. + +This option is retained for compatibility with previous versions of +\fBGDBM\fR. .TP +.B GDBM_SETSYNCMODE +.TQ .B GDBM_SYNCMODE -Turn on or off file system synchronization operations. This setting defaults -to off; \fIvalue\fR (see below) should be set to either TRUE or FALSE. +Turn on or off immediate disk synchronization after updates. The +\fIvalue\fR should point to an integer: 1 to turn synchronization on, +and 0 to turn it off. + +\fBNOTE\fR: setting this option entails severe performance degradation +and does not necessarily ensure that the resulting database state is +consistent, therefore we discourage its use. For a discussion of how +to ensure database consistency with minimal performance overhead, see +.B CRASH TOLERANCE +below. +.TP +.B GDBM_GETSYNCMODE +Return the current synchronization status. The \fIvalue\fR should +point to an \fBint\fR where the status will be stored. .TP +.B GDBM_SETCENTFREE +.TQ .B GDBM_CENTFREE -Set \fBcentral free block pool\fR to either on or off. -The default is off, which is how previous versions of \fBGdbm\fR -handled free blocks. If set, this option causes all subsequent free -blocks to be placed in the \fBglobal\fR pool, allowing (in thoery) -more file space to be reused more quickly. \fIvalue\fR (see below) should -be set to either TRUE or FALSE. -\fINOTICE: This feature is still under study.\fR +Enable or disable central free block pool. The default is off, +which is how previous versions of \fBGDBM\fR handled free blocks. If +set, this option causes all subsequent free blocks to be placed in the +\fIglobal\fR pool, allowing (in theory) more file space to be reused +more quickly. The \fIvalue\fR should point to an integer: \fBTRUE\fR to +turn central block pool on, and \fBFALSE\fR to turn it off. + +The \fBGDBM_CENTFREE\fR alias is provided for compatibility with +earlier versions. .TP +.B GDBM_SETCOALESCEBLKS +.TQ .B GDBM_COALESCEBLKS -Set \fBfree block merging\fR to either on or off. -The default is off, which is how previous versions of \fBGdbm\fR -handled free blocks. If set, this option causes adjacent free blocks -to be merged. This can become a CPU expensive process with time, though, -especially if used in conjunction with \fBGDBM_CENTFREE\fR. \fIvalue\fR -(see below) should be set to either TRUE or FALSE. -\fINOTICE: This feature is still under study.\fR -.PP -\fIvalue\fR is the value to set \fIoption\fR to, specified as an integer -pointer. \fIsize\fR is the size of the data pointed to by \fIvalue\fR. -The return value will be \-1 upon failure, or 0 upon success. The global -variable \fIgdbm_errno\fR will be set upon failure. - -For instance, to set a database to use a cache of 10, after opening it -with \fBgdbm_open\fR, but prior to accessing it in any way, the following -code could be used: -.sp -.nf -.in +5 -int value = 10; - -ret = gdbm_setopt( dbf, GDBM_CACHESIZE, &value, sizeof(int)); -.in -.fi -.PP -If the database was opened with the \fBGDBM_NOLOCK\fR flag, the user may -wish 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 \fIgdbm_fdesc\fR routine is provided. - +Set free block merging to either on or off. The default is off, which +is how previous versions of \fBGDBM\fR handled free blocks. If set, +this option causes adjacent free blocks to be merged. This can become +a CPU expensive process with time, though, especially if used in +conjunction with \fBGDBM_CENTFREE\fR. The \fIvalue\fR should point +to an integer: \fBTRUE\fR to turn free block merging on, and \fBFALSE\fR to +turn it off. +.TP +.B GDBM_GETCOALESCEBLKS +Return the current status of free block merging. The \fIvalue\fR should +point to an \fBint\fR where the status will be stored. +.TP +.B GDBM_SETMAXMAPSIZE +Sets maximum size of a memory mapped region. The \fIvalue\fR should +point to a value of type \fBsize_t\fR, \fBunsigned long\fR or +\fBunsigned\fR. The actual value is rounded to the nearest page +boundary (the page size is obtained from \fBsysconf(_SC_PAGESIZE)\fR). +.TP +.B GDBM_GETMAXMAPSIZE +Return the maximum size of a memory mapped region. The \fIvalue\fR should +point to a value of type \fBsize_t\fR where to return the data. +.TP +.B GDBM_SETMMAP +Enable or disable memory mapping mode. The \fIvalue\fR should point +to an integer: \fBTRUE\fR to enable memory mapping or \fBFALSE\fR to +disable it. +.TP +.B GDBM_GETMMAP +Check whether memory mapping is enabled. The \fIvalue\fR should point +to an integer where to return the status. +.TP +.B GDBM_GETDBNAME +Return the name of the database disk file. The \fIvalue\fR should +point to a variable of type \fBchar**\fR. 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. +.TP +.B GDBM_GETBLOCKSIZE +Return the block size in bytes. The \fIvalue\fR should point to \fBint\fR. +.RE +.TP .BI "int gdbm_fdesc (GDBM_FILE " dbf ); - -Where \fIdbf\fR is the return value from a previous call to \fBgdbm_open\fR. -The return value will be the file descriptor of the database. - -The following two external variables may be useful: - -\fIgdbm_errno\fR is the variable that contains more information about -gdbm errors. (gdbm.h has the definitions of the error values and -defines gdbm_errno as an external variable.) - -\fIgdbm_version\fR is the string containing the version information. - -There are a few more things of interest. First, \fBgdbm\fR files are -not "sparse". You can copy them with the UNIX \fBcp(1)\fR command and -they will not expand in the copying process. Also, there is a -compatibility mode for use with programs that already use UNIX -\fBdbm\fR. In this compatibility mode, no \fRgdbm\fR file pointer is -required by the programmer, and only one file may be opened at a time. -All users in compatibility mode are assumed to be writers. If the -\fBgdbm\fR file is a read only, it will fail as a writer, but will -also try to open it as a |