1<!--$Id: dbm.so,v 10.26 2003/10/18 19:15:48 bostic Exp $--> 2<!--Copyright (c) 1997,2008 Oracle. All rights reserved.--> 3<!--See the file LICENSE for redistribution information.--> 4<html> 5<head> 6<title>Berkeley DB: dbm/ndbm</title> 7<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit."> 8<meta name="keywords" content="embedded,database,programmatic,toolkit,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,Java,C,C++"> 9</head> 10<body bgcolor=white> 11<table width="100%"><tr valign=top> 12<td> 13<b>dbm/ndbm</b> 14</td> 15<td align=right> 16<a href="../api_c/api_core.html"><img src="../images/api.gif" alt="API"></a> 17<a href="../ref/toc.html"><img src="../images/ref.gif" alt="Ref"></a></td> 18</tr></table> 19<hr size=1 noshade> 20<tt> 21<b><pre> 22#define DB_DBM_HSEARCH 1 23#include <db.h> 24<p> 25typedef struct { 26 char *dptr; 27 int dsize; 28} datum; 29<hr size=1 noshade> 30<b>Dbm Functions</b> 31int 32dbminit(char *file); 33<p> 34int 35dbmclose(); 36<p> 37datum 38fetch(datum key); 39<p> 40int 41store(datum key, datum content); 42<p> 43int 44delete(datum key); 45<p> 46datum 47firstkey(void); 48<p> 49datum 50nextkey(datum key); 51<hr size=1 noshade> 52<b>Ndbm Functions</b> 53DBM * 54dbm_open(char *file, int flags, int mode); 55<p> 56void 57dbm_close(DBM *db); 58<p> 59datum 60dbm_fetch(DBM *db, datum key); 61<p> 62int 63dbm_store(DBM *db, datum key, datum content, int flags); 64<p> 65int 66dbm_delete(DBM *db, datum key); 67<p> 68datum 69dbm_firstkey(DBM *db); 70<p> 71datum 72dbm_nextkey(DBM *db); 73<p> 74int 75dbm_error(DBM *db); 76<p> 77int 78dbm_clearerr(DBM *db); 79</pre></b> 80<hr size=1 noshade> 81<b>Description: dbm/ndbm</b> 82<p>The dbm functions are intended to provide high-performance 83implementations and source code compatibility for applications written 84to historic interfaces. They are not recommended for any other purpose. 85The historic dbm database format <b>is not supported</b>, 86and databases previously built using the real dbm libraries 87cannot be read by the Berkeley DB functions.</p> 88<p>To compile dbm applications, replace the application's 89<b>#include</b> of the dbm or ndbm include file (for example, 90<b>#include <dbm.h></b> or <b>#include <ndbm.h></b>) 91with the following two lines:</p> 92<blockquote><pre>#define DB_DBM_HSEARCH 1 93#include <db.h></pre></blockquote> 94<p>and recompile. If the application attempts to load against a dbm library 95(for example, <b>-ldbm</b>), remove the library from the load line.</p> 96<p><b>Key</b> and <b>content</b> parameters are objects described by the 97<b>datum</b> typedef. A <b>datum</b> specifies a string of 98<b>dsize</b> bytes pointed to by <b>dptr</b>. Arbitrary binary data, 99as well as normal text strings, are allowed.</p> 100<b>Dbm Functions</b> 101<p>Before a database can be accessed, it must be opened by dbminit. 102This will open and/or create the database <b>file</b>.db. If created, 103the database file is created read/write by owner only (as described in 104<b>chmod</b>(2)) and modified by the process' umask value at the time 105of creation (see <b>umask</b>(2)). The group ownership of created 106files is based on the system and directory defaults, and is not further 107specified by Berkeley DB.</p> 108<p>A database may be closed, and any held resources released, by calling 109dbmclose.</p> 110<p>Once open, the data stored under a key is accessed by fetch, and 111data is placed under a key by store. A key (and its associated 112contents) are deleted by delete. A linear pass through all keys 113in a database may be made, in an (apparently) random order, by using 114firstkey and nextkey. The firstkey method will return 115the first key in the database. The nextkey method will return the next 116key in the database.</p> 117<p>The following code will traverse the database:</p> 118<blockquote><pre>for (key = firstkey(); 119 key.dptr != NULL; key = nextkey(key)) { 120 ... 121}</pre></blockquote> 122<b>Ndbm Functions</b> 123<p>Before a database can be accessed, it must be opened by dbm_open. 124This will open and/or create the database file <b>file.db</b>, depending 125on the flags parameter (see <b>open</b>(2)). If created, the database 126file is created with mode <b>mode</b> (as described in <b>chmod</b>(2)) and modified by the process' umask value at the time of creation (see 127<b>umask</b>(2)). The group ownership of created files is based on 128the system and directory defaults, and is not further specified by 129Berkeley DB.</p> 130<p>Once open, the data stored under a key is accessed by dbm_fetch, 131and data is placed under a key by dbm_store. The <b>flags</b> 132field can be either <b>DBM_INSERT</b> or <b>DBM_REPLACE</b>. 133<b>DBM_INSERT</b> will only insert new entries into the database, and will 134not change an existing entry with the same key. <b>DBM_REPLACE</b> will 135replace an existing entry if it has the same key. A key (and its 136associated contents) are deleted by dbm_delete. A linear pass 137through all keys in a database may be made, in an (apparently) random 138order, by using dbm_firstkey and dbm_nextkey. The 139dbm_firstkey method will return the first key in the database. The 140dbm_nextkey method will return the next key in the database.</p> 141<p>The following code will traverse the database:</p> 142<blockquote><pre>for (key = dbm_firstkey(db); 143 key.dptr != NULL; key = dbm_nextkey(db)) { 144 ... 145}</pre></blockquote> 146<b>Compatibility Notes</b> 147<p>The historic dbm library created two underlying database files, 148traditionally named <b>file.dir</b> and <b>file.pag</b>. The Berkeley DB 149library creates a single database file named <b>file.db</b>. 150Applications that are aware of the underlying database filenames may 151require additional source code modifications.</p> 152<p>The historic dbminit function required that the underlying 153<b>.dir</b> and <b>.pag</b> files already exist (empty databases were 154created by first manually creating zero-length <b>.dir</b> and 155<b>.pag</b> files). Applications that expect to create databases using 156this method may require additional source code modifications.</p> 157<p>The historic dbm_dirfno and dbm_pagfno macros are 158supported, but will return identical file descriptors because there is 159only a single underlying file used by the Berkeley DB hashing access method. 160Applications using both file descriptors for locking may require 161additional source code modifications.</p> 162<p>If applications using the dbm function exits without first 163closing the database, it may lose updates because the Berkeley DB library 164buffers writes to underlying databases. Such applications will require 165additional source code modifications to work correctly with the Berkeley DB 166library.</p> 167<b>Dbm Diagnostics</b> 168<p>The dbminit function returns -1 on failure, setting <b>errno</b>, 169and 0 on success.</p> 170<p>The fetch function sets the <b>dptr</b> field of the returned 171<b>datum</b> to NULL on failure, setting <b>errno</b>, 172and returns a non-NULL <b>dptr</b> on success.</p> 173<p>The store function returns -1 on failure, setting <b>errno</b>, 174and 0 on success.</p> 175<p>The delete function returns -1 on failure, setting <b>errno</b>, 176and 0 on success.</p> 177<p>The firstkey function sets the <b>dptr</b> field of the returned 178<b>datum</b> to NULL on failure, setting <b>errno</b>, 179and returns a non-NULL <b>dptr</b> on success.</p> 180<p>The nextkey function sets the <b>dptr</b> field of the returned 181<b>datum</b> to NULL on failure, setting <b>errno</b>, 182and returns a non-NULL <b>dptr</b> on success.</p> 183<br><b>Errors</b> 184<p>The dbminit, fetch, store, delete, firstkey, and nextkey functions may 185fail and return an error for errors specified for other Berkeley DB and C 186library or system functions.</p> 187<b>Ndbm Diagnostics</b> 188<p>The dbm_close method returns non-zero when an error has occurred reading or 189writing the database.</p> 190<p>The dbm_close method resets the error condition on the named database.</p> 191<p>The dbm_open function returns NULL on failure, setting <b>errno</b>, 192and a DBM reference on success.</p> 193<p>The dbm_fetch function sets the <b>dptr</b> field of the returned 194<b>datum</b> to NULL on failure, setting <b>errno</b>, 195and returns a non-NULL <b>dptr</b> on success.</p> 196<p>The dbm_store function returns -1 on failure, setting <b>errno</b>, 1970 on success, and 1 if DBM_INSERT was set and the specified key already 198existed in the database.</p> 199<p>The dbm_delete function returns -1 on failure, setting <b>errno</b>, 200and 0 on success.</p> 201<p>The dbm_firstkey function sets the <b>dptr</b> field of the returned 202<b>datum</b> to NULL on failure, setting <b>errno</b>, 203and returns a non-NULL <b>dptr</b> on success.</p> 204<p>The dbm_nextkey function sets the <b>dptr</b> field of the returned 205<b>datum</b> to NULL on failure, setting <b>errno</b>, 206and returns a non-NULL <b>dptr</b> on success.</p> 207<p>The dbm_close function returns -1 on failure, setting <b>errno</b>, 208and 0 on success.</p> 209<p>The dbm_close function returns -1 on failure, setting <b>errno</b>, 210and 0 on success.</p> 211<br><b>Errors</b> 212<p>The dbm_open, dbm_close, dbm_fetch, dbm_store, dbm_delete, dbm_firstkey, 213and dbm_nextkey functions may fail and return an error for errors 214specified for other Berkeley DB and C library or system functions.</p> 215</tt> 216<table width="100%"><tr><td><br></td><td align=right> 217<a href="../api_c/api_core.html"><img src="../images/api.gif" alt="API"></a><a href="../ref/toc.html"><img src="../images/ref.gif" alt="Ref"></a> 218</td></tr></table> 219<p><font size=1>Copyright (c) 1996,2008 Oracle. All rights reserved.</font> 220</body> 221</html> 222