1GDBM(3) Library Functions Manual GDBM(3)
2
6 GDBM - The GNU database manager. Includes dbm and ndbm compatability.
7 (Version 1.8.)
8
10 #include <gdbm.h>
11 extern gdbm_error
13 gdbm_errno
14 extern char
16 *gdbm_version
17 GDBM_FILE
19 gdbm_open (name, block_size, read_write, mode, fatal_func)
20 char * name;
21 int block_size, read_write, mode;
22 void (*fatal_func) ();
23 void
25 gdbm_close (dbf)
26 GDBM_FILE dbf;
27 int
29 gdbm_store (dbf, key, content, flag)
30 GDBM_FILE dbf;
31 datum key, content;
32 int flag;
33 datum
35 gdbm_fetch (dbf, key)
36 GDBM_FILE dbf;
37 datum key;
38 int
40 gdbm_delete (dbf, key)
41 GDBM_FILE dbf;
42 datum key;
43 datum
45 gdbm_firstkey (dbf)
46 GDBM_FILE dbf;
47 datum
49 gdbm_nextkey (dbf, key)
50 GDBM_FILE dbf;
51 datum key;
52 int
54 gdbm_reorganize (dbf)
55 GDBM_FILE dbf;
56 void
58 gdbm_sync (dbf)
59 GDBM_FILE dbf;
60 int
62 gdbm_exists (dbf, key)
63 GDBM_FILE dbf;
64 datum key;
65 char *
67 gdbm_strerror (errno)
68 gdbm_error errno;
69 int
71 gdbm_setopt (dbf, option, value, size)
72 GDBM_FILE dbf;
73 int option;
74 int *value;
75 int size;
76 int
78 gdbm_fdesc (dbf)
79 GDBM_FILE dbf;
80 DBM Compatability routines:
82 #include <dbm.h>
84 int
86 dbminit (name)
87 char *name;
88 int
90 store (key, content)
91 datum key, content;
92 datum
94 fetch (key)
95 datum key;
96 int
98 delete (key)
99 datum key;
100 datum
102 firstkey ()
103 datum
105 nextkey (key)
106 datum key;
107 int
109 dbmclose ()
110 NDBM Compatability routines:
112 #include <ndbm.h>
114 DBM
116 *dbm_open (name, flags, mode)
117 char *name;
118 int flags, mode;
119 void
121 dbm_close (file)
122 DBM *file;
123 datum
125 dbm_fetch (file, key)
126 DBM *file;
127 datum key;
128 int
130 dbm_store (file, key, content, flags)
131 DBM *file;
132 datum key, content;
133 int flags;
134 int
136 dbm_delete (file, key)
137 DBM *file;
138 datum key;
139 datum
141 dbm_firstkey (file)
142 DBM *file;
143 datum
145 dbm_nextkey (file)
146 DBM *file;
147 int
149 dbm_error (file)
150 DBM *file;
151 int
153 dbm_clearerr (file)
154 DBM *file;
155 int
157 dbm_pagfno (file)
158 DBM *file;
159 int
161 dbm_dirfno (file)
162 DBM *file;
163 int
165 dbm_rdonly (file)
166 DBM *file;
167
171 GNU dbm is a library of routines that manages data files that contain
172 key/data pairs. The access provided is that of storing, retrieval, and
173 deletion by key and a non-sorted traversal of all keys. A process is
174 allowed to use multiple data files at the same time.
175 A process that opens a gdbm file is designated as a "reader" or a
177 "writer". Only one writer may open a gdbm file and many readers may
178 open the file. Readers and writers can not open the gdbm file at the
179 same time. The procedure for opening a gdbm file is:
180 GDBM_FILE dbf;
182 dbf = gdbm_open ( name, block_size, read_write, mode, fatal_func )
184 Name is the name of the file (the complete name, gdbm does not append
186 any characters to this name). Block_size is the size of a single
187 transfer from disk to memory. This parameter is ignored unless the file
188 is a new file. The minimum size is 512. If it is less than 512, dbm
189 will use the stat block size for the file system. Read_write can have
190 one of the following values:
191 GDBM_READER reader
192 GDBM_WRITER writer
193 GDBM_WRCREAT writer - if database does not exist create new one
194 GDBM_NEWDB writer - create new database regardless if one exists
195 For the last three (writers of the database) the following may be added
196 added to read_write by bitwise or: GDBM_SYNC, which causes all database
197 operations to be synchronized to the disk, and GDBM_NOLOCK, which pre‐
198 vents the library from performing any locking on the database file.
199 The option GDBM_FAST is now obsolete, since gdbm defaults to no-sync
200 mode.
201 Mode is the file mode (see chmod(2) and open(2)) if the file is cre‐
202 ated. (*Fatal_func) () is a function for dbm to call if it detects a
203 fatal error. The only parameter of this function is a string. If the
204 value of 0 is provided, gdbm will use a default function.
205 The return value dbf is the pointer needed by all other routines to
207 access that gdbm file. If the return is the NULL pointer, gdbm_open
208 was not successful. The errors can be found in gdbm_errno for gdbm
209 errors and in errno for system errors. (For error codes, see gdbmer‐
210 rno.h.)
211 In all of the following calls, the parameter dbf refers to the pointer
213 returned from gdbm_open.
214 It is important that every file opened is also closed. This is needed
216 to update the reader/writer count on the file. This is done by:
217 gdbm_close (dbf);
219 The database is used by 3 primary routines. The first stores data in
222 the database.
223 ret = gdbm_store ( dbf, key, content, flag )
225 Dbf is the pointer returned by gdbm_open. Key is the key data. Con‐
227 tent is the data to be associated with the key. Flag can have one of
228 the following values:
229 GDBM_INSERT insert only, generate an error if key exists
230 GDBM_REPLACE replace contents if key exists.
231 If a reader calls gdbm_store, the return value will be -1. If called
233 with GDBM_INSERT and key is in the database, the return value will be
234 1. Otherwise, the return value is 0.
235 NOTICE: If you store data for a key that is already in the data base,
237 gdbm replaces the old data with the new data if called with
238 GDBM_REPLACE. You do not get two data items for the same key and you
239 do not get an error from gdbm_store.
240 NOTICE: The size in gdbm is not restricted like dbm or ndbm. Your data
242 can be as large as you want.
243 To search for some data:
246 content = gdbm_fetch ( dbf, key )
248 Dbf is the pointer returned by gdbm_open. Key is the key data.
250 If the dptr element of the return value is NULL, no data was found.
253 Otherwise the return value is a pointer to the found data. The storage
254 space for the dptr element is allocated using malloc(3C). Gdbm does
255 not automatically free this data. It is the programmer's responsibil‐
256 ity to free this storage when it is no longer needed.
257 To search for some data, without retrieving it:
260 ret = gdbm_exists ( dbf, key )
262 Dbf is the pointer returned by gdbm_open. Key is the key data to
264 search for.
265 If the key is found within the database, the return value ret will be
267 true. If nothing appropiate is found, ret will be false. This routine
268 is useful for checking for the existance of a record, without perform‐
269 ing the memory allocation done by gdbm_fetch.
270 To remove some data from the database:
273 ret = gdbm_delete ( dbf, key )
275 Dbf is the pointer returned by gdbm_open. Key is the key data.
277 The return value is -1 if the item is not present or the requester is a
279 reader. The return value is 0 if there was a successful delete.
280 The next two routines allow for accessing all items in the database.
283 This access is not key sequential, but it is guaranteed to visit every
284 key in the database once. (The order has to do with the hash values.)
285 key = gdbm_firstkey ( dbf )
287 nextkey = gdbm_nextkey ( dbf, key )
289 Dbf is the pointer returned by gdbm_open. Key is the key data.
291 The return values are both of type datum. If the dptr element of the
293 return value is NULL, there is no first key or next key. Again notice
294 that dptr points to data allocated by malloc(3C) and gdbm will not free
295 it for you.
296 These functions were intended to visit the database in read-only algo‐
298 rithms, for instance, to validate the database or similar operations.
299 File `visiting' is based on a `hash table'. gdbm_delete re-arranges
301 the hash table to make sure that any collisions in the table do not
302 leave some item `un-findable'. The original key order is NOT guaran‐
303 teed to remain unchanged in ALL instances. It is possible that some
304 key will not be visited if a loop like the following is executed:
305 key = gdbm_firstkey ( dbf );
307 while ( key.dptr ) {
308 nextkey = gdbm_nextkey ( dbf, key );
309 if ( some condition ) {
310 gdbm_delete ( dbf, key );
311 free ( key.dptr );
312 }
313 key = nextkey;
314 }
315 The following routine should be used very infrequently.
318 ret = gdbm_reorganize ( dbf )
320 If you have had a lot of deletions and would like to shrink the space
322 used by the gdbm file, this routine will reorganize the database. Gdbm
323 will not shorten the length of a gdbm file except by using this reorga‐
324 nization. (Deleted file space will be reused.)
325 Unless your database was opened with the GDBM_SYNC flag, gdbm does not
328 wait for writes to be flushed to the disk before continuing. The fol‐
329 lowing routine can be used to guarantee that the database is physically
330 written to the disk file.
331 gdbm_sync ( dbf )
333 It will not return until the disk file state is syncronized with the
335 in-memory state of the database.
336 To convert a gdbm error code into English text, use this routine:
339 ret = gdbm_strerror ( errno )
341 Where errno is of type gdbm_error, usually the global variable
343 gdbm_errno. The appropiate phrase is returned.
344 Gdbm now supports the ability to set certain options on an already open
347 database.
348 ret = gdbm_setopt ( dbf, option, value, size )
350 Where dbf is the return value from a previous call to gdbm_open, and
352 option specifies which option to set. The valid options are currently:
353 GDBM_CACHESIZE - Set the size of the internal bucket
355 cache. This option may only be set once on each GDBM_FILE
356 descriptor, and is set automatically to 100 upon the first
357 access to the database.
358 GDBM_FASTMODE - Set fast mode to either on or off. This
360 allows fast mode to be toggled on an already open and
361 active database. value (see below) should be set to either
362 TRUE or FALSE. This option is now obsolete.
363 GDBM_SYNCMODE - Turn on or off file system synchronization opera‐
365 tions.
366 This setting defaults to off; value (see below) should be set to
367 either
368 TRUE or FALSE.
369 GDBM_CENTFREE - Set central free block pool to either on or off.
371 The default is off, which is how previous versions of Gdbm
372 handled free blocks. If set, this option causes all subsequent free
373 blocks to be placed in the global pool, allowing (in thoery)
374 more file space to be reused more quickly. value (see below) should
375 be set to either TRUE or FALSE.
376 NOTICE: This feature is still under study.
377 GDBM_COALESCEBLKS - Set free block merging to either on or off.
379 The default is off, which is how previous versions of Gdbm
380 handled free blocks. If set, this option causes adjacent free blocks
381 to be merged. This can become a CPU expensive process with time,
382 though,
383 especially if used in conjunction with GDBM_CENTFREE. value
384 (see below) should be set to either TRUE or FALSE.
385 NOTICE: This feature is still under study.
386 value is the value to set option to, specified as an integer pointer.
388 size is the size of the data pointed to by value. The return value
389 will be -1 upon failure, or 0 upon success. The global variable
390 gdbm_errno will be set upon failure.
391 For instance, to set a database to use a cache of 10, after opening it
393 with gdbm_open, but prior to accessing it in any way, the following
394 code could be used:
395 int value = 10;
397 ret = gdbm_setopt( dbf, GDBM_CACHESIZE, &value, sizeof(int));
399 If the database was opened with the GDBM_NOLOCK flag, the user may wish
402 to perform their own file locking on the database file in order to pre‐
403 vent multiple writers operating on the same file simultaneously.
404 In order to support this, the gdbm_fdesc routine is provided.
406 ret = gdbm_fdesc ( dbf )
408 Where dbf is the return value from a previous call to gdbm_open. The
410 return value will be the file descriptor of the database.
411 The following two external variables may be useful:
413 gdbm_errno is the variable that contains more information about gdbm
415 errors. (gdbm.h has the definitions of the error values and defines
416 gdbm_errno as an external variable.)
417 gdbm_version is the string containing the version information.
418 There are a few more things of interest. First, gdbm files are not
421 "sparse". You can copy them with the UNIX cp(1) command and they will
422 not expand in the copying process. Also, there is a compatibility mode
423 for use with programs that already use UNIX dbm. In this compatibility
424 mode, no gdbm file pointer is required by the programmer, and only one
425 file may be opened at a time. All users in compatibility mode are
426 assumed to be writers. If the gdbm file is a read only, it will fail
427 as a writer, but will also try to open it as a reader. All returned
428 pointers in datum structures point to data that gdbm WILL free. They
429 should be treated as static pointers (as standard UNIX dbm does).
430
434 This library is accessed by specifying -lgdbm as the last parameter to
435 the compile line, e.g.:
436 gcc -o prog prog.c -lgdbm
438
442 NDBM_LOCK - When the NDBM interface is used, the database file is
443 locked by default. Locking might degrade performance when used on a NFS
444 share. This environment variable can be set to false to tell GDBM not
445 to lock the database file.
446
449 dbm, ndbm
450
453 by Philip A. Nelson and Jason Downs. Copyright (C) 1990 - 1999 Free
454 Software Foundation, Inc.
455 GDBM is free software; you can redistribute it and/or modify it under
457 the terms of the GNU General Public License as published by the Free
458 Software Foundation; either version 1, or (at your option) any later
459 version.
460 GDBM is distributed in the hope that it will be useful, but WITHOUT ANY
462 WARRANTY; without even the implied warranty of MERCHANTABILITY or FIT‐
463 NESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
464 more details.
465 You should have received a copy of the GNU General Public License along
467 with GDBM; see the file COPYING. If not, write to the Free Software
468 Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.
469 You may contact the original author by:
471 e-mail: phil@cs.wwu.edu
472 us-mail: Philip A. Nelson
473 Computer Science Department
474 Western Washington University
475 Bellingham, WA 98226
476 You may contact the current maintainer by:
478 e-mail: downsj@downsj.com
479 5/19/99 GDBM(3)