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