1GDBM(3) GDBM User Reference GDBM(3)
2
6 GDBM - The GNU database manager. Includes dbm and ndbm compatability.
7 (Version 1.9.)
8
10 #include <gdbm.h>
11 extern gdbm_error gdbm_errno;
13 extern char *gdbm_version;
14 GDBM_FILE gdbm_open (const char *name, int block_size,
15 int flags, int mode,
16 void (*fatal_func)(const char *));
17 void 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_reorganize (GDBM_FILE dbf);
24 void gdbm_sync (GDBM_FILE dbf);
25 int gdbm_exists (GDBM_FILE dbf, datum key);
26 const char *gdbm_strerror (gdbm_error errno);
27 int gdbm_setopt (GDBM_FILE dbf, int option, int value, int size);
28 int gdbm_fdesc (GDBM_FILE dbf);
29 DBM Compatability routines:
31 #include <dbm.h>
32 int dbminit (const char *name);
34 int store (datum key, datum content);
35 datum fetch (datum key);
36 int delete (datum key);
37 datum firstkey (void);
38 datum nextkey (datum key);
39 int dbmclose (void);
40 NDBM Compatability routines:
42 #include <ndbm.h>
43 DBM *dbm_open (const char *name, int flags, int mode);
45 void dbm_close (DBM *file); datumdbm_fetch(DBM*"file, datum key);
46 int dbm_store (DBM *file, datum key, datum content, int flags);
47 int dbm_delete (DBM *file, datum key);
48 datum dbm_firstkey (DBM *file);
49 datum dbm_nextkey (DBM *file, datum key);
50 int dbm_error (DBM *file);
51 int dbm_clearerr (DBM *file);
52 int dbm_pagfno (DBM *file);
53 int dbm_dirfno (DBM *file);
54 int dbm_rdonly (DBM *file);
55
57 GNU dbm is a library of routines that manages data files that contain
58 key/data pairs. The access provided is that of storing, retrieval, and
59 deletion by key and a non-sorted traversal of all keys. A process is
60 allowed to use multiple data files at the same time.
61 This manpage is a short description of the GDBM library. For a
63 detailed discussion, including examples of the configuration and usage
64 recommendations, refer to the GDBM Manual available in Texinfo format.
65 To access it, run:
66 info gdbm
68 Should any discrepancies occur between this manpage and the GDBM Man‐
70 ual, the later shall be considered the authoritative source.
71 A process that opens a gdbm file is designated as a "reader" or a
73 "writer". Only one writer may open a gdbm file and many readers may
74 open the file. Readers and writers can not open the gdbm file at the
75 same time. The procedure for opening a gdbm file is:
76 GDBM_FILE gdbm_open (const char *name, int block_size,
78 int flags, int mode,
79 void (*fatal_func)(const char *));
80 Name is the name of the file (the complete name, gdbm does not append
82 any characters to this name). Block_size is the size of a single
83 transfer from disk to memory. This parameter is ignored unless the file
84 is a new file. The minimum size is 512. If it is less than 512, dbm
85 will use the stat block size for the file system. Read_write can have
86 one of the following values:
87 GDBM_READER
89 reader
90 GDBM_WRITER
92 writer
93 GDBM_WRCREAT
95 writer - if database does not exist create new one
96 GDBM_NEWDB
98 writer - create new database regardless if one exists
99 The GDBM_NOMMAP added to read_write by bitwise or instructs gdbm_open
101 to disable the use of mmap(2).
102 For the last three (writers of the database) the following may be added
104 added to read_write by bitwise or:
105 GDBM_SYNC
107 Causes all database operations to be synchronized to the disk,
108 GDBM_NOLOCK
110 Pevents the library from performing any locking on the database
111 file.
112 The option GDBM_FAST is now obsolete, since gdbm defaults to no-sync
114 mode.
115 Mode is the file mode (see chmod(2) and open(2)) if the file is cre‐
117 ated. (*Fatal_func) () is a function for dbm to call if it detects a
118 fatal error. The only parameter of this function is a string. If the
119 value of 0 is provided, gdbm will use a default function.
120 The return value is the pointer needed by all other routines to access
122 that gdbm file. If the return is the NULL pointer, gdbm_open was not
123 successful. The errors can be found in gdbm_errno for gdbm errors and
124 in errno for system errors. (For error codes, see gdbmerrno.h.)
125 In all of the following calls, the parameter dbf refers to the pointer
127 returned from gdbm_open.
128 It is important that every file opened is also closed. This is needed
130 to update the reader/writer count on the file. This is done by:
131 void gdbm_close (GDBM_FILE dbf);
133 The database is used by 3 primary routines. The first stores data in
135 the database.
136 int gdbm_store (GDBM_FILE dbf, datum key, datum content, int flag);
138 Dbf is the pointer returned by gdbm_open. Key is the key data. Con‐
140 tent is the data to be associated with the key. Flag can have one of
141 the following values:
142 GDBM_INSERT
144 Insert only, generate an error if key exists;
145 GDBM_REPLACE
147 Replace contents if key exists.
148 If a reader calls gdbm_store, the return value will be -1. If called
150 with GDBM_INSERT and key is in the database, the return value will be
151 1. Otherwise, the return value is 0.
152 NOTICE: If you store data for a key that is already in the data base,
154 gdbm replaces the old data with the new data if called with
155 GDBM_REPLACE. You do not get two data items for the same key and you
156 do not get an error from gdbm_store.
157 NOTICE: The size in gdbm is not restricted like in dbm or ndbm. Your
159 data can be as large as you want.
160 To search for some data, use:
162 datum gdbm_fetch (GDBM_FILE dbf, datum key);
164 Dbf is the pointer returned by gdbm_open. Key is the key data.
166 If the dptr element of the return value is NULL, no data was found.
168 Otherwise the return value is a pointer to the found data. The storage
169 space for the dptr element is allocated using malloc(3). Gdbm does not
170 automatically free this data. It is the programmer's responsibility to
171 free this storage when it is no longer needed.
172 To search for some data, without retrieving it:
174 int gdbm_exists (GDBM_FILE dbf, datum key);
176 Dbf is the pointer returned by gdbm_open. Key is the key data to
178 search for.
179 If the key is found within the database, the return value will be true.
181 If nothing appropiate is found, false is returned. This routine is
182 useful for checking for the existence of a record, without performing
183 the memory allocation done by gdbm_fetch.
184 To remove some data from the database:
186 int gdbm_delete (GDBM_FILE dbf, datum key);
188 Dbf is the pointer returned by gdbm_open. Key is the key data.
190 The return value is -1 if the item is not present or the requester is a
192 reader. The return value is 0 if there was a successful delete.
193 The next two routines allow for accessing all items in the database.
195 This access is not key sequential, but it is guaranteed to visit every
196 key in the database once. (The order has to do with the hash values.)
197 datum gdbm_firstkey (GDBM_FILE dbf);
199 datum gdbm_nextkey (GDBM_FILE dbf, datum key);
200 Dbf is the pointer returned by gdbm_open. Key is the key data.
202 The return values are both of type datum. If the dptr element of the
204 return value is NULL, there is no first key or next key. Again notice
205 that dptr points to data allocated by malloc(3) and gdbm will not free
206 it for you.
207 These functions were intended to visit the database in read-only algo‐
209 rithms, for instance, to validate the database or similar operations.
210 File `visiting' is based on a `hash table'. gdbm_delete re-arranges
212 the hash table to make sure that any collisions in the table do not
213 leave some item `un-findable'. The original key order is NOT guaran‐
214 teed to remain unchanged in ALL instances. It is possible that some
215 key will not be visited if a loop like the following is executed:
216 key = gdbm_firstkey (dbf);
218 while (key.dptr)
219 {
220 nextkey = gdbm_nextkey (dbf, key);
221 if (some condition)
222 gdbm_delete ( dbf, key );
223 free (key.dptr);
224 key = nextkey;
225 }
226 The following routine should be used very infrequently.
228 int gdbm_reorganize (GDBM_FILE dbf);
230 If you have had a lot of deletions and would like to shrink the space
232 used by the gdbm file, this routine will reorganize the database. Gdbm
233 will not shorten the length of a gdbm file except by using this reorga‐
234 nization. (Deleted file space will be reused.)
235 Unless your database was opened with the GDBM_SYNC flag, gdbm does not
237 wait for writes to be flushed to the disk before continuing. The fol‐
238 lowing routine can be used to guarantee that the database is physically
239 written to the disk file.
240 void gdbm_sync (GDBM_FILE dbf);
242 It will not return until the disk file state is syncronized with the
244 in-memory state of the database.
245 To convert a gdbm error code into English text, use this routine:
247 const char *gdbm_strerror (gdbm_error errno);
249 Gdbm now supports the ability to set certain options on an already open
251 database.
252 int gdbm_setopt (GDBM_FILE dbf, int option, int value, int size);
254 Where dbf is the return value from a previous call to gdbm_open, and
256 option specifies which option to set. The valid options are currently:
257 GDBM_CACHESIZE
259 Set the size of the internal bucket cache. This option may only
260 be set once on each GDBM_FILE descriptor, and is set automati‐
261 cally to 100 upon the first access to the database.
262 GDBM_FASTMODE
264 Set fast mode to either on or off. This allows fast mode to be
265 toggled on an already open and active database. value (see
266 below) should be set to either TRUE or FALSE. This option is
267 now obsolete.
268 GDBM_SYNCMODE
270 Turn on or off file system synchronization operations. This
271 setting defaults to off; value (see below) should be set to
272 either TRUE or FALSE.
273 GDBM_CENTFREE
275 Set central free block pool to either on or off. The default is
276 off, which is how previous versions of Gdbm handled free blocks.
277 If set, this option causes all subsequent free blocks to be
278 placed in the global pool, allowing (in thoery) more file space
279 to be reused more quickly. value (see below) should be set to
280 either TRUE or FALSE. NOTICE: This feature is still under
281 study.
282 GDBM_COALESCEBLKS
284 Set free block merging to either on or off. The default is off,
285 which is how previous versions of Gdbm handled free blocks. If
286 set, this option causes adjacent free blocks to be merged. This
287 can become a CPU expensive process with time, though, especially
288 if used in conjunction with GDBM_CENTFREE. value (see below)
289 should be set to either TRUE or FALSE. NOTICE: This feature is
290 still under study.
291 value is the value to set option to, specified as an integer pointer.
293 size is the size of the data pointed to by value. The return value
294 will be -1 upon failure, or 0 upon success. The global variable
295 gdbm_errno will be set upon failure.
296 For instance, to set a database to use a cache of 10, after opening it
298 with gdbm_open, but prior to accessing it in any way, the following
299 code could be used:
300 int value = 10;
302 ret = gdbm_setopt( dbf, GDBM_CACHESIZE, &value, sizeof(int));
304 If the database was opened with the GDBM_NOLOCK flag, the user may wish
306 to perform their own file locking on the database file in order to pre‐
307 vent multiple writers operating on the same file simultaneously.
308 In order to support this, the gdbm_fdesc routine is provided.
310 int gdbm_fdesc (GDBM_FILE dbf);
312 Where dbf is the return value from a previous call to gdbm_open. The
314 return value will be the file descriptor of the database.
315 The following two external variables may be useful:
317 gdbm_errno is the variable that contains more information about gdbm
319 errors. (gdbm.h has the definitions of the error values and defines
320 gdbm_errno as an external variable.)
321 gdbm_version is the string containing the version information.
323 There are a few more things of interest. First, gdbm files are not
325 "sparse". You can copy them with the UNIX cp(1) command and they will
326 not expand in the copying process. Also, there is a compatibility mode
327 for use with programs that already use UNIX dbm. In this compatibility
328 mode, no gdbm file pointer is required by the programmer, and only one
329 file may be opened at a time. All users in compatibility mode are
330 assumed to be writers. If the gdbm file is a read only, it will fail
331 as a writer, but will also try to open it as a reader. All returned
332 pointers in datum structures point to data that gdbm WILL free. They
333 should be treated as static pointers (as standard UNIX dbm does).
334
336 This library is accessed by specifying -lgdbm as the last parameter to
337 the compile line, e.g.:
338 gcc -o prog prog.c -lgdbm
340 If you wish to use the dbm or ndbm compatibility routines, you must
342 link in the gdbm_compat library as well. For example:
343 gcc -o prog proc.c -lgdbm -lgdbm_compat
345
348 Send bug reports to <bug-gdbm@gnu.org>.
349
351 dbm, ndbm
352
354 by Philip A. Nelson, Jason Downs and Sergey Poznyakoff.
355
357 Copyright © 1990 - 2011 Free Software Foundation, Inc.
358 GDBM is free software; you can redistribute it and/or modify it under
360 the terms of the GNU General Public License as published by the Free
361 Software Foundation; either version 1, or (at your option) any later
362 version.
363 GDBM is distributed in the hope that it will be useful, but WITHOUT ANY
365 WARRANTY; without even the implied warranty of MERCHANTABILITY or FIT‐
366 NESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
367 more details.
368 You should have received a copy of the GNU General Public License along
370 with GDBM. If not, see <http://gnu.org/licenses/gpl.html>
371
373 You may contact the original author by:
374 e-mail: phil@cs.wwu.edu
375 us-mail: Philip A. Nelson
376 Computer Science Department
377 Western Washington University
378 Bellingham, WA 98226
379 You may contact the current maintainers by:
381 e-mail: downsj@downsj.com
382 and
383 e-mail: gray@gnu.org
384GDBM August 9, 2011 GDBM(3)