diff options
| -rw-r--r-- | doc/gdbm.3 | 40 | ||||
| -rw-r--r-- | doc/gdbm.texi | 464 | ||||
| -rw-r--r-- | src/bucket.c | 26 | ||||
| -rw-r--r-- | src/gdbm.h.in | 95 | ||||
| -rw-r--r-- | src/gdbmclose.c | 3 | ||||
| -rw-r--r-- | src/gdbmconst.h | 2 | ||||
| -rw-r--r-- | src/gdbmdefs.h | 2 | ||||
| -rw-r--r-- | src/gdbmopen.c | 5 |
8 files changed, 396 insertions, 241 deletions
@@ -15,3 +15,3 @@ .\" along with GDBM. If not, see <http://www.gnu.org/licenses/>. */ -.TH GDBM 3 "January 27, 2020" "GDBM" "GDBM User Reference" +.TH GDBM 3 "March 21, 2021" "GDBM" "GDBM User Reference" .SH NAME @@ -35,7 +35,7 @@ compatibility. .br -.BI "int gdbm_store (GDBM_FILE " dbf ", datum " key ", datum " content ", int " flag ); +.BI "int gdbm_store (GDBM_FILE " dbf ", datum " key ", datum " content ", int " flag ");" .br -.BI "datum gdbm_fetch (GDBM_FILE " dbf ", datum " key ); +.BI "datum gdbm_fetch (GDBM_FILE " dbf ", datum " key ");" .br -.BI "int gdbm_delete (GDBM_FILE " dbf ", datum " key ); +.BI "int gdbm_delete (GDBM_FILE " dbf ", datum " key ");" .br @@ -43,3 +43,5 @@ compatibility. .br -.BI "datum gdbm_nextkey (GDBM_FILE " dbf ", datum " key ); +.BI "datum gdbm_nextkey (GDBM_FILE " dbf ", datum " key ");" +.br +.BI "int gdbm_recover (GDBM_FILE " dbf ", gdbm_recovery *" rcvr ", int" flags ");" .br @@ -49,5 +51,5 @@ compatibility. .br -.BI "int gdbm_exists (GDBM_FILE " dbf ", datum " key ); +.BI "int gdbm_exists (GDBM_FILE " dbf ", datum " key ");" .br -.BI "const char *gdbm_strerror (gdbm_error " errno ); +.BI "const char *gdbm_strerror (gdbm_error " errno ");" .br @@ -57,2 +59,7 @@ compatibility. .br +.BI "int gdbm_count (GDBM_FILE " dbf ", gdbm_count_t *" pcount ");" +.br +.BI "int gdbm_bucket_count (GDBM_FILE " dbf ", size_t *" pcount ");" +.br +.BI "int gdbm_avail_verify (GDBM_FILE " dbf ");" .PP @@ -163,2 +170,11 @@ Causes all database operations to be synchronized to the disk, 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. +.TP +.B 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. .PP @@ -329,5 +345,9 @@ currently: .B GDBM_CACHESIZE -Set the size of the internal bucket cache. This option may only be set once -on each \fIGDBM_FILE\fR descriptor, and is set automatically to 100 upon the -first access to the database. +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. .TP diff --git a/doc/gdbm.texi b/doc/gdbm.texi index 9c679ca..5f42ced 100644 --- a/doc/gdbm.texi +++ b/doc/gdbm.texi @@ -70,3 +70,3 @@ Documentation License.'' @sp 1 -@center for GNU @code{dbm}, Version @value{VERSION} +@center for GNU @command{dbm}, Version @value{VERSION} @page @@ -87,4 +87,4 @@ Documentation License.'' -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.@: @@ -117,3 +117,3 @@ Functions: * Variables:: Useful global variables. - +* Additional functions:: * Error codes:: Error codes returned by @code{gdbm} calls. @@ -145,4 +145,4 @@ Other topics: 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 @@ -178,6 +178,6 @@ 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 @@ -346,3 +346,3 @@ no such key @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 @@ -365,5 +365,5 @@ 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}. @@ -374,10 +374,10 @@ variable to @samp{GDBM_BLOCK_SIZE_ERROR}. @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 @@ -388,14 +388,33 @@ access to the new database. @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}. @@ -403,3 +422,5 @@ variable to @samp{GDBM_BLOCK_SIZE_ERROR} and return @samp{NULL}. @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 @@ -408,9 +429,18 @@ If the host @samp{open} call @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 @@ -419,3 +449,3 @@ File mode (see @ifnothtml -@ref{chmod,,change permissions of a file,chmod(2), +@xref{chmod,,change permissions of a file,chmod(2), chmod(2) man page}, @@ -427,8 +457,8 @@ and @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. @@ -437,3 +467,3 @@ provided, @code{gdbm} will use a default function. 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 @@ -448,3 +478,3 @@ returned from @code{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 *)) @@ -525,4 +555,4 @@ The data to be associated with the key. 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} @@ -540,6 +570,6 @@ 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. @@ -547,3 +577,3 @@ other functions to indicate an error, it cannot be valid data. 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 @@ -553,3 +583,3 @@ 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}. @@ -568,3 +598,3 @@ value for an object of type @code{int} (type of the @code{dsize} member of 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 @@ -572,5 +602,5 @@ 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 @@ -608,8 +638,8 @@ 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. @@ -646,4 +676,4 @@ The search key. -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 @@ -665,4 +695,4 @@ access is not @code{key} sequential, but it is guaranteed to visit every 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 @@ -671,3 +701,3 @@ 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 @@ -682,4 +712,4 @@ value returned from a previous call to @code{gdbm_nextkey} or -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 @@ -688,3 +718,3 @@ 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 @@ -782,3 +812,3 @@ 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 @@ -867,4 +897,4 @@ 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. @@ -872,3 +902,3 @@ 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, @@ -876,3 +906,3 @@ 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. @@ -897,3 +927,3 @@ for a detailed discussion. 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 @@ -902,4 +932,4 @@ 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. @@ -945,3 +975,3 @@ 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 @@ -966,6 +996,6 @@ 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 @@ -1092,2 +1122,6 @@ code. The following are the ones that have: @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 @@ -1099,3 +1133,3 @@ For other errors, @code{gdbm_last_syserr} will return 0. @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}. @@ -1110,3 +1144,3 @@ 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 @@ -1293,3 +1327,3 @@ The length of the data pointed to by @var{value}. -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. @@ -1304,19 +1338,29 @@ The valid options are: @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 @@ -1340,3 +1384,3 @@ 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. @@ -1353,3 +1397,3 @@ 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. @@ -1357,6 +1401,6 @@ 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. @@ -1378,6 +1422,6 @@ 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. @@ -1395,3 +1439,3 @@ 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. @@ -1419,3 +1463,3 @@ point to a value of type @code{size_t} where to return the data. 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. @@ -1461,3 +1505,3 @@ 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 @@ -1550,4 +1594,4 @@ To compare two split-out version numbers, use the following function: 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. @@ -1571,2 +1615,12 @@ gdbm_version_cmp (a, b) @result{} -1 +@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 @@ -1592,3 +1646,3 @@ 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. @@ -1642,3 +1696,3 @@ The file given as argument to @code{gdbm_open} function is not a valid 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}). @@ -1683,3 +1737,3 @@ 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. @@ -1693,5 +1747,6 @@ to @code{gdbm_store} (@pxref{Store}). @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. @@ -1742,3 +1797,3 @@ 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,3 +1829,72 @@ 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. +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 @@ -1778,7 +1902,7 @@ hash bucket. This error can occur while storing a new key. @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 @@ -1792,3 +1916,3 @@ 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 @@ -1811,7 +1935,7 @@ 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 @@ -1828,3 +1952,3 @@ process. -The functions below implement the @acronym{POSIX} @samp{ndbm} interface: +The functions below implement the @acronym{POSIX} @command{ndbm} interface: @@ -1850,3 +1974,3 @@ 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} @@ -1865,3 +1989,3 @@ 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 @@ -1887,3 +2011,3 @@ Replace existing record with the new one. The existing record is left unchanged, and the function returns -@samp{1}. +@code{1}. @end table @@ -1896,4 +2020,4 @@ inserted no matter what the value of the @var{mode} is. 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 @@ -1906,3 +2030,3 @@ 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 @@ -1914,3 +2038,3 @@ 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 @@ -1936,3 +2060,3 @@ 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 @@ -1960,4 +2084,4 @@ 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 @@ -1995,3 +2119,3 @@ 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 @@ -2005,3 +2129,3 @@ one. -Returns @samp{0} on success and @samp{-1} on error. +Returns @code{0} on success and @code{-1} on error. @end deftypefn @@ -2011,4 +2135,4 @@ 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. @@ -2022,3 +2146,3 @@ 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 @@ -2030,3 +2154,3 @@ 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 @@ -2128,3 +2252,3 @@ Disable memory mapping. 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 @@ -2157,3 +2281,3 @@ gdbmtool> _ -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. @@ -2165,4 +2289,4 @@ 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}. @@ -2197,3 +2321,3 @@ 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 @@ -2236,3 +2360,3 @@ such as truncating the existing database. -Default is @samp{true}. +Default is @code{true}. @end deftypevr @@ -2249,3 +2373,3 @@ follows: @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 @@ -2260,3 +2384,3 @@ 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 @@ -2318,3 +2442,3 @@ 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}. @@ -2325,3 +2449,3 @@ 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}. @@ -2332,3 +2456,3 @@ 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 @@ -2349,3 +2473,3 @@ 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 @@ -2356,3 +2480,3 @@ 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 @@ -2376,3 +2500,3 @@ 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}. @@ -2391,3 +2515,3 @@ 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}. @@ -2417,11 +2541,11 @@ 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} denote +@code{true}, and @code{off}, @code{false}, @code{no} stand for +@code{false}. Alternatively, only the name of a boolean variable can be +supplied to set it to @code{true}, and its name prefixed with +@code{no} can be used to set it to false. For example, the following +command sets the @code{delim2} variable to @samp{;} and the +@code{confirm} variable to @code{false}: @@ -2436,3 +2560,3 @@ variable. Unless explicitly described in the discussion of the variables above, unsetting a boolean variable is equivalent to setting it to -@samp{false}. Unsetting a string variable is equivalent to assigning it +@code{false}. Unsetting a string variable is equivalent to assigning it an empty string. @@ -2577,7 +2701,7 @@ for a list of its values. @item lock -Whether or not to lock the database. Default is @samp{on}. +Whether or not to lock the database. Default is @code{on}. @item mmap -Use the memory mapping. Default is @samp{on}. +Use the memory mapping. Default is @code{on}. @item sync -Synchronize after each write. Default is @samp{off}. +Synchronize after each write. De |