diff options
-rw-r--r-- | doc/gdbm.3 | 40 | ||||
-rw-r--r-- | doc/gdbm.texi | 462 | ||||
-rw-r--r-- | src/bucket.c | 10 | ||||
-rw-r--r-- | src/gdbm.h.in | 91 | ||||
-rw-r--r-- | src/gdbmclose.c | 3 | ||||
-rw-r--r-- | src/gdbmconst.h | 2 | ||||
-rw-r--r-- | src/gdbmdefs.h | 0 | ||||
-rw-r--r-- | src/gdbmopen.c | 5 |
8 files changed, 384 insertions, 229 deletions
@@ -13,7 +13,7 @@ | |||
13 | .\" | 13 | .\" |
14 | .\" You should have received a copy of the GNU General Public License | 14 | .\" You should have received a copy of the GNU General Public License |
15 | .\" along with GDBM. If not, see <http://www.gnu.org/licenses/>. */ | 15 | .\" along with GDBM. If not, see <http://www.gnu.org/licenses/>. */ |
16 | .TH GDBM 3 "January 27, 2020" "GDBM" "GDBM User Reference" | 16 | .TH GDBM 3 "March 21, 2021" "GDBM" "GDBM User Reference" |
17 | .SH NAME | 17 | .SH NAME |
18 | GDBM \- The GNU database manager. Includes \fBdbm\fR and \fBndbm\fR | 18 | GDBM \- The GNU database manager. Includes \fBdbm\fR and \fBndbm\fR |
19 | compatibility. | 19 | compatibility. |
@@ -33,28 +33,35 @@ compatibility. | |||
33 | .br | 33 | .br |
34 | .BI "int gdbm_close (GDBM_FILE " dbf ");" | 34 | .BI "int gdbm_close (GDBM_FILE " dbf ");" |
35 | .br | 35 | .br |
36 | .BI "int gdbm_store (GDBM_FILE " dbf ", datum " key ", datum " content ", int " flag ); | 36 | .BI "int gdbm_store (GDBM_FILE " dbf ", datum " key ", datum " content ", int " flag ");" |
37 | .br | 37 | .br |
38 | .BI "datum gdbm_fetch (GDBM_FILE " dbf ", datum " key ); | 38 | .BI "datum gdbm_fetch (GDBM_FILE " dbf ", datum " key ");" |
39 | .br | 39 | .br |
40 | .BI "int gdbm_delete (GDBM_FILE " dbf ", datum " key ); | 40 | .BI "int gdbm_delete (GDBM_FILE " dbf ", datum " key ");" |
41 | .br | 41 | .br |
42 | .BI "datum gdbm_firstkey (GDBM_FILE " dbf ");" | 42 | .BI "datum gdbm_firstkey (GDBM_FILE " dbf ");" |
43 | .br | 43 | .br |
44 | .BI "datum gdbm_nextkey (GDBM_FILE " dbf ", datum " key ); | 44 | .BI "datum gdbm_nextkey (GDBM_FILE " dbf ", datum " key ");" |
45 | .br | ||
46 | .BI "int gdbm_recover (GDBM_FILE " dbf ", gdbm_recovery *" rcvr ", int" flags ");" | ||
45 | .br | 47 | .br |
46 | .BI "int gdbm_reorganize (GDBM_FILE " dbf ");" | 48 | .BI "int gdbm_reorganize (GDBM_FILE " dbf ");" |
47 | .br | 49 | .br |
48 | .BI "int gdbm_sync (GDBM_FILE " dbf ");" | 50 | .BI "int gdbm_sync (GDBM_FILE " dbf ");" |
49 | .br | 51 | .br |
50 | .BI "int gdbm_exists (GDBM_FILE " dbf ", datum " key ); | 52 | .BI "int gdbm_exists (GDBM_FILE " dbf ", datum " key ");" |
51 | .br | 53 | .br |
52 | .BI "const char *gdbm_strerror (gdbm_error " errno ); | 54 | .BI "const char *gdbm_strerror (gdbm_error " errno ");" |
53 | .br | 55 | .br |
54 | .BI "int gdbm_setopt (GDBM_FILE " dbf ", int " option ", int " value ", int " size ); | 56 | .BI "int gdbm_setopt (GDBM_FILE " dbf ", int " option ", int " value ", int " size ); |
55 | .br | 57 | .br |
56 | .BI "int gdbm_fdesc (GDBM_FILE " dbf ); | 58 | .BI "int gdbm_fdesc (GDBM_FILE " dbf ); |
57 | .br | 59 | .br |
60 | .BI "int gdbm_count (GDBM_FILE " dbf ", gdbm_count_t *" pcount ");" | ||
61 | .br | ||
62 | .BI "int gdbm_bucket_count (GDBM_FILE " dbf ", size_t *" pcount ");" | ||
63 | .br | ||
64 | .BI "int gdbm_avail_verify (GDBM_FILE " dbf ");" | ||
58 | .PP | 65 | .PP |
59 | .SS DBM Compatibility routines: | 66 | .SS DBM Compatibility routines: |
60 | .PP | 67 | .PP |
@@ -161,6 +168,15 @@ Causes all database operations to be synchronized to the disk, | |||
161 | .TP | 168 | .TP |
162 | .B GDBM_NOLOCK | 169 | .B GDBM_NOLOCK |
163 | Prevents the library from performing any locking on the database file. | 170 | Prevents the library from performing any locking on the database file. |
171 | .TP | ||
172 | .B GDBM_CLOEXEC | ||
173 | Set the close-on-exec flag on the database file descriptor. | ||
174 | .TP | ||
175 | .B GDBM_XVERIFY | ||
176 | Enable additional consistency checks. With this flag, eventual | ||
177 | corruptions of the database are discovered when opening it, instead of | ||
178 | when a corrupted structure is read during normal operation. However, | ||
179 | on large databases, it can slow down the opening process. | ||
164 | .PP | 180 | .PP |
165 | The option | 181 | The option |
166 | .B GDBM_FAST | 182 | .B GDBM_FAST |
@@ -327,9 +343,13 @@ and \fIoption\fR specifies which option to set. The valid options are | |||
327 | currently: | 343 | currently: |
328 | .TP | 344 | .TP |
329 | .B GDBM_CACHESIZE | 345 | .B GDBM_CACHESIZE |
330 | Set the size of the internal bucket cache. This option may only be set once | 346 | Set the size of the internal bucket cache. By default, the cache size |
331 | on each \fIGDBM_FILE\fR descriptor, and is set automatically to 100 upon the | 347 | is selected to provide for the optimal performance. Use this option, |
332 | first access to the database. | 348 | if you wish to limit the memory usage at the expense of performance. |
349 | .sp | ||
350 | Use the | ||
351 | .B GDBM_CACHE_AUTO | ||
352 | constant to return to the default. | ||
333 | .TP | 353 | .TP |
334 | .B GDBM_FASTMODE | 354 | .B GDBM_FASTMODE |
335 | Set \fBfast mode\fR to either on or off. This allows \fBfast mode\fR to | 355 | Set \fBfast mode\fR to either on or off. This allows \fBfast mode\fR to |
diff --git a/doc/gdbm.texi b/doc/gdbm.texi index 9c679ca..5f42ced 100644 --- a/doc/gdbm.texi +++ b/doc/gdbm.texi | |||
@@ -68,7 +68,7 @@ Documentation License.'' | |||
68 | @sp 1 | 68 | @sp 1 |
69 | @center Edition @value{EDITION} | 69 | @center Edition @value{EDITION} |
70 | @sp 1 | 70 | @sp 1 |
71 | @center for GNU @code{dbm}, Version @value{VERSION} | 71 | @center for GNU @command{dbm}, Version @value{VERSION} |
72 | @page | 72 | @page |
73 | @vskip 0pt plus 1filll | 73 | @vskip 0pt plus 1filll |
74 | @insertcopying | 74 | @insertcopying |
@@ -85,8 +85,8 @@ Documentation License.'' | |||
85 | @node Top | 85 | @node Top |
86 | @top The GNU database manager. | 86 | @top The GNU database manager. |
87 | 87 | ||
88 | GNU @code{dbm} is a library of functions implementing a hashed database | 88 | GNU @command{dbm} is a library of functions implementing a hashed database |
89 | on a disk file. This manual documents GNU @code{dbm} Version @value{VERSION} | 89 | on a disk file. This manual documents GNU @command{dbm} Version @value{VERSION} |
90 | (@code{gdbm}). The software was originally written by Philip A.@: | 90 | (@code{gdbm}). The software was originally written by Philip A.@: |
91 | Nelson. This document was originally written by Pierre Gaumond from | 91 | Nelson. This document was originally written by Pierre Gaumond from |
92 | texts written by Phil. | 92 | texts written by Phil. |
@@ -115,7 +115,7 @@ Functions: | |||
115 | * Options:: Setting internal options. | 115 | * Options:: Setting internal options. |
116 | * Locking:: File locking. | 116 | * Locking:: File locking. |
117 | * Variables:: Useful global variables. | 117 | * Variables:: Useful global variables. |
118 | 118 | * Additional functions:: | |
119 | * Error codes:: Error codes returned by @code{gdbm} calls. | 119 | * Error codes:: Error codes returned by @code{gdbm} calls. |
120 | * Compatibility:: Compatibility with UNIX dbm and ndbm. | 120 | * Compatibility:: Compatibility with UNIX dbm and ndbm. |
121 | 121 | ||
@@ -143,8 +143,8 @@ Other topics: | |||
143 | @node Copying | 143 | @node Copying |
144 | @chapter Copying Conditions. | 144 | @chapter Copying Conditions. |
145 | This library is @dfn{free}; this means that everyone is free to use | 145 | This library is @dfn{free}; this means that everyone is free to use |
146 | it and free to redistribute it on a free basis. GNU @code{dbm} (@code{gdbm}) | 146 | it and free to redistribute it on a free basis. GNU @command{dbm} |
147 | is not in the public domain; it is copyrighted and there | 147 | (@code{gdbm}) is not in the public domain; it is copyrighted and there |
148 | are restrictions on its distribution, but these restrictions are | 148 | are restrictions on its distribution, but these restrictions are |
149 | designed to permit everything that a good cooperating citizen would want | 149 | designed to permit everything that a good cooperating citizen would want |
150 | to do. What is not allowed is to try to prevent others from further | 150 | to do. What is not allowed is to try to prevent others from further |
@@ -176,10 +176,10 @@ Public License.) A copy the GNU General Public License is included with | |||
176 | the distribution of @code{gdbm}. | 176 | the distribution of @code{gdbm}. |
177 | 177 | ||
178 | @node Intro | 178 | @node Intro |
179 | @chapter Introduction to GNU @code{dbm}. | 179 | @chapter Introduction to GNU @command{dbm}. |
180 | 180 | ||
181 | GNU @code{dbm} (@code{gdbm}) is a library of database functions that use | 181 | GNU @command{dbm} (@code{gdbm}) is a library of database functions that use |
182 | extensible hashing and works similar to the standard UNIX @code{dbm} | 182 | extensible hashing and works similar to the standard UNIX @command{dbm} |
183 | functions. These routines are provided to a programmer needing to | 183 | functions. These routines are provided to a programmer needing to |
184 | create and manipulate a hashed database. (@code{gdbm} is @emph{NOT} a | 184 | create and manipulate a hashed database. (@code{gdbm} is @emph{NOT} a |
185 | complete database package for an end user.) | 185 | complete database package for an end user.) |
@@ -344,7 +344,7 @@ no such key | |||
344 | @cindex opening the database | 344 | @cindex opening the database |
345 | @cindex database, opening or creating | 345 | @cindex database, opening or creating |
346 | @deftypefn {gdbm interface} GDBM_FILE gdbm_open (const char *@var{name}, int @var{block_size}, @ | 346 | @deftypefn {gdbm interface} GDBM_FILE gdbm_open (const char *@var{name}, int @var{block_size}, @ |
347 | int @var{flags}, int @var{mode}, void (*fatal_func)(const char *)) | 347 | int @var{flags}, int @var{mode}, void (*@var{fatal_func})(const char *)) |
348 | Initializes @code{gdbm} system. If the file has a size of zero bytes, a file | 348 | Initializes @code{gdbm} system. If the file has a size of zero bytes, a file |
349 | initialization procedure is performed, setting up the initial structure in the | 349 | initialization procedure is performed, setting up the initial structure in the |
350 | file. | 350 | file. |
@@ -363,61 +363,91 @@ initialized. If the value is less than 512, the file system block | |||
363 | size is used instead. The size is adjusted so that the block can hold | 363 | size is used instead. The size is adjusted so that the block can hold |
364 | exact number of directory entries, so that the effective block size | 364 | exact number of directory entries, so that the effective block size |
365 | can be slightly greater than requested. However, if the | 365 | can be slightly greater than requested. However, if the |
366 | @samp{GDBM_BSEXACT} flag is set and the size needs to be adjusted, the | 366 | @code{GDBM_BSEXACT} flag is set and the size needs to be adjusted, the |
367 | function will return with error status, setting the @samp{gdbm_errno} | 367 | function will return with error status, setting the @code{gdbm_errno} |
368 | variable to @samp{GDBM_BLOCK_SIZE_ERROR}. | 368 | variable to @code{GDBM_BLOCK_SIZE_ERROR}. |
369 | 369 | ||
370 | @item flags | 370 | @item flags |
371 | @kwindex GDBM_READER | 371 | @kwindex GDBM_READER |
372 | @kwindex GDBM_WRITER | 372 | @kwindex GDBM_WRITER |
373 | @kwindex GDBM_WRCREAT | 373 | @kwindex GDBM_WRCREAT |
374 | @kwindex GDBM_NEWDB | 374 | @kwindex GDBM_NEWDB |
375 | If @code{flags} is set to @samp{GDBM_READER}, the user wants to just read the | 375 | If @code{flags} is set to @code{GDBM_READER}, the user wants to just read the |
376 | database and any call to @code{gdbm_store} or @code{gdbm_delete} will fail. | 376 | database and any call to @code{gdbm_store} or @code{gdbm_delete} will fail. |
377 | Many readers can access the database at the same time. If @code{flags} is | 377 | Many readers can access the database at the same time. If @code{flags} is |
378 | set to @samp{GDBM_WRITER}, the user wants both read and write access | 378 | set to @code{GDBM_WRITER}, the user wants both read and write access |
379 | to the database and requires exclusive access. If @code{flags} is set | 379 | to the database and requires exclusive access. If @code{flags} is set |
380 | to @samp{GDBM_WRCREAT}, the user wants both read and write access to | 380 | to @code{GDBM_WRCREAT}, the user wants both read and write access to |
381 | the database and wants it created if it does not already exist. If | 381 | the database and wants it created if it does not already exist. If |
382 | @code{flags} is set to @samp{GDBM_NEWDB}, the user want a new database | 382 | @code{flags} is set to @code{GDBM_NEWDB}, the user want a new database |
383 | created, regardless of whether one existed, and wants read and write | 383 | created, regardless of whether one existed, and wants read and write |
384 | access to the new database. | 384 | access to the new database. |
385 | 385 | ||
386 | @kwindex GDBM_SYNC | 386 | @kwindex GDBM_SYNC |
387 | @kwindex GDBM_NOLOCK | 387 | @kwindex GDBM_NOLOCK |
388 | @kwindex GDBM_NOMMAP | 388 | @kwindex GDBM_NOMMAP |
389 | The following may also be logically or'd into the database flags: | 389 | The following constants may also be logically or'd into the database |
390 | @samp{GDBM_SYNC}, which causes all database operations to be | 390 | flags: |
391 | synchronized to the disk, @samp{GDBM_NOLOCK}, which prevents the library | 391 | |
392 | from performing any locking on the database file, and @samp{GDBM_NOMMAP}, | 392 | @table @code |
393 | which disables the memory mapping mechanism. The option @samp{GDBM_FAST} is | 393 | @kwindex GDBM_SYNC |
394 | now obsolete, since @code{gdbm} defaults to no-sync mode. | 394 | @item GDBM_SYNC |
395 | Synchronize all database operations to disk immediately. This | ||
396 | provides for the best database consistency at the expense of severe | ||