diff options
Diffstat (limited to 'doc/gdbm.texi')
| -rw-r--r-- | doc/gdbm.texi | 462 |
1 files changed, 293 insertions, 169 deletions
diff --git a/doc/gdbm.texi b/doc/gdbm.texi index 9c679ca..5f42ced 100644 --- a/doc/gdbm.texi +++ b/doc/gdbm.texi @@ -69,5 +69,5 @@ Documentation License.'' @center Edition @value{EDITION} @sp 1 -@center for GNU @code{dbm}, Version @value{VERSION} +@center for GNU @command{dbm}, Version @value{VERSION} @page @vskip 0pt plus 1filll @@ -86,6 +86,6 @@ Documentation License.'' @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} +GNU @command{dbm} is a library of functions implementing a hashed database +on a disk file. This manual documents GNU @command{dbm} Version @value{VERSION} (@code{gdbm}). The software was originally written by Philip A.@: Nelson. This document was originally written by Pierre Gaumond from @@ -116,5 +116,5 @@ Functions: * Locking:: File locking. * Variables:: Useful global variables. - +* Additional functions:: * Error codes:: Error codes returned by @code{gdbm} calls. * Compatibility:: Compatibility with UNIX dbm and ndbm. @@ -144,6 +144,6 @@ Other topics: @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 +it and free to redistribute it on a free basis. GNU @command{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 @@ -177,8 +177,8 @@ the distribution of @code{gdbm}. @node Intro -@chapter Introduction to GNU @code{dbm}. +@chapter Introduction to GNU @command{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} +GNU @command{dbm} (@code{gdbm}) is a library of database functions that use +extensible hashing and works similar to the standard UNIX @command{dbm} functions. These routines are provided to a programmer needing to create and manipulate a hashed database. (@code{gdbm} is @emph{NOT} a @@ -345,5 +345,5 @@ no such key @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 *)) + int @var{flags}, int @var{mode}, void (*@var{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 @@ -364,7 +364,7 @@ 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. However, if the -@samp{GDBM_BSEXACT} flag is set and the size needs to be adjusted, the -function will return with error status, setting the @samp{gdbm_errno} -variable to @samp{GDBM_BLOCK_SIZE_ERROR}. +@code{GDBM_BSEXACT} flag is set and the size needs to be adjusted, the +function will return with error status, setting the @code{gdbm_errno} +variable to @code{GDBM_BLOCK_SIZE_ERROR}. @item flags @@ -373,12 +373,12 @@ variable to @samp{GDBM_BLOCK_SIZE_ERROR}. @kwindex GDBM_WRCREAT @kwindex GDBM_NEWDB -If @code{flags} is set to @samp{GDBM_READER}, the user wants to just read the +If @code{flags} is set to @code{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 +set to @code{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 +to @code{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 +@code{flags} is set to @code{GDBM_NEWDB}, the user want a new database created, regardless of whether one existed, and wants read and write access to the new database. @@ -387,36 +387,66 @@ access to the new database. @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. +The following constants may also be logically or'd into the database +flags: + +@table @code +@kwindex GDBM_SYNC +@item GDBM_SYNC +Synchronize all database operations to disk immediately. This +provides for the best database consistency at the expense of severe +performance degradation. + +@kwindex GDBM_FAST +@item GDBM_FAST +A reverse of @code{GDBM_SYNC}. Synchronize writes only when needed. +This is the default. The flag is provided for compatibility with +previous versions of @command{GDBM}. + +@kwindex GDBM_NOLOCK +@item GDBM_NOLOCK +Don't lock the database file. Use this flag if you intend to do +locking separately. + +@kwindex GDBM_NOMMAP +@item GDBM_NOMMAP +Disable memory mapping mechanism. This degrades performance. @kwindex GDBM_BSEXACT +@item GDBM_BSEXACT If this flag is set and the requested @var{block_size} cannot be used without adjustment, @code{gdbm_open} will refuse to create the -databases. In this case it will set the @samp{gdbm_errno} -variable to @samp{GDBM_BLOCK_SIZE_ERROR} and return @samp{NULL}. +databases. In this case it will set the @code{gdbm_errno} +variable to @code{GDBM_BLOCK_SIZE_ERROR} and return @code{NULL}. @kwindex GDBM_CLOEXEC @cindex close-on-exec -If the host @samp{open} call +@item GDBM_CLOEXEC +Set the close-on-exec flag on the database file descriptor. The +@code{libc} must support the @code{O_CLOEXEC} flag@footnote{ @ifhtml (@uref{http://www.manpagez.com/man/2/open, open(2)}) @end ifhtml @ifnothtml -(@pxref{open,,,open(2),open(2) man page}) +@xref{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. +} + +@kwindex GDBM_XVERIFY +@item GDBM_XVERIFY +Enable additional consistency checks. With this flag, eventual +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. + +@xref{Additional functions}. +@end table + @item mode -File mode (see +File mode@footnote{See @ifhtml @uref{http://www.manpagez.com/man/2/chmod, chmod(2)}, @end ifhtml @ifnothtml -@ref{chmod,,change permissions of a file,chmod(2), +@xref{chmod,,change permissions of a file,chmod(2), chmod(2) man page}, @end ifnothtml @@ -426,15 +456,15 @@ and @end ifhtml @ifnothtml -@pxref{open,,open a file,open(2), open(2) man page}), +@ref{open,,open a file,open(2), open(2) man page}.}, @end ifnothtml -which is used if the file is created). +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 +parameter of this function is a string. If the value of @code{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, +access that @code{gdbm} file. If the return is the @code{NULL} pointer, @code{gdbm_open} was not successful. The errors can be found in @code{gdbm_errno} variable (@pxref{Variables, gdbm_errno}). Available @@ -447,5 +477,5 @@ returned from @code{gdbm_open}. @deftypefn {gdbm interface} GDBM_FILE gdbm_fd_open (int @var{fd},@ const char *@var{name}, int @var{block_size}, @ - int @var{flags}, int @var{mode}, void (*fatal_func)(const char *)) + int @var{flags}, int @var{mode}, void (*@var{fatal_func})(const char *)) Alternative function for opening a GDBM database. The @var{fd} @@ -524,6 +554,6 @@ The data to be associated with the key. @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} +@code{GDBM_REPLACE} (defined in @file{gdbm.h}) asks that the old data +be replaced by the new @var{content}. The value @code{GDBM_INSERT} asks that an error be returned and no action taken if the @var{key} already exists. @@ -539,12 +569,12 @@ database. 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. +@code{NULL} @code{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 +Both @var{key} and @var{content} must have the @code{dptr} field be a +non-@code{NULL} value. Since a @code{NULL} @code{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. +@code{GDBM_INSERT} and the @var{key} was already in the database. @end table @end deftypefn @@ -552,5 +582,5 @@ The item was not stored because the argument @var{flag} was 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{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}. @@ -567,11 +597,11 @@ value for an object of type @code{int} (type of the @code{dsize} member of @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 +The @code{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}, inspect the value of the +If the @code{dptr} is @code{NULL}, inspect the value of the @code{gdbm_errno} variable (@pxref{Variables,gdbm_errno}). If it is -@samp{GDBM_ITEM_NOT_FOUND}, no data was found. Any other value means an +@code{GDBM_ITEM_NOT_FOUND}, no data was found. Any other value means an error occurred. Use @code{gdbm_strerror} function to convert @code{gdbm_errno} to a human-readable string. @@ -607,10 +637,10 @@ You may also search for a particular key without retrieving it: Checks whether the @var{key} exists in the database @var{dbf}. -If @var{key} is found, returns @samp{true} (@samp{1}). If it is not -found, returns @samp{false} (@samp{0}) and sets @code{gdbm_errno} to -@samp{GDBM_NO_ERROR} (@samp{0}). +If @var{key} is found, returns @code{true} (@code{1}). If it is not +found, returns @code{false} (@code{0}) and sets @code{gdbm_errno} to +@code{GDBM_NO_ERROR} (@code{0}). -On error, returns @samp{0} and sets @code{gdbm_errno} to a -non-@samp{0} error code. +On error, returns @code{0} and sets @code{gdbm_errno} to a +non-@code{0} error code. The parameters are: @@ -645,6 +675,6 @@ 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. +The function returns @code{-1} if the item is not present or the +requester is a reader. The return of @code{0} marks a successful delete. @end deftypefn @@ -664,11 +694,11 @@ access is not @code{key} sequential, but it is guaranteed to visit every @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}, inspect the +value is the first key accessed in the database. If the @code{dptr} +field in the returned datum is @code{NULL}, inspect the @code{gdbm_errno} variable (@pxref{Variables, gdbm_errno}). The value of @code{GDBM_ITEM_NOT_FOUND} means that the database contains no data. Other value means an error occurred. -On success, @samp{dptr} points to a memory block obtained from +On success, @code{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. @@ -681,11 +711,11 @@ 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} inspect the +The function returns next key from the database. If the @code{dptr} +field in the returned datum is @code{NULL} inspect the @code{gdbm_errno} variable (@pxref{Variables, gdbm_errno}). The value of @code{GDBM_ITEM_NOT_FOUND} means that all keys in the database has been visited. Any other value means an error occurred. -Otherwise, @samp{dptr} points to a memory block obtained from +Otherwise, @code{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. @@ -781,5 +811,5 @@ reorganization. @kwindex GDBM_SYNC -Unless your database was opened with the @samp{GDBM_SYNC} flag, +Unless your database was opened with the @code{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 @@ -866,14 +896,14 @@ 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 +Output file format. Allowed values are: @code{GDBM_DUMP_FMT_BINARY} to +create a binary dump and @code{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} +How to create the output file. If @var{flag} is @code{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 +If @var{flag} is @code{GDBM_NEWDB}, the function will create a new output file, replacing it if it already exists. @@ -896,11 +926,11 @@ for a detailed discussion. 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 +to by @var{pdbf}. The latter can point to @code{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. +set @code{gdbm_errno} to @code{GDBM_NO_DBNAME} and return +@code{-1}, indicating failure. The @var{flag} has the same meaning as the @var{flag} argument @@ -944,5 +974,5 @@ 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}. +this error equally as @code{GDBM_ILLEGAL_DATA}. @end table @@ -965,8 +995,8 @@ 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}. +is @code{NULL}. If the line information is not available or applicable, @var{errline} -will be set to @samp{0}. +will be set to @code{0}. @end deftypefn @@ -1091,4 +1121,8 @@ code. The following are the ones that have: @item GDBM_FILE_STAT_ERROR @item GDBM_BACKUP_FAILED +@item GDBM_BACKUP_FAILED +@item GDBM_FILE_CLOSE_ERROR +@item GDBM_FILE_SYNC_ERROR +@item GDBM_FILE_TRUNCATE_ERROR @end itemize @@ -1098,5 +1132,5 @@ For other errors, @code{gdbm_last_syserr} will return 0. @anchor{gdbm_check_syserr} @deftypefn {gdbm interface} {int} gdbm_check_syserr (gdbm_errno @var{err}) -Returns @code{1}, if system errno value should be checked to get more +Returns @code{1}, if system @code{errno} value should be checked to get more info on the error described by GDBM code @var{err}. @end deftypefn @@ -1109,5 +1143,5 @@ Returns textual description of the most recent error encountered when operating on the database @var{dbf}. The resulting string is often more informative than what would be returned by -@samp{gdbm_strerror(gdbm_last_errno(@var{dbf}))}. In particular, if +@code{gdbm_strerror(gdbm_last_errno(@var{dbf}))}. In particular, if there is a system error associated with the recent failure, it will be described as well. @@ -1292,5 +1326,5 @@ The length of the data pointed to by @var{value}. @end table -The return value will be @samp{-1} upon failure, or @samp{0} upon +The return value will be @code{-1} upon failure, or @code{0} upon success. The global variable @code{gdbm_errno} will be set upon failure. @end deftypefn @@ -1303,21 +1337,31 @@ The valid options are: @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. +@kwindex GDBM_CACHE_AUTO +Set the size of the internal bucket cache. The @var{value} should +point to a @code{size_t} holding the desired cache size, or the +constant @code{GDBM_CACHE_AUTO}, to set the best cache size +automatically. + +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. + +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. For example: -The @samp{GDBM_CACHESIZE} option is provided for compatibility with -earlier versions. +@example +size_t bn; +gdbm_bucket_count (dbf, &bn); +ret = gdbm_setopt (dbf, GDBM_SETCACHESIZE, &bn, sizeof (bn)); +@end example -For instance, to set a database to use a cache of 10, after opening it -with @code{gdbm_open}, but prior to accessing it in any way, the following -code could be used: +To set the best cache size, use the constant @code{GDBM_CACHE_AUTO}: @example -@group -int value = 10; -ret = gdbm_setopt (dbf, GDBM_SETCACHESIZE, &value, sizeof (int)); -@end group +size_t bn = GDBM_CACHE_AUTO; +ret = gdbm_setopt (dbf, GDBM_SETCACHESIZE, &bn, sizeof (bn)); @end example @@ -1339,5 +1383,5 @@ its value will be similar to the flags used when opening the database 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 +to an integer: @code{TRUE} to enable fast mode, and @code{FALSE} to disable it. @@ -1352,12 +1396,12 @@ This option is retained for compatibility with previous versions of 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 +to an integer: @code{TRUE} to turn synchronization on, and @code{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}. +i.e.@: calling @code{GDBM_SETSYNCMODE} with @code{TRUE} has the same effect +as calling @code{GDBM_FASTMODE} with @code{FALSE}. -The @samp{GDBM_SYNCMODE} option is provided for compatibility with +The @code{GDBM_SYNCMODE} option is provided for compatibility with earlier versions. @@ -1377,8 +1421,8 @@ which is how previous versions of @code{gdbm} handled free blocks. If set, this option causes all subsequent free blocks to be placed in the @emph{global} pool, allowing (in theory) more file space to be reused -more quickly. The @var{value} should point to an integer: @samp{TRUE} to -turn central block pool on, and @samp{FALSE} to turn it off. +more quickly. The @var{value} should point to an integer: @code{TRUE} to +turn central block pool on, and @code{FALSE} to turn it off. -The @samp{GDBM_CENTFREE} option is provided for compatibility with +The @code{GDBM_CENTFREE} option is provided for compatibility with earlier versions. @@ -1394,5 +1438,5 @@ this option causes adjacent free blocks to be merged. This can become a @acronym{CPU} expensive process with time, though, especially if used in conjunction with GDBM_CENTFREE. The @var{value} should point -to an integer: @samp{TRUE} to turn free block merging on, and @samp{FALSE} to +to an integer: @code{TRUE} to turn free block merging on, and @code{FALSE} to turn it off. @@ -1418,5 +1462,5 @@ point to a value of type @code{size_t} where to return the data. @item GDBM_SETMMAP Enable or disable memory mapping mode. The @var{value} should point -to an integer: @samp{TRUE} to enable memory mapping or @samp{FALSE} to +to an integer: @code{TRUE} to enable memory mapping or @code{FALSE} to disable it. @@ -1460,5 +1504,5 @@ Return the block size in bytes. The @var{value} should point to @code{int}. @kwindex GDBM_NOLOCK -With locking disabled (if @code{gdbm_open} was called with @samp{GDBM_NOLOCK}), +With locking disabled (if @code{gdbm_open} was called with @code{GDBM_NOLOCK}), the user may want to perform their own file locking on the database file in order to prevent multiple writers operating on the same file @@ -1549,6 +1593,6 @@ To compare two split-out version numbers, use the following function: @deftypefn {gdbm interface} int gdbm_version_cmp (int const @var{a}[3], @ int const @var{b}[3]) -Compare two version numbers. Return @samp{-1} if @var{a} is less than -@var{b}, @samp{1} if @var{a} is greater than @var{b} and @samp{0} if +Compare two version numbers. Return @code{-1} if @var{a} is less than +@var{b}, @code{1} if @var{a} is greater than @var{b} and @code{0} if they are equal. @@ -1570,4 +1614,14 @@ gdbm_version_cmp (a, b) @result{} -1 @end deftypefn +@node Additional functions +@chapter Additional functions + +@deftypefn {gdbm interface} int gdbm_avail_verify (GDBM_FILE @var{dbf}) +Verify if the available block stack is in consistent state. On +success, returns 0. If any errors are encountered, sets the +@code{gdbm_errno} to @code{GDBM_BAD_AVAIL}, marks the database as +needing recovery (@pxref{Recovery}) and return -1. +@end deftypefn + @node Error codes @chapter Error codes @@ -1591,5 +1645,5 @@ Memory allocation failed. Not enough memory. This error is set by the @code{gdbm_open} function (@pxref{Open}), if the value of its @var{block_size} argument is incorrect and the -@samp{GDBM_BSEXACT} flag is set. +@code{GDBM_BSEXACT} flag is set. @kwindex GDBM_FILE_OPEN_ERROR @@ -1641,5 +1695,5 @@ The file given as argument to @code{gdbm_open} function is not a valid @item GDBM_CANT_BE_READER This error code is set by the @code{gdbm_open} function if it is not -able to lock file when called in @samp{GDBM_READER} mode (@pxref{Open, +able to lock file when called in @code{GDBM_READER} mode (@pxref{Open, GDBM_READER}). @@ -1682,5 +1736,5 @@ able to create a temporary database. @xref{Reorganization}. Cannot replace existing item. This error is set by the @code{gdbm_store} if the requested @var{key} value is found in the -database and the @var{flag} parameter is not @samp{GDBM_REPLACE}. +database and the @var{flag} parameter is not @code{GDBM_REPLACE}. @xref{Store}, for a detailed discussion. @@ -1692,7 +1746,8 @@ to @code{gdbm_store} (@pxref{Store}). @kwindex GDBM_OPT_ALREADY_SET @item GDBM_OPT_ALREADY_SET -Requested option can be set only once and was already set. This error -is returned by the @code{gdbm_setopt} function. @xref{Options, -GDBM_CACHESIZE}. +Requested option can be set only once and was already set. As of +version @value{VERSION}, this error code is no longer used. In prior +versions it could have been returned by the @code{gdbm_setopt} +function when setting the @code{GDBM_CACHESIZE} value. @kwindex GDBM_OPT_ILLEGAL @@ -1741,5 +1796,5 @@ these functions are: @code{gdbm_delete}, @code{gdbm_exists}, Output database name is not specified. This error code is set by @code{gdbm_load} (@pxref{gdbm_load function,,gdbm_load}) if the first -argument points to @samp{NULL} and the input file does not specify the +argument points to @code{NULL} and the input file does not specify the database name. @@ -1774,12 +1829,81 @@ The GDBM engine is unable to create backup copy of the file. Bucket directory would overflow the size limit during an attempt to split hash bucket. This error can occur while storing a new key. + +@kwindex GDBM_BAD_BUCKET +@item GDBM_BAD_BUCKET +Invalid index bucket is encountered in the database. Database +recovery is needed (@pxref{Recovery}). + +@kwindex GDBM_BAD_HEADER +@item GDBM_BAD_HEADER +This error is set by @code{gdbm_open} and @code{gdbm_fd_open}, if the +first block read from the database file does not contain a valid GDBM +header. + +@kwindex GDBM_BAD_AVAIL +@item GDBM_BAD_AVAIL +The available space stack is invalid. This error can be set by +@code{gdbm_open} and @code{gdbm_fd_open}, if the extended database +verification was requested (@code{GDBM_XVERIFY}). It is also set +by the @code{gdbm_avail_verify} function (@pxref{Additional +functions}). + +Database recovery is needed (@pxref{Recovery}). + +@kwindex GDBM_BAD_HASH_TABLE +@item GDBM_BAD_HASH_TABLE +Hash table in a bucket is invalid. This error can be set by the +following functions: @code{gdbm_delete}, @code{gdbm_exists}, +@code{gdbm_fetch}, @code{gdbm_firstkey}, @code{gdbm_nextkey}, and +@code{gdbm_store}. + +Database recovery is needed (@pxref{Recovery}). + +@kwindex GDBM_BAD_DIR_ENTRY +@item GDBM_BAD_DIR_ENTRY +Bad directory entry found in the bucket. The database recovery is +needed (@pxref{Recovery}). + +@kwindex GDBM_FILE_CLOSE_ERROR +@item GDBM_FILE_CLOSE_ERROR +The @code{gdbm_close} function was unable to close the database file +descriptor. The system @code{errno} variable contains the +corresponding error code. + +@kwindex GDBM_FILE_SYNC_ERROR +@item GDBM_FILE_SYNC_ERROR +Cached content couldn't be synchronized to disk. Examine the +@code{errno} variable to get more info, + +Database recovery is needed (@pxref{Recovery}). + +@kwindex GDBM_FILE_TRUNCATE_ERROR +@item GDBM_FILE_TRUNCATE_ERROR +File cannot be truncated. Examine the @code{errno} variable to get +more info, + +This error is set by @code{gdbm_open} and @code{gdbm_fd_open} when +called with the @code{GDBM_NEWDB} flag. + +@kwindex GDBM_BUCKET_CACHE_CORRUPTED +@item GDBM_BUCKET_CACHE_CORRUPTED +The bucket cache structure is corrupted. Database recovery is needed +(@pxref{Recovery}). + +@kwindex GDBM_BAD_HASH_ENTRY +@kwindex GDBM_BAD_HASH_ENTRY +This error is set during sequential access (@pxref{Sequential}), if +the next hash table entry does not contain the expected key. This +means that the bucket is malformed or corrupted and the database needs +recovery (@pxref{Recovery}). + @end table @node Compatibility -@chapter Compatibility with standard @code{dbm} and @code{ndbm}. +@chapter Compatibility with standard @command{dbm} and @command{ndbm}. @cindex compatibility layer -@code{Gdbm} includes a compatibility layer, which provides traditional -@samp{ndbm} and older @samp{dbm} functions. The layer is compiled and +@command{Gdbm} includes a compatibility layer, which provides traditional +@command{ndbm} and older @command{dbm} functions. The layer is compiled and installed if the @option{--enable-libgdbm-compat} option is used when configuring the package. @@ -1791,5 +1915,5 @@ The compatibility layer consists of two header files: @file{ndbm.h} and @file{dbm.h} and the @file{libgdbm_compat} library. -Older programs using @code{ndbm} or @code{dbm} interfaces can +Older programs using @command{ndbm} or @command{dbm} interfaces can use @file{libgdbm_compat} without any changes. To link a program with the compatibility library, add the following two options to the @@ -1810,9 +1934,9 @@ specification and corresponds to the traditional usage. Note, however, that despite the similarity of the naming convention, actual data stored in these files has not the same format as -in the databases created by other @code{dbm} or @code{ndbm} +in the databases created by other @command{dbm} or @command{ndbm} libraries. In other words, you cannot access a standard UNIX -@code{dbm} file with GNU @code{dbm}! +@command{dbm} file with GNU @command{dbm}! -GNU @code{dbm} files are not @code{sparse}. You can copy them with +GNU @command{dbm} files are not @code{sparse}. You can copy them with the usual @code{cp} command and they will not expand in the copying process. @@ -1827,5 +1951,5 @@ process. @cindex NDBM functions -The functions below implement the @acronym{POSIX} @samp{ndbm} interface: +The functions below implement the @acronym{POSIX} @command{ndbm} interface: @deftypefn {ndbm} {DBM *} dbm_open (char *@var{file}, int @var{flags}, int @var{mode}) @@ -1849,5 +1973,5 @@ the database. This pointer is used to refer to this database in all operations described below. -Any error detected will cause a return value of @samp{NULL} and an +Any error detected will cause a return value of @code{NULL} and an appropriate value will be stored in @code{gdbm_errno} (@pxref{Variables}). @@ -1864,5 +1988,5 @@ argument supplies the key that is being looked for. If no matching record is found, the @code{dptr} member of the returned -datum is @samp{NULL}. Otherwise, the @code{dptr} member of the +datum is @code{NULL}. Otherwise, the @code{dptr} member of the returned datum points to the memory managed by the compatibility library. The application should never free it. @@ -1886,5 +2010,5 @@ Replace existing record with the new one. @item DBM_INSERT The existing record is left unchanged, and the function returns -@samp{1}. +@code{1}. @end table @@ -1895,6 +2019,6 @@ inserted no matter what the value of the @var{mode} is. @deftypefn {ndbm} int dbm_delete (DBM *@var{dbf}, datum @var{key}) Deletes the record with the matching key from the database. If the -function succeeds, @samp{0} is returned. Otherwise, if no matching -record is found or if an error occurs, @samp{-1} is returned. +function succeeds, @code{0} is returned. Otherwise, if no matching +record is found or if an error occurs, @code{-1} is returned. @end deftypefn @@ -1905,5 +2029,5 @@ specific ordering of the keys. If there are no records in the database, the @code{dptr} member of the -returned datum is @samp{NULL}. Otherwise, the @code{dptr} member of +returned datum is @code{NULL}. Otherwise, the @code{dptr} member of the returned datum points to the memory managed by the compatibility library. The application should never free it. @@ -1913,5 +2037,5 @@ library. The application should never free it. Continues the iteration started by @code{dbm_firstkey}. Returns the next key in the database. If the iteration covered all keys in the -database, the @code{dptr} member of the returned datum is @samp{NULL}. +database, the @code{dptr} member of the returned datum is @code{NULL}. Otherwise, the @code{dptr} member of the returned datum points to the memory managed by the compatibility library. The application should @@ -1935,5 +2059,5 @@ otherwise the iteration is not guaranteed to cover all the keys. @deftypefn {ndbm} int dbm_error (DBM *@var{dbf}) -Returns the error condition of the database: @samp{0} if no errors +Returns the error condition of the database: @code{0} if no errors occurred so far while manipulating the database, and a non-zero value otherwise. @@ -1959,6 +2083,6 @@ See also @code{dbm_dirfno}. @deftypefn {ndbm} int dbm_rdonly (DBM *@var{dbf}) -Returns @samp{1} if the database @var{dbf} is open in a read-only mode -and @samp{0} otherwise. +Returns @code{1} if the database @var{dbf} is open in a read-only mode +and @code{0} otherwise. @end deftypefn @@ -1994,5 +2118,5 @@ argument supplies the key that is being looked for. If no matching record is found, the @code{dptr} member of the returned -datum is @samp{NULL}. Otherwise, the @code{dptr} member of the +datum is @code{NULL}. Otherwise, the @code{dptr} member of the returned datum points to the memory managed by the compatibility library. The application should never free it. @@ -2004,5 +2128,5 @@ matching key already exists, its content will be replaced with the new one. -Returns @samp{0} on success and @samp{-1} on error. +Returns @code{0} on success and @code{-1} on error. @end deftypefn @@ -2010,6 +2134,6 @@ Returns @samp{0} on success and @samp{-1} on error. Deletes a record with the matching key. -If the function succeeds, @samp{0} is returned. Otherwise, if no -matching record is found or if an error occurs, @samp{-1} is +If the function succeeds, @code{0} is returned. Otherwise, if no +matching record is found or if an error occurs, @code{-1} is returned. @end deftypefn @@ -2021,5 +2145,5 @@ specific ordering of the keys. If there are no records in the database, the @code{dptr} member of the -returned datum is @samp{NULL}. Otherwise, the @code{dptr} member of +returned datum is @code{NULL}. Otherwise, the @code{dptr} member of the returned datum points to the memory managed by the compatibility library. The application should never free it. @@ -2029,5 +2153,5 @@ library. The application should never free it. Continues the iteration started by a call to @code{firstkey}. Returns the next key in the database. If the iteration covered all keys in the -database, the @code{dptr} member of the returned datum is @samp{NULL}. +database, the @code{dptr} member of the returned datum is @code{NULL}. Otherwise, the @code{dptr} member of the returned datum points to the memory managed by the compatibility library. The application should @@ -2127,5 +2251,5 @@ Disable memory mapping. @itemx --quiet Don't print the usual welcome banner at startup. This is the same as -setting the variable @samp{quiet} in the startup file. @xref{quiet}. +setting the variable @code{quiet} in the startup file. @xref{quiet}. @item -r @itemx --read-only @@ -2156,5 +2280,5 @@ gdbmtool> _ @end example -The utility finishes when it reads the @samp{quit} command (see below) or +The utility finishes when it reads the @code{quit} command (see below) or detects end-of-file on its standard input, whichever occurs first. @@ -2164,6 +2288,6 @@ amount of white space and terminated with a newline or semicolon. A command verb can be entered either in full or in an abbreviated form, as long as that abbreviation does not match any other verb. For -example, @samp{co} can be used instead of @samp{count} and @samp{ca} -instead of @samp{cache}. +example, @code{co} can be used instead of @code{count} and @code{ca} +instead of @code{cache}. Any sequence of non-whitespace characters appearing after the command @@ -2196,5 +2320,5 @@ Command parameters may be optional or mandatory. If the number of actual arguments is less than the number of mandatory parameters, @command{gdbmtool} will prompt you to supply missing arguments. For -example, the @samp{store} command takes two mandatory parameters, so +example, the @code{store} command takes two mandatory parameters, so if you invoked it with no arguments, you would be prompted twice to supply the necessary data, as shown in example below: @@ -2235,5 +2359,5 @@ Whether to ask for confirmation before certain destructive operations, such as truncating the existing database. -Default is @samp{true}. +Default is @code{true}. @end deftypevr @@ -2248,5 +2372,5 @@ follows: @item %f @tab name of the current database file @item %p @tab program invocation name -@item %P @tab package name (@samp{GDBM}) +@item %P @tab package name (@code{GDBM}) @item %v @tab program version @item %_ @tab single space character @@ -2259,5 +2383,5 @@ a ``greater than'' sign, followed by a single space. @deftypevr {gdbmtool variable} string ps2 -Secondary prompt. See @samp{ps1} for a description of its value. +Secondary prompt. See @code{ps1} for a description of its value. This prompt is displayed before reading the second and subsequent lines of a multi-line command. @@ -2317,5 +2441,5 @@ Truncate the database if it exists or create a new one. Open it in read-write mode. -Technically, this sets the @samp{GDBM_NEWDB} flag in call to @samp{gdbm_open}. +Technically, this sets the @code{GDBM_NEWDB} flag in call to @code{gdbm_open}. @xref{Open, GDBM_NEWDB}. @item wrcreat @@ -2324,5 +2448,5 @@ Open the database in read-write mode. Create it if it does not exist. This is the default. -Technically speaking, it sets the @samp{GDBM_WRCREAT} flag in call to +Technically speaking, it sets the @code{GDBM_WRCREAT} flag in call to @code{gdbm_open}. @xref{Open, GDBM_WRCREAT}. @item reader @@ -2331,5 +2455,5 @@ Open the database in read-only mode. Signal an error if it does not exist. -This sets the @samp{GDBM_READER} flag (@pxref{Open, GDBM_READER}). +This sets the @code{GDBM_READER} flag (@pxref{Open, GDBM_READER}). @end table @@ -2348,5 +2472,5 @@ Lock the database. This is the default. Setting this variable to false or unsetting it results in passing -@samp{GDBM_NOLOCK} flag to @code{gdbm_open} (@pxref{Open, GDBM_NOLOCK}). +@code{GDBM_NOLOCK} flag to @code{gdbm_open} (@pxref{Open, GDBM_NOLOCK}). @end deftypevr @@ -2355,5 +2479,5 @@ Use memory mapping. This is the default. Setting this variable to false or unsetting it results in passing -@samp{GDBM_NOMMAP} flag to @code{gdbm_open} (@pxref{Open, GDBM_NOMMAP}). +@code{GDBM_NOMMAP} flag to @code{gdbm_open} (@pxref{Open, GDBM_NOMMAP}). @end deftypevr @@ -2375,5 +2499,5 @@ before invoking it. @deftypevr {gdbmtool variable} bool centfree -Set to @samp{true}, enables the use of central free block pool in +Set to @code{true}, enables the use of central free block pool in newly opened databases. @xref{Options, GDBM_SETCENTFREE}. @@ -2390,5 +2514,5 @@ Unset variables are shown after a comment sign (@samp{#}). For string and numeric variables, values are shown after an equals sign. For boolean variables, only the variable name is displayed if the variable -is @samp{true}. If it is @samp{false}, its name is prefixed with +is @code{true}. If it is @code{false}, its name is prefixed with @samp{no}. @@ -2416,13 +2540,13 @@ If used with arguments, the @code{set} command alters the specified variables. In this case, arguments are variable assignments in the form @samp{@var{name}=@var{value}}. For boolean variables, the -@var{value} is interpreted as follows: if it is numeric, @samp{0} -stands for @samp{false}, any non-zero value stands for @samp{true}. -Otherwise, the values @samp{on}, @samp{true}, and @samp{yes} denote -@samp{true}, and @samp{off}, @samp{false}, @samp{no} stand for -@samp{false}. Alternatively, only the name of a boolean variable can be -supplied to set it to @samp{true}, and its name prefixed with -@samp{no} can be used to set it to false. For example, the following -command sets the @samp{delim2} variable to @samp{;} and the -@samp{confirm} variable to @samp{false}: +@var{value} is interpreted as follows: if it is numeric, @code{0} +stands for @code{false}, any non-zero value stands for @code{true}. +Otherwise, the values @code{on}, @code{true}, and @code{yes |