)I$Berkeley DB: dbm/ndbm[P

dbm/ndbm





#define DB_DBM_HSEARCH    1#include <db.h>



typedef struct { char *dptr; int dsize;} datum;




Dbm Functions

intdbminit(char *file);

int dbmclose();

datumfetch(datum key);

int store(datum key, datum content);

intdelete(datum key);

datumfirstkey(void);

datumnextkey(datum key);




Ndbm Functions

DBM **dbm_open(char *file, int flags, int mode);

voiddbm_close(DBM *db);

datumdbm_fetch(DBM *db, datum key);

int8dbm_store(DBM *db, datum key, datum content, int flags);

intdbm_delete(DBM *db, datum key);

datumdbm_firstkey(DBM *db);

datumdbm_nextkey(DBM *db);

intdbm_error(DBM *db);

intdbm_clearerr(DBM *db);





Description



EThe dbm interfaces to the Berkeley DB library are intended to provideBhigh-performance implementations and source code compatibility for,applications written to historic interfaces./They are not recommended for any other purpose.9The historic dbm database format is not supported,;and databases previously built using the real dbm libraries,cannot be read by the Berkeley DB functions.

6To compile dbm applications, replace the application's6#include of the dbm or ndbm include file (e.g.,@#include <dbm.h> or #include <ndbm.h>)with the following two lines:

and recompile.@If the application attempts to load against a dbm library (e.g.,5-ldbm), remove the library from the load line.

DKey and content arguments are objects described by thedatum typedef.EA datum specifies a string of dsize bytes pointed to by dptr.BArbitrary binary data, as well as normal text strings, is allowed.

Dbm Functions

GBefore a database can be accessed, it must be opened by dbminit.9This will open and/or create the database file.db.EIf created, the database file is created read/write by owner only (asEdescribed in chmod(2) and modified by the process' umask value.at the time of creation (see umask(2)).IThe group ownership of created files is based on the system and directory6defaults, and is not further specified by Berkeley DB.

EA database may be closed, and any held resources released, by callingdbmclose.

BOnce open, the data stored under a key is accessed by fetch/and data is placed under a key by store.@A key (and its associated contents) is deleted by delete.?A linear pass through all keys in a database may be made, in an$(apparently) random order, by use of#firstkey and nextkey.:Firstkey will return the first key in the database.EWith any key nextkey will return the next key in the database.

/The following code will traverse the data base:



Ndbm Functions



HBefore a database can be accessed, it must be opened by dbm_open.GThis will open and/or create the database file file.db depending,on the flags parameter (see open(2)).BIf created, the database file is created with mode mode (as@described in chmod(2)) and modified by the process' umask4value at the time of creation (see umask(2)).IThe group ownership of created files is based on the system and directory6defaults, and is not further specified by Berkeley DB.

FOnce open, the data stored under a key is accessed by dbm_fetch3and data is placed under a key by dbm_store.9The flags field can be either DBM_INSERT orDBM_REPLACE.IDBM_INSERT will only insert new entries into the database and will/not change an existing entry with the same key.IDBM_REPLACE will replace an existing entry if it has the same key.1A key (and its associated contents) is deleted bydbm_delete.9A linear pass through all keys in a database may be made,*in an (apparently) random order, by use of+dbm_firstkey and dbm_nextkey.>Dbm_firstkey will return the first key in the database.<Dbm_nextkey will return the next key in the database./The following code will traverse the data base:



Compatibility Notes



?The historic dbm library created two underlying database files,8traditionally named file.dir and file.pag.LThe Berkeley DB library creates a single database file named file.db.EApplications that are aware of the underlying database file names may-require additional source code modifications.

BThe historic dbminit interface required that the underlying@.dir and .pag files already exist (empty databasesCwere created by first manually creating zero-length .dir and.pag files).>Applications that expect to create databases using this method1may require additional source code modifications.

?The historic dbm_dirfno and dbm_pagfno macros areAsupported, but will return identical file descriptors as there isLonly a single underlying file used by the Berkeley DB hashing access method.@Applications using both file descriptors for locking may require%additional source code modifications.

CIf applications using the dbm interface exits without first closingIthe database, it may lose updates because the Berkeley DB library bufferswrites to underlying databases.CSuch applications will require additional source code modifications/to work correctly with the Berkeley DB library.

Dbm Diagnostics



HThe dbminit function returns -1 on failure, setting errno,and 0 on success.

DThe fetch function sets the dptr field of the returned6datum to NULL on failure, setting errno,.and returns a non-NULL dptr on success.

FThe store function returns -1 on failure, setting errno,and 0 on success.

GThe delete function returns -1 on failure, setting errno,and 0 on success.

GThe firstkey function sets the dptr field of the returned6datum to NULL on failure, setting errno,.and returns a non-NULL dptr on success.

FThe nextkey function sets the dptr field of the returned6datum to NULL on failure, setting errno,.and returns a non-NULL dptr on success.



Errors

PIf a fatal error occurs in Berkeley DB, the dbminit function may fail and returnFDB_RUNRECOVERY, at which point all subsequent database calls will alsoreturn DB_RUNRECOVERY.



The fetch)function may fail and return errnoKfor any of the errors specified for the following Berkeley DB and C library functions:6dbm_fetch,and fprintf(3).

The store)function may fail and return errnoKfor any of the errors specified for the following Berkeley DB and C library functions:6dbm_store,and fprintf(3).

The delete)function may fail and return errnoKfor any of the errors specified for the following Berkeley DB and C library functions:6dbm_store,ands fprintf(3).

> The firstkey)function may fail and return errnodKfor any of the errors specified for the following Berkeley DB and C librarys functions:9dbm_firstkey,aandp fprintf(3).o

, The nextkeye)function may fail and return errnoiKfor any of the errors specified for the following Berkeley DB and C librarym functions:8dbm_nextkey,and fprintf(3).&

Ndbm Diagnostics

y

GDbm_error returns non-zero when an error has occurred reading or>writing the database.

iEDbm_clearerr resets the error condition on the named database.e

KThe dbm_open function returns NULL on failure, setting errno,and 0 on success.k

iHThe dbm_fetch function sets the dptr field of the returned6datum to NULL on failure, setting errno,.and returns a non-NULL dptr on success.

aJThe dbm_store function returns -1 on failure, setting errno,G0 on success, and 1 if DBM_INSERT was set and the specified key already)existed in the database.

DKThe dbm_delete function returns -1 on failure, setting errno,)and 0 on success._

eKThe dbm_firstkey function sets the dptr field of the returnedt6datum to NULL on failure, setting errno,.and returns a non-NULL dptr on success.

iJThe dbm_nextkey function sets the dptr field of the returned6datum to NULL on failure, setting errno,.and returns a non-NULL dptr on success.

oJThe dbm_error function returns -1 on failure, setting errno,and 0 on success.o

iMThe dbm_clearerr function returns -1 on failure, setting errno,dand 0 on success.g

b

Errors

.}If a fatal error occurs in Berkeley DB, the dbm_open function may fail and returnuFDB_RUNRECOVERY, at which point all subsequent database calls will alsoreturn DB_RUNRECOVERY.

i8The dbm_open)function may fail and return errnoDB->close,4DB->cursor,/db_open, memset(3), strcat(3), strcpy(3),andt strlen(3).

d9The dbm_closef)function may fail and return errno Kfor any of the errors specified for the following Berkeley DB and C libraryd functions:dbc->dbp->close(3).

t9The dbm_fetchs)function may fail and return errno Kfor any of the errors specified for the following Berkeley DB and C library functions:dbc->dbp->get(3),nandd memset(3).

e9The dbm_store )function may fail and return errno/Kfor any of the errors specified for the following Berkeley DB and C librarye functions:dbc->dbp->put(3),landb memset(3).

:The dbm_delete)function may fail and return errnobKfor any of the errors specified for the following Berkeley DB and C libraryb functions:dbc->dbp->del(3),bandl memset(3).

k<The dbm_firstkey)function may fail and return errnorKfor any of the errors specified for the following Berkeley DB and C library< functions:7DBcursor->c_get,,andu memset(3).

b;The dbm_nextkeye)function may fail and return errnorKfor any of the errors specified for the following Berkeley DB and C libraryo functions:7DBcursor->c_get, ands memset(3).

tmt<˙˙umask(2)).IThe group ownership of created files is based on the system and directory6defaults, and is not further specified by Berkeley DB.

FOnce open, the data stored under a key is accessed by dbm_fetch3and data is placed under a key by dbm_store.9The flags field can be either DBM_INSERT orDBM_REPLACE.IDBM_INSERT will only insert new entries into the database and will/not change an existing entry wit