1GDBM(3) GDBM User Reference GDBM(3)
2
6 GDBM - The GNU database manager. Includes dbm and ndbm compatibility.
7
9 #include <gdbm.h>
10 extern gdbm_error gdbm_errno;
12 extern char *gdbm_version;
13 GDBM_FILE gdbm_open (const char *name, int block_size,
14 int flags, int mode,
15 void (*fatal_func)(const char *));
16 int gdbm_close (GDBM_FILE dbf);
17 int gdbm_store (GDBM_FILE dbf, datum key, datum content, int flag);
18 datum gdbm_fetch (GDBM_FILE dbf, datum key);
19 int gdbm_delete (GDBM_FILE dbf, datum key);
20 datum gdbm_firstkey (GDBM_FILE dbf);
21 datum gdbm_nextkey (GDBM_FILE dbf, datum key);
22 int gdbm_reorganize (GDBM_FILE dbf);
23 int gdbm_sync (GDBM_FILE dbf);
24 int gdbm_exists (GDBM_FILE dbf, datum key);
25 const char *gdbm_strerror (gdbm_error errno);
26 int gdbm_setopt (GDBM_FILE dbf, int option, int value, int size);
27 int gdbm_fdesc (GDBM_FILE dbf);
28 DBM Compatibility routines:
30 #include <dbm.h>
31 int dbminit (const char *name);
33 int store (datum key, datum content);
34 datum fetch (datum key);
35 int delete (datum key);
36 datum firstkey (void);
37 datum nextkey (datum key);
38 int dbmclose (void);
39 NDBM Compatibility routines:
41 #include <ndbm.h>
42 DBM *dbm_open (const char *name, int flags, int mode);
44 void dbm_close (DBM *file);
45 datum dbm_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 Prevents 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 int 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, the gdbm_errno vari‐
168 able should be examined. The value of GDBM_ITEM_NOT_FOUND means no
169 data was found for that key. Other value means an error occurred.
170 Otherwise the return value is a pointer to the found data. The storage
172 space for the dptr element is allocated using malloc(3). Gdbm does not
173 automatically free this data. It is the programmer's responsibility to
174 free this storage when it is no longer needed.
175 To search for some data, without retrieving it:
177 int gdbm_exists (GDBM_FILE dbf, datum key);
179 Dbf is the pointer returned by gdbm_open. Key is the key data to
181 search for.
182 If the key is found within the database, the return value will be true.
184 If nothing appropriate is found, false is returned. This routine is
185 useful for checking for the existence of a record, without performing
186 the memory allocation done by gdbm_fetch.
187 To remove some data from the database:
189 int gdbm_delete (GDBM_FILE dbf, datum key);
191 Dbf is the pointer returned by gdbm_open. Key is the key data.
193 The return value is -1 if the item is not present or the requester is a
195 reader. The return value is 0 if there was a successful delete.
196 The next two routines allow for accessing all items in the database.
198 This access is not key sequential, but it is guaranteed to visit every
199 key in the database once. (The order has to do with the hash values.)
200 datum gdbm_firstkey (GDBM_FILE dbf);
202 datum gdbm_nextkey (GDBM_FILE dbf, datum key);
203 Dbf is the pointer returned by gdbm_open. Key is the key data.
205 The return values are both of type datum. If the dptr element of the
207 return value is NULL, inspect the gdbm_errno. If it is
208 GDBM_ITEM_NOT_FOUND, there is no first key or next key. Otherwise, an
209 error occurred.
210 Again, notice that dptr points to data allocated by malloc(3) and gdbm
212 will not free it for you.
213 These functions were intended to visit the database in read-only algo‐
215 rithms, for instance, to validate the database or similar operations.
216 File `visiting' is based on a `hash table'. gdbm_delete re-arranges
218 the hash table to make sure that any collisions in the table do not
219 leave some item `un-findable'. The original key order is NOT guaran‐
220 teed to remain unchanged in ALL instances. It is possible that some
221 key will not be visited if a loop like the following is executed:
222 key = gdbm_firstkey (dbf);
224 while (key.dptr)
225 {
226 nextkey = gdbm_nextkey (dbf, key);
227 if (some condition)
228 gdbm_delete ( dbf, key );
229 free (key.dptr);
230 key = nextkey;
231 }
232 The following routine should be used very infrequently.
234 int gdbm_reorganize (GDBM_FILE dbf);
236 If you have had a lot of deletions and would like to shrink the space
238 used by the gdbm file, this routine will reorganize the database. Gdbm
239 will not shorten the length of a gdbm file except by using this reorga‐
240 nization. (Deleted file space will be reused.)
241 Unless your database was opened with the GDBM_SYNC flag, gdbm does not
243 wait for writes to be flushed to the disk before continuing. The fol‐
244 lowing routine can be used to guarantee that the database is physically
245 written to the disk file.
246 int gdbm_sync (GDBM_FILE dbf);
248 It will not return until the disk file state is synchronized with the
250 in-memory state of the database.
251 To convert a gdbm error code into English text, use this routine:
253 const char *gdbm_strerror (gdbm_error errno);
255 Gdbm now supports the ability to set certain options on an already open
257 database.
258 int gdbm_setopt (GDBM_FILE dbf, int option, int value, int size);
260 Where dbf is the return value from a previous call to gdbm_open, and
262 option specifies which option to set. The valid options are currently:
263 GDBM_CACHESIZE
265 Set the size of the internal bucket cache. This option may only
266 be set once on each GDBM_FILE descriptor, and is set automati‐
267 cally to 100 upon the first access to the database.
268 GDBM_FASTMODE
270 Set fast mode to either on or off. This allows fast mode to be
271 toggled on an already open and active database. value (see
272 below) should be set to either TRUE or FALSE. This option is
273 now obsolete.
274 GDBM_SYNCMODE
276 Turn on or off file system synchronization operations. This
277 setting defaults to off; value (see below) should be set to
278 either TRUE or FALSE.
279 GDBM_CENTFREE
281 Set central free block pool to either on or off. The default is
282 off, which is how previous versions of Gdbm handled free blocks.
283 If set, this option causes all subsequent free blocks to be
284 placed in the global pool, allowing (in thoery) more file space
285 to be reused more quickly. value (see below) should be set to
286 either TRUE or FALSE. NOTICE: This feature is still under
287 study.
288 GDBM_COALESCEBLKS
290 Set free block merging to either on or off. The default is off,
291 which is how previous versions of Gdbm handled free blocks. If
292 set, this option causes adjacent free blocks to be merged. This
293 can become a CPU expensive process with time, though, especially
294 if used in conjunction with GDBM_CENTFREE. value (see below)
295 should be set to either TRUE or FALSE. NOTICE: This feature is
296 still under study.
297 value is the value to set option to, specified as an integer pointer.
299 size is the size of the data pointed to by value. The return value
300 will be -1 upon failure, or 0 upon success. The global variable
301 gdbm_errno will be set upon failure.
302 For instance, to set a database to use a cache of 10, after opening it
304 with gdbm_open, but prior to accessing it in any way, the following
305 code could be used:
306 int value = 10;
308 ret = gdbm_setopt( dbf, GDBM_CACHESIZE, &value, sizeof(int));
310 If the database was opened with the GDBM_NOLOCK flag, the user may wish
312 to perform their own file locking on the database file in order to pre‐
313 vent multiple writers operating on the same file simultaneously.
314 In order to support this, the gdbm_fdesc routine is provided.
316 int gdbm_fdesc (GDBM_FILE dbf);
318 Where dbf is the return value from a previous call to gdbm_open. The
320 return value will be the file descriptor of the database.
321 The following two external variables may be useful:
323 gdbm_errno is the variable that contains more information about gdbm
325 errors. (gdbm.h has the definitions of the error values and defines
326 gdbm_errno as an external variable.)
327 gdbm_version is the string containing the version information.
329 There are a few more things of interest. First, gdbm files are not
331 "sparse". You can copy them with the UNIX cp(1) command and they will
332 not expand in the copying process. Also, there is a compatibility mode
333 for use with programs that already use UNIX dbm. In this compatibility
334 mode, no gdbm file pointer is required by the programmer, and only one
335 file may be opened at a time. All users in compatibility mode are
336 assumed to be writers. If the gdbm file is a read only, it will fail
337 as a writer, but will also try to open it as a reader. All returned
338 pointers in datum structures point to data that gdbm WILL free. They
339 should be treated as static pointers (as standard UNIX dbm does).
340
342 This library is accessed by specifying -lgdbm as the last parameter to
343 the compile line, e.g.:
344 gcc -o prog prog.c -lgdbm
346 If you wish to use the dbm or ndbm compatibility routines, you must
348 link in the gdbm_compat library as well. For example:
349 gcc -o prog proc.c -lgdbm -lgdbm_compat
351
354 Send bug reports to <bug-gdbm@gnu.org>.
355
357 gdbm_dump(1), gdbm_load(1), gdbmtool(1).
358
360 by Philip A. Nelson, Jason Downs and Sergey Poznyakoff.
361
363 Copyright © 1990 - 2020 Free Software Foundation, Inc.
364 GDBM is free software; you can redistribute it and/or modify it under
366 the terms of the GNU General Public License as published by the Free
367 Software Foundation; either version 1, or (at your option) any later
368 version.
369 GDBM is distributed in the hope that it will be useful, but WITHOUT ANY
371 WARRANTY; without even the implied warranty of MERCHANTABILITY or FIT‐
372 NESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
373 more details.
374 You should have received a copy of the GNU General Public License along
376 with GDBM. If not, see <http://gnu.org/licenses/gpl.html>
377
379 You may contact the original author by:
380 e-mail: phil@cs.wwu.edu
381 us-mail: Philip A. Nelson
382 Computer Science Department
383 Western Washington University
384 Bellingham, WA 98226
385 You may contact the current maintainers by:
387 e-mail: downsj@downsj.com
388 and
389 e-mail: gray@gnu.org
390GDBM January 27, 2020 GDBM(3)