1GDBM(3) GDBM User Reference GDBM(3)
2
3
4
6 GDBM - The GNU database manager. Includes dbm and ndbm compatibility.
7
9 #include <gdbm.h>
10
11 extern gdbm_error gdbm_errno;
12 extern char *gdbm_version;
13 extern int gdbm_version[3];
14 GDBM_FILE gdbm_open (const char *name, int block_size,
15 int flags, int mode,
16 void (*fatal_func)(const char *));
17 int gdbm_close (GDBM_FILE dbf);
18 int gdbm_store (GDBM_FILE dbf, datum key, datum content, int flag);
19 datum gdbm_fetch (GDBM_FILE dbf, datum key);
20 int gdbm_delete (GDBM_FILE dbf, datum key);
21 datum gdbm_firstkey (GDBM_FILE dbf);
22 datum gdbm_nextkey (GDBM_FILE dbf, datum key);
23 int gdbm_recover (GDBM_FILE dbf, gdbm_recovery *rcvr, intflags);
24 int gdbm_reorganize (GDBM_FILE dbf);
25 int gdbm_sync (GDBM_FILE dbf);
26 int gdbm_exists (GDBM_FILE dbf, datum key);
27 const char *gdbm_strerror (gdbm_error errno);
28 int gdbm_setopt (GDBM_FILE dbf, int option, int value, int size);
29 int gdbm_fdesc (GDBM_FILE dbf);
30 int gdbm_count (GDBM_FILE dbf, gdbm_count_t *pcount);
31 int gdbm_bucket_count (GDBM_FILE dbf, size_t *pcount);
32 int gdbm_avail_verify (GDBM_FILE dbf);
33
34 Crash Tolerance (see below):
35 int gdbm_failure_atomic (GDBM_FILE dbf, const char *even, const char
36 *odd);
37 int gdbm_latest_snapshot (const char *even, const char *odd, const char
38 **result);
39
41 This manpage is a short description of the GDBM library. For a de‐
42 tailed discussion, including examples and usage recommendations, refer
43 to the GDBM Manual available in Texinfo format. To access it, run:
44
45 info gdbm
46
47 The documentation is also available online at
48
49 https://www.gnu.org/software/gdbm/manual
50
51 Should any discrepancies occur between this manpage and the GDBM Man‐
52 ual, the later shall be considered the authoritative source.
53
55 GNU dbm is a library of routines that manages data files that contain
56 key/data pairs. The access provided is that of storing, retrieval, and
57 deletion by key and a non-sorted traversal of all keys. A process is
58 allowed to use multiple data files at the same time.
59
60 Opening a database
61 A process that opens a gdbm file is designated as a "reader" or a
62 "writer". Only one writer may open a gdbm file and many readers may
63 open the file. Readers and writers can not open the gdbm file at the
64 same time. The procedure for opening a gdbm file is:
65
66 GDBM_FILE gdbm_open (const char *name, int block_size,
67 int flags, int mode,
68 void (*fatal_func)(const char *));
69
70 Name is the name of the file (the complete name, gdbm does not append
71 any characters to this name).
72
73 Block_size is the size of a single transfer from disk to memory. If
74 the value is less than 512, the file system block size is used instead.
75 The size is adjusted so that the block can hold exact number of direc‐
76 tory entries, so that the effective block size can be slightly greater
77 than requested. This adjustment is disabled if the GDBM_BSEXACT flag
78 is used.
79
80 The flags parameter is a bitmask, composed of the access mode and one
81 or more modifier flags. The access mode bit designates the process as
82 a reader or writer and must be one of the following:
83
84 GDBM_READER
85 reader
86
87 GDBM_WRITER
88 writer
89
90 GDBM_WRCREAT
91 writer - if database does not exist create new one
92
93 GDBM_NEWDB
94 writer - create new database regardless if one exists
95
96 Additional flags (modifiers) can be combined with these values by bit‐
97 wise OR. Not all of them are meaningful with all access modes.
98
99 Flags that are valid for any value of access mode are:
100
101 GDBM_CLOEXEC
102 Set the close-on-exec flag on the database file descriptor.
103
104 GDBM_NOLOCK
105 Prevents the library from performing any locking on the database
106 file.
107
108 GDBM_NOMMAP
109 Instructs gdbm_open to disable the use of mmap(2).
110
111 GDBM_PREREAD
112 When mapping GDBM file to memory, read its contents immediately,
113 instead of when needed (prefault reading). This can be advanta‐
114 geous if you open a read-only database and are going to do a lot
115 of look-ups on it. In this case entire database will be read at
116 once and searches will operate on an in-memory copy. In con‐
117 trast, GDBM_PREREAD should not be used if you open a database
118 (even in read-only mode) only to retrieve a couple of keys.
119
120 Finally, never use GDBM_PREREAD when opening a database for up‐
121 dates, especially for inserts: this will degrade performance.
122
123 This flag has no effect if GDBM_NOMMAP is given, or if the oper‐
124 ating system does not support prefault reading. It is known to
125 work on Linux and FreeBSD kernels.
126
127 GDBM_XVERIFY
128 Enable additional consistency checks. With this flag, eventual
129 corruptions of the database are discovered when opening it, in‐
130 stead of when a corrupted structure is read during normal opera‐
131 tion. However, on large databases, it can slow down the opening
132 process.
133
134 The following additional flags are valid when the database is opened
135 for writing (GDBM_WRITER, GDBM_WRCREAT, or GDBM_NEWDB):
136
137 GDBM_SYNC
138 Causes all database operations to be synchronized to the disk.
139
140 NOTE: this option entails severe performance degradation and
141 does not necessarily ensure that the resulting database state is
142 consistent, therefore we discourage its use. For a discussion
143 of how to ensure database consistency with minimal performance
144 overhead, see CRASH TOLERANCE below.
145
146 GDBM_FAST
147 A reverse of GDBM_SYNC: synchronize writes only when needed.
148 This is the default. This flag is provided only for compatibil‐
149 ity with previous versions of GDBM.
150
151 The following flags can be used together with GDBM_NEWDB. They also
152 take effect when used with GDBM_WRCREAT, if the requested database file
153 doesn't exist:
154
155 GDBM_BSEXACT
156 If this flag is set and the requested block_size value cannot be
157 used, gdbm_open will refuse to create the database. In this
158 case it will set the gdbm_errno variable to GDBM_BLOCK_SIZE_ER‐
159 ROR and return NULL.
160
161 Without this flag, gdbm_open will silently adjust the block_size
162 to a usable value, as described above.
163
164 GDBM_NUMSYNC
165 Create new database in extended database format, a format best
166 suited for effective crash recovery. For a detailed discussion,
167 see the CRASH RECOVERY chapter below.
168
169 Mode is the file mode (see chmod(2) and open(2)). It is used if the
170 file is created.
171
172 Fatal_func is a function to be called when gdbm if it encounters a fa‐
173 tal error. This parameter is deprecated and must always be NULL.
174
175 The return value is the pointer needed by all other routines to access
176 that gdbm file. If the return is the NULL pointer, gdbm_open was not
177 successful. In this case, the reason of the failure can be found in
178 the gdbm_errno variable. If the following call returns true (non-zero
179 value):
180
181 gdbm_check_syserr(gdbm_open)
182
183 the system errno variable must be examined in order to obtain more de‐
184 tail about the failure.
185
186 GDBM_FILE gdbm_fd_open (int FD, const char *name, int block_size,
187 int flags, int mode,
188 void (*fatal_func)(const char *));
189
190 This is an alternative entry point to gdbm_open. FD is a valid file
191 descriptor obtained as a result of a call to open(2) or creat(2). The
192 function opens (or creates) a DBM database this descriptor refers to.
193 The descriptor is not dup'ed, and will be closed when the returned
194 GDBM_FILE is closed. Use dup (2) if that is not desirable.
195
196 In case of error, the function behaves like gdbm_open and does not
197 close FD. This can be altered by the following value passed in flags:
198
199 GDBM_CLOERROR
200 Close FD before exiting on error.
201
202 The rest of arguments are the same as for gdbm_open.
203
204 Calling convention
205 All GDBM functions take as their first parameter the database handle
206 (GDBM_FILE), returned from gdbm_open or gdbm_fd_open.
207
208 Any value stored in the GDBM database is described by datum, an aggre‐
209 gate type defined as:
210
211 typedef struct
212 {
213 char *dptr;
214 int dsize;
215 } datum;
216
217 The dptr field points to the actual data. Its type is char * for his‐
218 torical reasons. Actually it should have been typed void *. Program‐
219 mers are free to store data of arbitrary complexity, both scalar and
220 aggregate, in this field.
221
222 The dsize field contains the number of bytes stored in dptr.
223
224 The datum type is used to describe both keys and content (values) in
225 the database. Values of this type can be passed as arguments or re‐
226 turned from GDBM function calls.
227
228 GDBM functions that return datum indicate failure by setting its dptr
229 field to NULL.
230
231 Functions returning integer value, indicate success by returning 0 and
232 failure by returning a non-zero value (the only exception to this rule
233 is gdbm_exists, for which the return value is reversed).
234
235 If the returned value indicates failure, the gdbm_errno variable con‐
236 tains an integer value indicating what went wrong. A similar value is
237 associated with the dbf handle and can be accessed using the
238 gdbm_last_errno function. Immediately after return from a function,
239 both values are exactly equal. Subsequent GDBM calls with another dbf
240 as argument may alter the value of the global gdbm_errno, but the value
241 returned by gdbm_last_errno will always indicate the most recent code
242 of an error that occurred for that particular database. Programmers
243 are encouraged to use such per-database error codes.
244
245 Sometimes the actual reason of the failure can be clarified by examin‐
246 ing the system errno value. To make sure its value is meaningful for a
247 given GDBM error code, use the gdbm_check_syserr function. The func‐
248 tion takes error code as argument and returns 1 if the errno is mean‐
249 ingful for that error, or 0 if it is irrelevant.
250
251 Similarly to gdbm_errno, the latest errno value associated with a par‐
252 ticular database can be obtained using the gdbm_last_syserr function.
253
254 The gdbm_clear_error clears the error indicator (both GDBM and system
255 error codes) associated with a database handle.
256
257 Some critical errors leave the database in a structurally inconsistent
258 state. If that happens, all subsequent GDBM calls accessing that data‐
259 base will fail with the GDBM error code of GDBM_NEED_RECOVERY (a spe‐
260 cial function gdbm_needs_recovery is also provided, which returns true
261 if the database handle given as its argument is structurally inconsis‐
262 tent). To return such databases to consistent state, use the gdbm_re‐
263 cover function (see below).
264
265 The GDBM_NEED_RECOVERY error cannot be cleared using gdbm_clear_error.
266
267 Error functions
268 This section describes the error handling functions outlined above.
269
270 gdbm_error gdbm_last_errno (GDBM_FILE dbf)
271 Returns the error code of the most recent failure encountered
272 when operating on dbf.
273
274 int gdbm_last_syserr (GDBM_FILE dbf)
275 Returns the value of the system errno variable associated with
276 the most recent failure that occurred on dbf.
277
278 Notice that not all gdbm_error codes have a relevant system er‐
279 ror code. Use the following function to determine if a given
280 code has.
281
282 int gdbm_check_syserr (gdbm_error err)
283 Returns 1, if system errno value should be checked to get more
284 info on the error described by GDBM code err.
285
286 void gdbm_clear_error (GDBM_FILE dbf)
287 Clears the error state for the database dbf. This function is
288 called implicitly upon entry to any GDBM function that operates
289 on GDBM_FILE.
290
291 The GDBM_NEED_RECOVERY error cannot be cleared.
292
293 int gdbm_needs_recovery (GDBM_FILE dbf)
294 Return 1 if the database file dbf is in inconsistent state and
295 needs recovery.
296
297 const char *gdbm_strerror (gdbm_error err)
298 Returns a textual description of the error code err.
299
300 const char *gdbm_db_strerror (GDBM_FILE dbf)
301 Returns a textual description of the recent error in database
302 dbf. This description includes the system errno value, if rele‐
303 vant.
304
305 Closing the database
306 It is important that every database file opened is also closed. This
307 is needed to update the reader/writer count on the file. This is done
308 by:
309
310 int gdbm_close (GDBM_FILE dbf);
311
312 Database lookups
313 int gdbm_exists (GDBM_FILE dbf, datum key);
314 If the key is found within the database, the return value will
315 be true (1). If nothing appropriate is found, false (0) is re‐
316 turned and gdbm_errno set to GDBM_NO_ERROR.
317
318 On error, returns 0 and sets gdbm_errno.
319
320 datum gdbm_fetch (GDBM_FILE dbf, datum key);
321 Dbf is the pointer returned by gdbm_open. Key is the key data.
322
323 If the dptr element of the return value is NULL, the gdbm_errno
324 variable should be examined. The value of GDBM_ITEM_NOT_FOUND
325 means no data was found for that key. Other value means an er‐
326 ror occurred.
327
328 Otherwise the return value is a pointer to the found data. The
329 storage space for the dptr element is allocated using malloc(3).
330 GDBM does not automatically free this data. It is the program‐
331 mer's responsibility to free this storage when it is no longer
332 needed.
333
334 Iterating over the database
335 The following two routines allow for iterating over all items in the
336 database. Such iteration is not key sequential, but it is guaranteed
337 to visit every key in the database exactly once. (The order has to do
338 with the hash values.)
339
340 datum gdbm_firstkey (GDBM_FILE dbf);
341 Returns first key in the database.
342
343 datum gdbm_nextkey (GDBM_FILE dbf, datum key);
344 Given a key, returns the database key that follows it. End of
345 iteration is marked by returning datum with dptr field set to
346 NULL and setting the gdbm_errno value to GDBM_ITEM_NOT_FOUND.
347
348 After successful return from both functions, dptr points to data allo‐
349 cated by malloc(3). It is the caller responsibility to free the data
350 when no longer needed.
351
352 A typical iteration loop looks like:
353
354 datum key, nextkey, content;
355 key = gdbm_firstkey (dbf);
356 while (key.dptr)
357 {
358 content = gdbm_fetch (dbf, key);
359 /* Do something with key and/or content */
360 nextkey = gdbm_nextkey (dbf, key);
361 free (key.dptr);
362 key = nextkey;
363 }
364
365 These functions are intended to visit the database in read-only algo‐
366 rithms. Avoid any database modifications within the iteration loop.
367 File visiting is based on a hash table. The gdbm_delete and, in most
368 cases, gdbm_store, functions rearrange the hash table to make sure that
369 any collisions in the table do not leave some item `un-findable'.
370 Thus, a call to either of these functions changes the order in which
371 the keys are ordered. Therefore, these functions should not be used
372 when iterating over all the keys in the database. For example, the
373 following loop is wrong: it is possible that some keys will not be vis‐
374 ited or will be visited twice if it is executed:
375
376 key = gdbm_firstkey (dbf);
377 while (key.dptr)
378 {
379 nextkey = gdbm_nextkey (dbf, key);
380 if (some condition)
381 gdbm_delete ( dbf, key );
382 free (key.dptr);
383 key = nextkey;
384 }
385
386 Updating the database
387 int gdbm_store (GDBM_FILE dbf, datum key, datum content, int flag);
388 Dbf is the pointer returned by gdbm_open. Key is the key data.
389 Content is the data to be associated with the key. Flag can
390 have one of the following values:
391
392 GDBM_INSERT
393 Insert only, generate an error if key exists;
394
395 GDBM_REPLACE
396 Replace contents if key exists.
397
398 The function returns 0 on success and -1 on failure. If the key
399 already exists in the database and the flag is GDBM_INSERT, the
400 function does not modify the database. It sets gdbm_errno to
401 GDBM_CANNOT_REPLACE and returns 1.
402
403 int gdbm_delete (GDBM_FILE dbf, datum key);
404 Looks up and deletes the given key from the database dbf.
405
406 The return value is 0 if there was a successful delete or -1 on
407 error. In the latter case, the gdbm_errno value
408 GDBM_ITEM_NOT_FOUND indicates that the key is not present in the
409 database. Other gdbm_errno values indicate failure.
410
411 Recovering structural consistency
412 If a function leaves the database in structurally inconsistent state,
413 it can be recovered using the gdbm_recover function.
414
415 int gdbm_recover (GDBM_FILE dbf, gdbm_recovery * rcvr, int flags)
416 Check the database file DBF and fix eventual inconsistencies.
417 The rcvr argument can be used both to control the recovery and
418 to return additional statistics about the process, as indicated
419 by flags. For a detailed discussion of these arguments and
420 their usage, see the GDBM Manual, chapter Recovering structural
421 consistency.
422
423 You can pass NULL as rcvr and 0 as flags, if no such control is
424 needed.
425
426 By default, this function first checks the database for incon‐
427 sistencies and attempts recovery only if some were found. The
428 special flags bit GDBM_RCVR_FORCE instructs gdbm_recovery to
429 skip this check and to perform database recovery uncondition‐
430 ally.
431
432 Export and import
433 GDBM database files can be exported (dumped) to so called flat files or
434 imported (loaded) from them. A flat file contains exactly the same
435 data as the original database, but it cannot be used for searches or
436 updates. Its purpose is to keep the data from the database for restor‐
437 ing it when the need arrives. As such, flat files are used for backup
438 purposes, and for sending databases over the wire.
439
440 As of GDBM version 1.21, there are two flat file formats. The ASCII
441 file format encodes all data in Base64 and stores not only key/data
442 pairs, but also the original database file metadata, such as file name,
443 mode and ownership. Files in this format can be sent without addi‐
444 tional encapsulation over transmission channels that normally allow
445 only ASCII data, such as, e.g. SMTP. Due to additional metadata they
446 allow for restoring an exact copy of the database, including file own‐
447 ership and privileges, which is especially important if the database in
448 question contained some security-related data. This is the preferred
449 format.
450
451 Another flat file format is the binary format. It stores only key/data
452 pairs and does not keep information about the database file itself. It
453 cannot be used to copy databases between different architectures. The
454 binary format was introduced in GDBM version 1.9.1 and is retained
455 mainly for backward compatibility.
456
457 The following functions are used to export or import GDBM database
458 files.
459
460 int gdbm_dump (GDBM_FILE dbf, const char *filename,
461 int format, int open_flag, int mode)
462 Dumps the database file dbf to the file filename in requested
463 format. Allowed values for format are: GDBM_DUMP_FMT_ASCII, to
464 create an ASCII dump file, and GDBM_DUMP_FMT_BINARY, to create a
465 binary dump.
466
467 The value of open_flag tells gdbm_dump what to do if filename
468 already exists. If it is GDBM_NEWDB, the function will create a
469 new output file, replacing it if it already exists. If its
470 value is GDBM_WRCREAT, the file will be created if it does not
471 exist. If it does exist, gdbm_dump will return error.
472
473 The file mode to use when creating the output file is defined by
474 the mode parameter. Its meaning is the same as for open(2).
475
476 int gdbm_load (GDBM_FILE *pdbf, const char *filename,
477 int flag, int meta_mask, unsigned long *errline)
478 Loads data from the dump file filename into the database pointed
479 to by pdbf. If pdbf is NULL, the function will try to create a
480 new database. On success, the new GDBM_FILE object will be
481 stored in the memory location pointed to by pdbf. If the dump
482 file carries no information about the original database file
483 name, the function will set gdbm_errno to GDBM_NO_DBNAME and re‐
484 turn -1, indicating failure.
485
486 Otherwise, if pdbf points to an already open GDBM_FILE, the
487 function will load data from filename into that database.
488
489 The flag parameter controls the function behavior if a key from
490 the dump file already exists in the database. See the
491 gdbm_store function for its possible values.
492
493 The meta_mask parameter can be used to disable restoring certain
494 bits of file's meta-data from the information in the input dump
495 file. It is a binary OR of zero or more of the following:
496
497 GDBM_META_MASK_MODE
498 Do not restore file mode.
499
500 GDBM_META_MASK_OWNER
501 Do not restore file owner.
502
503 Other functions
504 int gdbm_reorganize (GDBM_FILE dbf);
505 If you have had a lot of deletions and would like to shrink the
506 space used by the GDBM file, this routine will reorganize the
507 database.
508
509 int gdbm_sync (GDBM_FILE dbf);
510 Synchronizes the changes in dbf with its disk file.
511
512 It will not return until the disk file state is synchronized
513 with the in-memory state of the database.
514
515 int gdbm_setopt (GDBM_FILE dbf, int option, void *value, int size);
516 Query or change some parameter of an already opened database.
517 The option argument defines what parameter to set or retrieve.
518 If the set operation is requested, value points to the new
519 value. Its actual data type depends on option. If the get op‐
520 eration is requested, value points to a memory region where to
521 store the return value. In both cases, size contains the actual
522 size of the memory pointed to by value.
523
524 Possible values of option are:
525
526 GDBM_SETCACHESIZE
527 GDBM_CACHESIZE
528 Set the size of the internal bucket cache. The value should
529 point to a size_t holding the desired cache size, or the
530 constant GDBM_CACHE_AUTO, to select the best cache size au‐
531 tomatically.
532
533 By default, a newly open database is configured to adapt the
534 cache size to the number of index buckets in the database
535 file. This provides for the best performance.
536
537 Use this option if you wish to limit the memory usage at the
538 expense of performance. If you chose to do so, please bear
539 in mind that cache becomes effective when its size is
540 greater then 2/3 of the number of index bucket counts in the
541 database. The best performance results are achieved when
542 cache size equals the number of buckets.
543
544 GDBM_GETCACHESIZE
545 Return the size of the internal bucket cache. The value
546 should point to a size_t variable, where the size will be
547 stored.
548
549 GDBM_GETFLAGS
550 Return the flags describing current state of the database.
551 The value should point to an int variable where to store the
552 flags. On success, its value will be similar to the flags
553 used when opening the database, except that it will reflect
554 the current state (which may have been altered by another
555 calls to gdbm_setopt).
556
557 GDBM_FASTMODE
558 Enable or disable the fast writes mode, similar to the
559 GDBM_FAST option to gdbm_open.
560
561 This option is retained for compatibility with previous ver‐
562 sions of GDBM.
563
564 GDBM_SETSYNCMODE
565 GDBM_SYNCMODE
566 Turn on or off immediate disk synchronization after updates.
567 The value should point to an integer: 1 to turn synchroniza‐
568 tion on, and 0 to turn it off.
569
570 NOTE: setting this option entails severe performance degra‐
571 dation and does not necessarily ensure that the resulting
572 database state is consistent, therefore we discourage its
573 use. For a discussion of how to ensure database consistency
574 with minimal performance overhead, see CRASH TOLERANCE be‐
575 low.
576
577 GDBM_GETSYNCMODE
578 Return the current synchronization status. The value should
579 point to an int where the status will be stored.
580
581 GDBM_SETCENTFREE
582 GDBM_CENTFREE
583 Enable or disable central free block pool. The default is
584 off, which is how previous versions of GDBM handled free
585 blocks. If set, this option causes all subsequent free
586 blocks to be placed in the global pool, allowing (in theory)
587 more file space to be reused more quickly. The value should
588 point to an integer: TRUE to turn central block pool on, and
589 FALSE to turn it off.
590
591 The GDBM_CENTFREE alias is provided for compatibility with
592 earlier versions.
593
594 GDBM_SETCOALESCEBLKS
595 GDBM_COALESCEBLKS
596 Set free block merging to either on or off. The default is
597 off, which is how previous versions of GDBM handled free
598 blocks. If set, this option causes adjacent free blocks to
599 be merged. This can become a CPU expensive process with
600 time, though, especially if used in conjunction with
601 GDBM_CENTFREE. The value should point to an integer: TRUE
602 to turn free block merging on, and FALSE to turn it off.
603
604 GDBM_GETCOALESCEBLKS
605 Return the current status of free block merging. The value
606 should point to an int where the status will be stored.
607
608 GDBM_SETMAXMAPSIZE
609 Sets maximum size of a memory mapped region. The value
610 should point to a value of type size_t, unsigned long or un‐
611 signed. The actual value is rounded to the nearest page
612 boundary (the page size is obtained from sysconf(_SC_PAGE‐
613 SIZE)).
614
615 GDBM_GETMAXMAPSIZE
616 Return the maximum size of a memory mapped region. The
617 value should point to a value of type size_t where to return
618 the data.
619
620 GDBM_SETMMAP
621 Enable or disable memory mapping mode. The value should
622 point to an integer: TRUE to enable memory mapping or FALSE
623 to disable it.
624
625 GDBM_GETMMAP
626 Check whether memory mapping is enabled. The value should
627 point to an integer where to return the status.
628
629 GDBM_GETDBNAME
630 Return the name of the database disk file. The value should
631 point to a variable of type char**. A pointer to the newly
632 allocated copy of the file name will be placed there. The
633 caller is responsible for freeing this memory when no longer
634 needed.
635
636 GDBM_GETBLOCKSIZE
637 Return the block size in bytes. The value should point to
638 int.
639
640 int gdbm_fdesc (GDBM_FILE dbf);
641 Returns the file descriptor of the database dbf.
642
644 By default GNU dbm does not protect the integrity of its databases from
645 corruption or destruction due to failures such as power outages, oper‐
646 ating system kernel panics, or application process crashes. Such fail‐
647 ures could damage or destroy the underlying database.
648
649 Starting with release 1.21 GNU dbm includes a mechanism that, if used
650 correctly, enables post-crash recovery to a consistent state of the un‐
651 derlying database. This mechanism requires OS and filesystem support
652 and must be requested when gdbm is compiled. The crash-tolerance mech‐
653 anism is a "pure opt-in" feature, in the sense that it has no effects
654 whatsoever except on those applications that explicitly request it.
655 For details, see the chapter Crash Tolerance in the GDBM manual.
656
658 gdbm_error gdbm_errno
659 This variable contains code of the most recent error that oc‐
660 curred. Note, that it is not C variable in the proper sense:
661 you can use its value, assign any value to it, but taking its
662 address will result in syntax error. It is a per-thread memory
663 location.
664
665 const char *gdbm_version
666 A string containing the library version number and build date.
667
668 int const gdbm_version_number[3]
669 This variable contains library version numbers: major, minor,
670 and patchlevel.
671
673 The version information is kept in two places. The version of the li‐
674 brary is kept in the gdbm_version_number variable, described above.
675 Additionally, the header file gdbm.h defines the following macros:
676
677 GDBM_VERSION_MAJOR
678 Major version number.
679
680 GDBM_VERSION_MINOR
681 Minor version number.
682
683 GDBM_VERSION_PATCH
684 Patchlevel number. 0 means no patchlevel.
685
686 You can use this to compare whether your header file corresponds to the
687 library the program is linked with.
688
689 The following function can be used to compare two version numbers:
690
691 int gdbm_version_cmp (int const a[3], int const b[3])
692 Compare two version numbers formatted as gdbm_version_number.
693 Return negative number if a is older than b, positive number if
694 a is newer than b, and 0 if they are equal.
695
697 GDBM_NO_ERROR
698 No error occurred.
699
700 GDBM_MALLOC_ERROR
701 Memory allocation failed.
702
703 GDBM_BLOCK_SIZE_ERROR
704 This error is set by the gdbm_open function, if the value of its
705 block_size argument is incorrect and the GDBM_BSEXACT flag is
706 set.
707
708 GDBM_FILE_OPEN_ERROR
709 The library was not able to open a disk file. This can be set
710 by gdbm_open, gdbm_fd_open, gdbm_dump and gdbm_load functions.
711
712 Inspect the value of the system errno variable to get more de‐
713 tailed diagnostics.
714
715 GDBM_FILE_WRITE_ERROR
716 Writing to a disk file failed. This can be set by gdbm_open,
717 gdbm_fd_open, gdbm_dump and gdbm_load functions.
718
719 Inspect the value of the system errno variable to get more de‐
720 tailed diagnostics.
721
722 GDBM_FILE_SEEK_ERROR
723 Positioning in a disk file failed. This can be set by gdbm_open
724 function.
725
726 Inspect the value of the system errno variable to get a more de‐
727 tailed diagnostics.
728
729 GDBM_FILE_READ_ERROR
730 Reading from a disk file failed. This can be set by gdbm_open,
731 gdbm_dump and gdbm_load functions.
732
733 Inspect the value of the system errno variable to get a more de‐
734 tailed diagnostics.
735
736 GDBM_BAD_MAGIC_NUMBER
737 The file given as argument to gdbm_open function is not a valid
738 gdbm file: it has a wrong magic number.
739
740 GDBM_EMPTY_DATABASE
741 The file given as argument to gdbm_open function is not a valid
742 gdbm file: it has zero length. This error is returned unless
743 the flags argument has GDBM_NEWDB bit set.
744
745 GDBM_CANT_BE_READER
746 This error code is set by the gdbm_open function if it is not
747 able to lock file when called in GDBM_READER mode.
748
749 GDBM_CANT_BE_WRITER
750 This error code is set by the gdbm_open function if it is not
751 able to lock file when called in writer mode.
752
753 GDBM_READER_CANT_DELETE
754 Set by the gdbm_delete, if it attempted to operate on a database
755 that is open in read-only mode.
756
757 GDBM_READER_CANT_STORE
758 Set by the gdbm_store if it attempted to operate on a database
759 that is open in read-only mode.
760
761 GDBM_READER_CANT_REORGANIZE
762 Set by the gdbm_reorganize if it attempted to operate on a data‐
763 base that is open in read-only mode.
764
765 GDBM_ITEM_NOT_FOUND
766 Requested item was not found. This error is set by gdbm_delete
767 and gdbm_fetch when the requested key value is not found in the
768 database.
769
770 GDBM_REORGANIZE_FAILED
771 The gdbm_reorganize function is not able to create a temporary
772 database.
773
774 GDBM_CANNOT_REPLACE
775 Cannot replace existing item. This error is set by the
776 gdbm_store if the requested key value is found in the database
777 and the flag parameter is not GDBM_REPLACE.
778
779 GDBM_MALFORMED_DATA
780 Input data was malformed in some way. When returned by
781 gdbm_load, this means that the input file was not a valid gdbm
782 dump file. When returned by gdbm_store, this means that either
783 key or content parameter had its dptr field set to NULL.
784
785 The GDBM_ILLEGAL_DATA is an alias for this error code, main‐
786 tained for backward compatibility.
787
788 GDBM_OPT_ALREADY_SET
789 Requested option can be set only once and was already set. As
790 of version 1.21, this error code is no longer used. In prior
791 versions it could have been returned by the gdbm_setopt function
792 when setting the GDBM_CACHESIZE value.
793
794 GDBM_OPT_BADVAL
795 The option argument is not valid or the value argument points to
796 an invalid value in a call to gdbm_setopt function.
797
798 GDBM_OPT_ILLEGAL is an alias for this error code, maintained for
799 backward compatibility. Modern applications should not use it.
800
801 GDBM_BYTE_SWAPPED
802 The gdbm_open function attempts to open a database which is cre‐
803 ated on a machine with different byte ordering.
804
805 GDBM_BAD_FILE_OFFSET
806 The gdbm_open function sets this error code if the file it tries
807 to open has a wrong magic number.
808
809 GDBM_BAD_OPEN_FLAGS
810 Set by the gdbm_dump function if supplied an invalid flags argu‐
811 ment.
812
813 GDBM_FILE_STAT_ERROR
814 Getting information about a disk file failed. The system errno
815 will give more details about the error.
816
817 This error can be set by the following functions: gdbm_open,
818 gdbm_reorganize.
819
820 GDBM_FILE_EOF
821 End of file was encountered where more data was expected to be
822 present. This error can occur when fetching data from the data‐
823 base and usually means that the database is truncated or other‐
824 wise corrupted.
825
826 This error can be set by any GDBM function that does I/O. Some
827 of these functions are: gdbm_delete, gdbm_exists, gdbm_fetch,
828 gdbm_export, gdbm_import, gdbm_reorganize, gdbm_firstkey,
829 gdbm_nextkey, gdbm_store.
830
831 GDBM_NO_DBNAME
832 Output database name is not specified. This error code is set
833 by gdbm_load if the first argument points to NULL and the input
834 file does not specify the database name.
835
836 GDBM_ERR_FILE_OWNER
837 This error code is set by gdbm_load if it is unable to restore
838 the database file owner. It is a mild error condition, meaning
839 that the data have been restored successfully, only changing the
840 target file owner failed. Inspect the system errno variable to
841 get a more detailed diagnostics.
842
843 GDBM_ERR_FILE_MODE
844 This error code is set by gdbm_load if it is unable to restore
845 database file mode. It is a mild error condition, meaning that
846 the data have been restored successfully, only changing the tar‐
847 get file owner failed. Inspect the system errno variable to get
848 a more detailed diagnostics.
849
850 GDBM_NEED_RECOVERY
851 Database is in inconsistent state and needs recovery. Call
852 gdbm_recover if you get this error.
853
854 GDBM_BACKUP_FAILED
855 The GDBM engine is unable to create backup copy of the file.
856
857 GDBM_DIR_OVERFLOW
858 Bucket directory would overflow the size limit during an attempt
859 to split hash bucket. This error can occur while storing a new
860 key.
861
862 GDBM_BAD_BUCKET
863 Invalid index bucket is encountered in the database. Database
864 recovery is needed.
865
866 GDBM_BAD_HEADER
867 This error is set by gdbm_open and gdbm_fd_open, if the first
868 block read from the database file does not contain a valid GDBM
869 header.
870
871 GDBM_BAD_AVAIL
872 The available space stack is invalid. This error can be set by
873 gdbm_open and gdbm_fd_open, if the extended database verifica‐
874 tion was requested (GDBM_XVERIFY). It is also set by the
875 gdbm_avail_verify function.
876
877 The database needs recovery.
878
879 GDBM_BAD_HASH_TABLE
880 Hash table in a bucket is invalid. This error can be set by the
881 following functions: gdbm_delete, gdbm_exists, gdbm_fetch,
882 gdbm_firstkey, gdbm_nextkey, and gdbm_store.
883
884 The database needs recovery.
885
886 GDBM_BAD_DIR_ENTRY
887 Bad directory entry found in the bucket. The database recovery
888 is needed.
889
890 GDBM_FILE_CLOSE_ERROR
891 The gdbm_close function was unable to close the database file
892 descriptor. The system errno variable contains the correspond‐
893 ing error code.
894
895 GDBM_FILE_SYNC_ERROR
896 Cached content couldn't be synchronized to disk. Examine the
897 errno variable to get more info,
898
899 Database recovery is needed.
900
901 GDBM_FILE_TRUNCATE_ERROR
902 File cannot be truncated. Examine the errno variable to get
903 more info.
904
905 This error is set by gdbm_open and gdbm_fd_open when called with
906 the GDBM_NEWDB flag.
907
908 GDBM_BUCKET_CACHE_CORRUPTED
909 The bucket cache structure is corrupted. Database recovery is
910 needed.
911
912 GDBM_BAD_HASH_ENTRY
913 This error is set during sequential access (@pxref{Sequential}),
914 if the next hash table entry does not contain the expected key.
915 This means that the bucket is malformed or corrupted and the
916 database needs recovery.
917
918 GDBM_ERR_SNAPSHOT_CLONE
919 Set by the gdbm_failure_atomic function if it was unable to
920 clone the database file into a snapshot. Inspect the system er‐
921 rno variable for the underlying cause of the error. If errno is
922 EINVAL or ENOSYS, crash tolerance settings will be removed from
923 the database.
924
925 GDBM_ERR_REALPATH
926 Set by the gdbm_failure_atomic function if the call to realpath
927 function failed. realpath is used to determine actual path
928 names of the snapshot files. Examine the system errno variable
929 for details.
930
931 GDBM_ERR_USAGE
932 Function usage error. That includes invalid argument values,
933 and the like.
934
936 GDBM includes a compatibility library libgdbm_compat, for use with pro‐
937 grams that expect traditional UNIX dbm or ndbm interfaces, such as,
938 e.g. Sendmail. The library is optional and thus may be absent in some
939 binary distributions.
940
941 As the detailed discussion of the compatibility API is beyond the scope
942 of this document, below we provide only a short reference. For de‐
943 tails, see the GDBM Manual, chapter Compatibility with standard dbm and
944 ndbm.
945
946 DBM compatibility routines
947 In dbm compatibility mode only one file may be opened at a time. All
948 users are assumed to be writers. If the database file is read only, it
949 will fail as a writer, but will be opened as a reader. All returned
950 pointers in datum structures point to data that the compatibility li‐
951 brary will free. They should be treated as static pointers (as stan‐
952 dard UNIX dbm does).
953
954 The following interfaces are provided:
955
956 #include <dbm.h>
957
958 int dbminit (const char *name);
959 int store (datum key, datum content);
960 datum fetch (datum key);
961 int delete (datum key);
962 datum firstkey (void);
963 datum nextkey (datum key);
964 int dbmclose (void);
965
966 NDBM Compatibility routines:
967 In this mode, multiple databases can be opened. Each database is iden‐
968 tified by a handle of type DBM *. As in the original NDBM, all re‐
969 turned pointers in datum structures point to data that will be freed by
970 the compatibility library. They should be treated as static pointers.
971
972 The following interfaces are provided:
973
974 #include <ndbm.h>
975
976 DBM *dbm_open (const char *name, int flags, int mode);
977 void dbm_close (DBM *file);
978 datum dbm_fetch (DBM *file, datum key);
979 int dbm_store (DBM *file, datum key, datum content, int flags);
980 int dbm_delete (DBM *file, datum key);
981 datum dbm_firstkey (DBM *file);
982 datum dbm_nextkey (DBM *file, datum key);
983 int dbm_error (DBM *file);
984 int dbm_clearerr (DBM *file);
985 int dbm_pagfno (DBM *file);
986 int dbm_dirfno (DBM *file);
987 int dbm_rdonly (DBM *file);
988
990 This library is accessed by specifying -lgdbm as the last parameter to
991 the compile line, e.g.:
992
993 gcc -o prog prog.c -lgdbm
994
995 If you wish to use the dbm or ndbm compatibility routines, you must
996 link in the gdbm_compat library as well. For example:
997
998 gcc -o prog proc.c -lgdbm -lgdbm_compat
999
1000
1002 Send bug reports to <bug-gdbm@gnu.org>.
1003
1005 gdbm_dump(1), gdbm_load(1), gdbmtool(1).
1006
1008 by Philip A. Nelson, Jason Downs and Sergey Poznyakoff; crash tolerance
1009 by Terence Kelly.
1010
1012 Copyright © 1990 - 2021 Free Software Foundation, Inc.
1013
1014 GDBM is free software; you can redistribute it and/or modify it under
1015 the terms of the GNU General Public License as published by the Free
1016 Software Foundation; either version 1, or (at your option) any later
1017 version.
1018
1019 GDBM is distributed in the hope that it will be useful, but WITHOUT ANY
1020 WARRANTY; without even the implied warranty of MERCHANTABILITY or FIT‐
1021 NESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
1022 more details.
1023
1024 You should have received a copy of the GNU General Public License along
1025 with GDBM. If not, see <http://gnu.org/licenses/gpl.html>
1026
1028 You may contact the original author by:
1029 e-mail: phil@cs.wwu.edu
1030 us-mail: Philip A. Nelson
1031 Computer Science Department
1032 Western Washington University
1033 Bellingham, WA 98226
1034
1035 You may contact the current maintainers by:
1036 e-mail: downsj@downsj.com
1037 and
1038 e-mail: gray@gnu.org
1039
1040 For questions and feedback regarding crash tolerance, you may contact
1041 Terence Kelly at:
1042 e-mail: tpkelly @ { acm.org, cs.princeton.edu, eecs.umich.edu }
1043
1044
1045
1046
1047GDBM October 18, 2021 GDBM(3)