doc/gdbm.3

   1 .\" This file is part of GDBM.
   2 .\" Copyright (C) 2011 Free Software Foundation, Inc.
   3 .\"
   4 .\" GDBM is free software; you can redistribute it and/or modify
   5 .\" it under the terms of the GNU General Public License as published by
   6 .\" the Free Software Foundation; either version 3, or (at your option)
   7 .\" any later version.
   8 .\"
   9 .\" GDBM is distributed in the hope that it will be useful,
  10 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
  11 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12 .\" GNU General Public License for more details.
  13 .\"
  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/>. */
  16 .TH GDBM 3 "August 9, 2011" "GDBM" "GDBM User Reference"
  17 .ds ve 1.9
  18 .SH NAME
  19 GDBM - The GNU database manager.  Includes \fBdbm\fR and \fBndbm\fR
  20 compatability. (Version \*(ve.)
  21 .SH SYNOPSIS
  22 .nf
  23 .B #include <gdbm.h>
  24 .sp
  25 .BI "extern gdbm_error"  " gdbm_errno";
  26 .br
  27 .BI "extern char *" gdbm_version ;
  28 .br
  29 .BI "GDBM_FILE gdbm_open (const char *" name ", int " block_size ", "
  30 .ti +21
  31 .BI     "int " flags ", int " mode ", "
  32 .ti +21
  33 .BI "void (*" fatal_func ")(const char *))";
  34 .br
  35 .BI "void gdbm_close (GDBM_FILE " dbf ");"
  36 .br
  37 .BI "int gdbm_store (GDBM_FILE " dbf ", datum " key ", datum " content ", int " flag );
  38 .br
  39 .BI "datum gdbm_fetch (GDBM_FILE " dbf ", datum " key );
  40 .br
  41 .BI "int gdbm_delete (GDBM_FILE " dbf ", datum " key );
  42 .br
  43 .BI "datum gdbm_firstkey (GDBM_FILE " dbf ");"
  44 .br
  45 .BI "datum gdbm_nextkey (GDBM_FILE " dbf ", datum " key );
  46 .br
  47 .BI "int gdbm_reorganize (GDBM_FILE " dbf ");"
  48 .br
  49 .BI "void gdbm_sync (GDBM_FILE " dbf ");"
  50 .br
  51 .BI "int gdbm_exists (GDBM_FILE " dbf ", datum " key );
  52 .br
  53 .BI "const char *gdbm_strerror (gdbm_error " errno );
  54 .br
  55 .BI "int gdbm_setopt (GDBM_FILE " dbf ", int " option ", int " value ", int " size );
  56 .br
  57 .BI "int gdbm_fdesc (GDBM_FILE " dbf );
  58 .br
  59 .PP
  60 .SS DBM Compatability routines:
  61 .PP
  62 .B #include <dbm.h>
  63 .sp
  64 .BI "int dbminit (const char *" name ");"
  65 .br
  66 .BI "int store (datum " key ", datum " content );
  67 .br
  68 .BI "datum fetch (datum " key );
  69 .br
  70 .BI "int delete (datum " key );
  71 .br
  72 .BI "datum firstkey (void);"
  73 .br
  74 .BI "datum nextkey (datum " key );
  75 .br
  76 .BI "int dbmclose (void);"
  77 .PP
  78 .SS NDBM Compatability routines:
  79 .PP
  80 .B #include <ndbm.h>
  81 .sp
  82 .BI "DBM *dbm_open (const char *" name ", int " flags ", int " mode );
  83 .br
  84 .BI "void dbm_close (DBM *" file );
  85 .BI datum dbm_fetch (DBM *" file ", datum " key );
  86 .br
  87 .BI "int dbm_store (DBM *" file ", datum " key ", datum " content ", int " flags );
  88 .br
  89 .BI "int dbm_delete (DBM *" file ", datum " key );
  90 .br
  91 .BI "datum dbm_firstkey (DBM *" file );
  92 .br
  93 .BI "datum dbm_nextkey (DBM *" file ", datum " key );
  94 .br
  95 .BI "int dbm_error (DBM *" file );
  96 .br
  97 .BI "int dbm_clearerr (DBM *" file );
  98 .br
  99 .BI "int dbm_pagfno (DBM *" file );
 100 .br
 101 .BI "int dbm_dirfno (DBM *" file );
 102 .br
 103 .BI "int dbm_rdonly (DBM *" file );
 104 .SH DESCRIPTION
 105 \fBGNU dbm\fR is a library of routines that manages data files that contain
 106 key/data pairs.  The access provided is that of storing,
 107 retrieval, and deletion by key and a non-sorted traversal of all
 108 keys.  A process is allowed to use multiple data files at the
 109 same time.
 110
 111 This manpage is a short description of the \fBGDBM\fR library.
 112 For a detailed discussion, including examples of the configuration and
 113 usage recommendations, refer to the \fBGDBM Manual\fR available in
 114 Texinfo format.  To access it, run:
 115
 116   \fBinfo gdbm\fR
 117
 118 Should any discrepancies occur between this manpage and the
 119 \fBGDBM Manual\fR, the later shall be considered the authoritative
 120 source.
 121
 122 A process that opens a gdbm file is designated as a "reader" or a
 123 "writer".  Only one writer may open a gdbm file and many readers may
 124 open the file.  Readers and writers can not open the gdbm file at the
 125 same time. The procedure for opening a gdbm file is:
 126
 127 .BI "GDBM_FILE gdbm_open (const char *" name ", int " block_size ", "
 128 .ti +21
 129 .BI     "int " flags ", int " mode ", "
 130 .ti +21
 131 .BI "void (*" fatal_func ")(const char *))";
 132
 133 \fIName\fR is the name of the file (the complete name,
 134 gdbm does not append any characters to this name).  \fIBlock_size\fR is
 135 the size of a single transfer from disk to memory. This parameter is
 136 ignored unless the file is a new file.  The minimum size is 512.  If
 137 it is less than 512, dbm will use the stat block size for the file system.
 138 \fIRead_write\fR can have one of the following values:
 139 .TP
 140 .B GDBM_READER
 141 reader
 142 .TP
 143 .B GDBM_WRITER
 144 writer
 145 .TP
 146 .B GDBM_WRCREAT
 147 writer - if database does not exist create new one
 148 .TP
 149 .B GDBM_NEWDB
 150 writer - create new database regardless if one exists
 151 .PP
 152 The \fBGDBM_NOMMAP\fR added to \fIread_write\fR by bitwise or instructs
 153 \fBgdbm_open\fR to disable the use of
 154 .BR mmap (2).
 155 .PP
 156 For the last three (writers of the database) the following may be added
 157 added to \fIread_write\fR by bitwise or:
 158 .TP
 159 .B GDBM_SYNC
 160 Causes all database operations to be synchronized to the disk,
 161 .TP
 162 .B GDBM_NOLOCK
 163 Pevents the library from performing any locking on the database file.
 164 .PP
 165 The option
 166 .B GDBM_FAST
 167 is now obsolete, since gdbm defaults to no-sync mode.
 168 .PP
 169 \fIMode\fR is the file mode (see \fBchmod(2)\fR and \fBopen(2)\fR) if the
 170 file is created. \fI(*Fatal_func) ()\fR is a function for dbm to call
 171 if it detects a fatal error. The only parameter of this function is a string.
 172 If the value of 0 is provided, \fBgdbm\fR will use a default function.
 173
 174 The return value is the pointer needed by all other routines to
 175 access that gdbm file.  If the return is the NULL pointer, \fBgdbm_open\fR
 176 was not successful.  The errors can be found in \fIgdbm_errno\fR for gdbm
 177 errors and in \fIerrno\fR for system errors.  (For error codes, see
 178 gdbmerrno.h.)
 179
 180 In all of the following calls, the parameter \fIdbf\fR refers to the pointer
 181 returned from \fBgdbm_open\fR.
 182
 183 It is important that every file opened is also closed.  This is needed to
 184 update the reader/writer count on the file.  This is done by:
 185
 186 .BI "void gdbm_close (GDBM_FILE " dbf ");"
 187
 188 The database is used by 3 primary routines.  The first stores data in the
 189 database.
 190
 191 .BI "int gdbm_store (GDBM_FILE " dbf ", datum " key ", datum " content ", int " flag );
 192
 193 \fIDbf\fR is the pointer returned by \fBgdbm_open\fR.  \fIKey\fR is the
 194 key data.  \fIContent\fR is the data to be associated with the \fIkey\fR.
 195 \fIFlag\fR can have one of the following values:
 196 .TP
 197 .B GDBM_INSERT
 198 Insert only, generate an error if key exists;
 199 .TP
 200 .B GDBM_REPLACE
 201 Replace contents if key exists.
 202 .PP
 203 If a reader calls \fBgdbm_store\fR, the return value will be  -1.
 204 If called with \fBGDBM_INSERT\fR and \fIkey\fR is in the database, the return
 205 value will be 1.  Otherwise, the return value is 0.
 206
 207 \fINOTICE: If you store data for a key that is already in the data base,
 208 \fBgdbm\fI replaces the old data with the new data if called with \fBGDBM_REPLACE\fI.
 209 You do not get two data items for the same key and you do not get an
 210 error from \fBgdbm_store\fI.
 211
 212 NOTICE: The size in \fBgdbm\fI is not restricted like in \fBdbm\fI or \fBndbm\fI.  Your data
 213 can be as large as you want.\fR
 214
 215 To search for some data, use:
 216
 217 .BI "datum gdbm_fetch (GDBM_FILE " dbf ", datum " key );
 218
 219 \fIDbf\fR is the pointer returned by \fBgdbm_open\fR.  \fIKey\fR is
 220 the key data.
 221
 222 If the \fIdptr\fR element of the return value is NULL, no data was
 223 found.  Otherwise the return value is a pointer to the found data.
 224 The storage space for the \fIdptr\fR element is allocated using
 225 \fBmalloc(3)\fR.  \fBGdbm\fI does not automatically free this data.
 226 It is the programmer's responsibility to free this storage when it is
 227 no longer needed.
 228
 229 To search for some data, without retrieving it:
 230
 231 .BI "int gdbm_exists (GDBM_FILE " dbf ", datum " key );
 232
 233 \fIDbf\fR is the pointer returned by \fBgdbm_open\fR.  \fIKey\fR is
 234 the key data to search for.
 235
 236 If the \fIkey\fR is found within the database, the return value
 237 will be true.  If nothing appropiate is found, false is returned.
 238 This routine is useful for checking for the existence of a record,
 239 without performing the memory allocation done by \fBgdbm_fetch\fR.
 240 .PP
 241 To remove some data from the database:
 242
 243 .BI "int gdbm_delete (GDBM_FILE " dbf ", datum " key );
 244
 245 \fIDbf\fR is the pointer returned by \fBgdbm_open\fR.  \fIKey\fR is the
 246 key data.
 247
 248 The return value is -1 if the item is not present or the requester is a reader.
 249 The return value is 0 if there was a successful delete.
 250
 251 The next two routines allow for accessing all items in the database.  This
 252 access is not key sequential, but it is guaranteed to visit every key in
 253 the database once.  (The order has to do with the hash values.)
 254
 255 .BI "datum gdbm_firstkey (GDBM_FILE " dbf ");"
 256 .br
 257 .BI "datum gdbm_nextkey (GDBM_FILE " dbf ", datum " key );
 258
 259 \fIDbf\fR is the pointer returned by \fBgdbm_open\fR. \fIKey\fR is the
 260 key data.
 261
 262 The return values are both of type \fBdatum\fR.  If the \fIdptr\fR
 263 element of the return value is NULL, there is no first key or next key.
 264 Again notice that \fIdptr\fR points to data allocated by \fBmalloc(3)\fR
 265 and \fBgdbm\fR will not free it for you.
 266
 267 These functions were intended to visit the database in read-only algorithms,
 268 for instance, to validate the database or similar operations.
 269
 270 File `visiting' is based on a `hash table'.  \fIgdbm_delete\fR re-arranges the
 271 hash table to make sure that any collisions in the table do not leave some item
 272 `un-findable'.  The original key order is NOT guaranteed to remain unchanged in
 273 ALL instances.  It is possible that some key will not be visited if a loop like
 274 the following is executed:
 275 .sp
 276 .nf
 277 .in +5
 278 key = gdbm_firstkey (dbf);
 279 while (key.dptr)
 280   {
 281     nextkey = gdbm_nextkey (dbf, key);
 282     if (some condition)
 283       gdbm_delete ( dbf, key );
 284     free (key.dptr);
 285     key = nextkey;
 286   }
 287 .in
 288 .fi
 289 .PP
 290 The following routine should be used very infrequently.
 291
 292 .BI "int gdbm_reorganize (GDBM_FILE " dbf ");"
 293
 294 If you have had a lot of deletions and would like to shrink the space
 295 used by the \fBgdbm\fR file, this routine will reorganize the database.
 296 \fBGdbm\fR will not shorten the length of a \fBgdbm\fR file except by
 297 using this reorganization.  (Deleted file space will be reused.)
 298
 299 Unless your database was opened with the \fBGDBM_SYNC\fR flag, \fBgdbm\fR does not
 300 wait for writes to be flushed to the disk before continuing.
 301 The following routine can be used to guarantee that the database is
 302 physically written to the disk file.
 303
 304 .BI "void gdbm_sync (GDBM_FILE " dbf ");"
 305
 306 It will not return until the disk file state is syncronized with the
 307 in-memory state of the database.
 308
 309 To convert a \fBgdbm\fR error code into English text, use this routine:
 310
 311 .BI "const char *gdbm_strerror (gdbm_error " errno );
 312
 313 \fBGdbm\fR now supports the ability to set certain options on an
 314 already open database.
 315
 316 .BI "int gdbm_setopt (GDBM_FILE " dbf ", int " option ", int " value ", int " size );
 317
 318 Where \fIdbf\fR is the return value from a previous call to \fBgdbm_open\fR,
 319 and \fIoption\fR specifies which option to set.  The valid options are
 320 currently:
 321 .TP
 322 .B GDBM_CACHESIZE
 323 Set the size of the internal bucket cache. This option may only be set once
 324 on each \fIGDBM_FILE\fR descriptor, and is set automatically to 100 upon the
 325 first access to the database.
 326 .TP
 327 .B GDBM_FASTMODE
 328  Set \fBfast mode\fR to either on or off.  This allows \fBfast mode\fR to
 329 be toggled on an already open and active database. \fIvalue\fR (see below)
 330 should be set to either TRUE or FALSE.  \fIThis option is now obsolete.\fR
 331 .TP
 332 .B GDBM_SYNCMODE
 333 Turn on or off file system synchronization operations.  This setting defaults
 334 to off; \fIvalue\fR (see below) should be set to either TRUE or FALSE.
 335 .TP
 336 .B GDBM_CENTFREE
 337 Set \fBcentral free block pool\fR to either on or off.
 338 The default is off, which is how previous versions of \fBGdbm\fR
 339 handled free blocks. If set, this option causes all subsequent free
 340 blocks to be placed in the \fBglobal\fR pool, allowing (in thoery)
 341 more file space to be reused more quickly. \fIvalue\fR (see below) should
 342 be set to either TRUE or FALSE.
 343 \fINOTICE: This feature is still under study.\fR
 344 .TP
 345 .B GDBM_COALESCEBLKS
 346 Set \fBfree block merging\fR to either on or off.
 347 The default is off, which is how previous versions of \fBGdbm\fR
 348 handled free blocks. If set, this option causes adjacent free blocks
 349 to be merged.  This can become a CPU expensive process with time, though,
 350 especially if used in conjunction with \fBGDBM_CENTFREE\fR. \fIvalue\fR
 351 (see below) should be set to either TRUE or FALSE.
 352 \fINOTICE: This feature is still under study.\fR
 353 .PP
 354 \fIvalue\fR is the value to set \fIoption\fR to, specified as an integer
 355 pointer.  \fIsize\fR is the size of the data pointed to by \fIvalue\fR.
 356 The return value will be -1 upon failure, or 0 upon success.  The global
 357 variable \fIgdbm_errno\fR will be set upon failure.
 358
 359 For instance, to set a database to use a cache of 10, after opening it
 360 with \fBgdbm_open\fR, but prior to accessing it in any way, the following
 361 code could be used:
 362 .sp
 363 .nf
 364 .in +5
 365 int value = 10;
 366
 367 ret = gdbm_setopt( dbf, GDBM_CACHESIZE, &value, sizeof(int));
 368 .in
 369 .fi
 370 .PP
 371 If the database was opened with the \fBGDBM_NOLOCK\fR flag, the user may
 372 wish to perform their own file locking on the database file in order to
 373 prevent multiple writers operating on the same file simultaneously.
 374
 375 In order to support this, the \fIgdbm_fdesc\fR routine is provided.
 376
 377 .BI "int gdbm_fdesc (GDBM_FILE " dbf );
 378
 379 Where \fIdbf\fR is the return value from a previous call to \fBgdbm_open\fR.
 380 The return value will be the file descriptor of the database.
 381
 382 The following two external variables may be useful:
 383
 384 \fIgdbm_errno\fR is the variable that contains more information about
 385 gdbm errors.  (gdbm.h has the definitions of the error values and
 386 defines gdbm_errno as an external variable.)
 387
 388 \fIgdbm_version\fR is the string containing the version information.
 389
 390 There are a few more things of interest.  First, \fBgdbm\fR files are
 391 not "sparse".  You can copy them with the UNIX \fBcp(1)\fR command and
 392 they will not expand in the copying process.  Also, there is a
 393 compatibility mode for use with programs that already use UNIX
 394 \fBdbm\fR.  In this compatibility mode, no \fRgdbm\fR file pointer is
 395 required by the programmer, and only one file may be opened at a time.
 396 All users in compatibility mode are assumed to be writers.  If the
 397 \fBgdbm\fR file is a read only, it will fail as a writer, but will
 398 also try to open it as a reader.  All returned pointers in datum
 399 structures point to data that \fBgdbm\fR WILL free.  They should be
 400 treated as static pointers (as standard UNIX \fBdbm\fR does).
 401 .SH LINKING
 402 This library is accessed by specifying \fI-lgdbm\fR as the last
 403 parameter to the compile line, e.g.:
 404 .sp
 405 .nf
 406 .in +5
 407 gcc -o prog prog.c -lgdbm
 408 .in
 409 .fi
 410 .PP
 411 If you wish to use the \fBdbm\fR or \fBndbm\fR compatibility routines,
 412 you must link in the \fIgdbm_compat\fR library as well.  For example:
 413 .sp
 414 .nf
 415 .in +5
 416 gcc -o prog proc.c -lgdbm -lgdbm_compat
 417 .in
 418 .fi
 419 .\" .SH BUGS
 420
 421 .SH "BUG REPORTS"
 422 Send bug reports to <bug-gdbm@gnu.org>.
 423 .SH "SEE ALSO"
 424 dbm, ndbm
 425 .SH AUTHOR
 426 by Philip A. Nelson, Jason Downs and Sergey Poznyakoff.
 427 .SH COPYRIGHT
 428 Copyright \(co 1990 - 2011 Free Software Foundation, Inc.
 429
 430 GDBM is free software; you can redistribute it and/or modify
 431 it under the terms of the GNU General Public License as published by
 432 the Free Software Foundation; either version 1, or (at your option)
 433 any later version.
 434
 435 GDBM is distributed in the hope that it will be useful,
 436 but WITHOUT ANY WARRANTY; without even the implied warranty of
 437 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 438 GNU General Public License for more details.
 439
 440 You should have received a copy of the GNU General Public License
 441 along with GDBM.  If not, see <http://gnu.org/licenses/gpl.html>
 442 .SH CONTACTS
 443 You may contact the original author by:
 444 .br
 445    e-mail:  phil@cs.wwu.edu
 446 .br
 447   us-mail:  Philip A. Nelson
 448 .br
 449 Computer Science Department
 450 .br
 451 Western Washington University
 452 .br
 453 Bellingham, WA 98226
 454
 455 You may contact the current maintainers by:
 456 .br
 457    e-mail:  downsj@downsj.com
 458 .br
 459 and
 460    e-mail:  gray@gnu.org
 461
 462 .\" Local variables:
 463 .\" eval: (add-hook 'write-file-hooks 'time-stamp)
 464 .\" time-stamp-start: ".TH GDBM 3 \""
 465 .\" time-stamp-format: "%:B %:d, %:y"
 466 .\" time-stamp-end: "\""
 467 .\" time-stamp-line-limit: 20
 468 .\" end: