1<?xml version="1.0" encoding="UTF-8" standalone="no"?> 2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 3<html xmlns="http://www.w3.org/1999/xhtml"> 4 <head> 5 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> 6 <title>dbm/ndbm</title> 7 <link rel="stylesheet" href="apiReference.css" type="text/css" /> 8 <meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /> 9 <link rel="start" href="index.html" title="Berkeley DB C API Reference" /> 10 <link rel="up" href="historic.html" title="Appendix 2. Historic Interfaces" /> 11 <link rel="prev" href="historic.html" title="Appendix 2. Historic Interfaces" /> 12 <link rel="next" href="hsearch.html" title="hsearch" /> 13 </head> 14 <body> 15 <div class="navheader"> 16 <table width="100%" summary="Navigation header"> 17 <tr> 18 <th colspan="3" align="center">dbm/ndbm</th> 19 </tr> 20 <tr> 21 <td width="20%" align="left"><a accesskey="p" href="historic.html">Prev</a> </td> 22 <th width="60%" align="center">Appendix 2. 23 Historic Interfaces 24 </th> 25 <td width="20%" align="right"> <a accesskey="n" href="hsearch.html">Next</a></td> 26 </tr> 27 </table> 28 <hr /> 29 </div> 30 <div class="sect1" lang="en" xml:lang="en"> 31 <div class="titlepage"> 32 <div> 33 <div> 34 <h2 class="title" style="clear: both"><a id="dbm"></a>dbm/ndbm</h2> 35 </div> 36 </div> 37 </div> 38 <pre class="programlisting">#define DB_DBM_HSEARCH 1 39#include <db.h> 40 41typedef struct { 42 char *dptr; 43 int dsize; 44} datum; </pre> 45 <p> 46<span class="bold"><strong>Dbm Functions</strong></span> 47</p> 48 <pre class="programlisting">int 49dbminit(char *file); 50 51int 52dbmclose(); 53 54datum 55fetch(datum key); 56 57int 58store(datum key, datum content); 59 60int 61delete(datum key); 62 63datum 64firstkey(void); 65 66datum 67nextkey(datum key);</pre> 68 <p> 69<span class="bold"><strong>Ndbm Functions</strong></span> 70</p> 71 <pre class="programlisting">DBM * 72dbm_open(char *file, int flags, int mode); 73 74void 75dbm_close(DBM *db); 76 77datum 78dbm_fetch(DBM *db, datum key); 79 80int 81dbm_store(DBM *db, datum key, datum content, int flags); 82 83int 84dbm_delete(DBM *db, datum key); 85 86datum 87dbm_firstkey(DBM *db); 88 89datum 90dbm_nextkey(DBM *db); 91 92int 93dbm_error(DBM *db); 94 95int 96dbm_clearerr(DBM *db); </pre> 97 <p> 98 The dbm functions are intended to provide high-performance 99 implementations and source code compatibility for applications written 100 to historic interfaces. They are not recommended for any other 101 purpose. The historic dbm database format <span class="bold"><strong>is not 102 supported</strong></span>, and databases previously built using the real 103 dbm libraries cannot be read by the Berkeley DB functions. 104 </p> 105 <p> 106 To compile dbm applications, replace the application's <span class="bold"><strong>#include</strong></span> of the dbm or ndbm include file (for 107 example, <span class="bold"><strong>#include <dbm.h></strong></span> or 108 <span class="bold"><strong>#include <ndbm.h></strong></span>) with the 109 following two lines: 110 </p> 111 <pre class="programlisting">#define DB_DBM_HSEARCH 1 112#include <db.h></pre> 113 <p> 114 and recompile. If the application attempts to load against a dbm 115 library (for example, <span class="bold"><strong>-ldbm</strong></span>), remove 116 the library from the load line. 117 </p> 118 <p> 119 <span class="bold"><strong>Key</strong></span> and 120 <span class="bold"><strong>content</strong></span> parameters are objects described by the 121 <span class="bold"><strong>datum</strong></span> typedef. A 122 <span class="bold"><strong>datum</strong></span> specifies a string of 123 <span class="bold"><strong>dsize</strong></span> bytes pointed to by 124 <span class="bold"><strong>dptr</strong></span>. Arbitrary binary data, as well as normal 125 text strings, are allowed. 126 </p> 127 <div class="sect2" lang="en" xml:lang="en"> 128 <div class="titlepage"> 129 <div> 130 <div> 131 <h3 class="title"><a id="dbmfunctions"></a>Dbm Functions</h3> 132 </div> 133 </div> 134 </div> 135 <p> 136 Before a database can be accessed, it must be opened by dbminit. This 137 will open and/or create the database 138 <span class="bold"><strong>file.db</strong></span>. If created, the database file is 139 created read/write by owner only (as described in 140 <span class="bold"><strong>chmod</strong></span>(2)) and modified by the process' umask 141 value at the time of creation (see 142 <span class="bold"><strong>umask</strong></span>(2)). The group ownership of created 143 files is based on the system and directory defaults, and is not 144 further specified by Berkeley DB. 145 </p> 146 <p> 147 A database may be closed, and any held resources released, by calling 148 dbmclose. 149 </p> 150 <p> 151 Once open, the data stored under a key is accessed by fetch, and data 152 is placed under a key by store. A key (and its associated contents) 153 are deleted by delete. A linear pass through all keys in a database 154 may be made, in an (apparently) random order, by using firstkey and 155 nextkey. The firstkey method will return the first key in the 156 databaseThe nextkey method will return the next key in satabase. 157 </p> 158 <p> 159 The following code will traverse the database: 160 </p> 161 <pre class="programlisting">for (key = firstkey(key); 162 key.dptr != NULL; key = nextkey(key)) { 163 ... 164} </pre> 165 </div> 166 <div class="sect2" lang="en" xml:lang="en"> 167 <div class="titlepage"> 168 <div> 169 <div> 170 <h3 class="title"><a id="ndbmfunctions"></a>Ndbm Functions</h3> 171 </div> 172 </div> 173 </div> 174 <p> 175 Before a database can be accessed, it must be opened by dbm_open. This 176 will open and/or create the database file 177 <span class="bold"><strong>file.db</strong></span>, depending on the flags parameter (see 178 <span class="bold"><strong>open</strong></span>(2)). If created, the database 179 file is created with mode <span class="bold"><strong>mode</strong></span> (as 180 described in <span class="bold"><strong>chmod</strong></span>(2)) and modified 181 by the process' umask value at the time of creation (see <span class="bold"><strong>umask</strong></span>(2)). The group ownership of created 182 files is based on the system and directory defaults, and is not 183 further specified by Berkeley DB. 184 </p> 185 <p> 186 Once open, the data stored under a key is accessed by dbm_fetch, and 187 data is placed under a key by dbm_store. The 188 <span class="bold"><strong>flags</strong></span> field can be either 189 <span class="bold"><strong>DBM_INSERT</strong></span> or 190 <span class="bold"><strong>DBM_REPLACE</strong></span>. 191 <span class="bold"><strong>DBM_INSERT</strong></span> will only insert new entries into 192 the database, and will not change an existing entry with the same key. 193 <span class="bold"><strong>DBM_REPLACE</strong></span> will replace an existing 194 entry if it has the same key. A key (and its associated contents) are 195 deleted by dbm_delete. A linear pass through all keys in a database 196 may be made, in an (apparently) random order, by using dbm_firstkey 197 and dbm_nextkey. The dbm_firstkey method will return the first key in 198 the database. The dbm_nextkey method will return the next key in the 199 database. 200 </p> 201 <p> 202 The following code will traverse the database: 203 </p> 204 <pre class="programlisting">for (key = dbm_firstkey(db); 205 key.dptr != NULL; key = dbm_nextkey(db)) { 206 ... 207} </pre> 208 </div> 209 <div class="sect2" lang="en" xml:lang="en"> 210 <div class="titlepage"> 211 <div> 212 <div> 213 <h3 class="title"><a id="dbm_compat_notes"></a>Compatibility Notes</h3> 214 </div> 215 </div> 216 </div> 217 <p> 218 The historic dbm library created two underlying database files, 219 traditionally named <span class="bold"><strong>file.dir</strong></span> and 220 <span class="bold"><strong>file.pag</strong></span>. The Berkeley DB library 221 creates a single database file named <span class="bold"><strong>file.db</strong></span>. Applications that are aware of the 222 underlying database filenames may require additional source code 223 modifications. 224 </p> 225 <p> 226 The historic dbminit function required that the underlying <span class="bold"><strong>.dir</strong></span> and <span class="bold"><strong>.pag</strong></span> 227 files already exist (empty databases were created by first manually 228 creating zero-length <span class="bold"><strong>.dir</strong></span> and 229 <span class="bold"><strong>.pag</strong></span> files). Applications that 230 expect to create databases using this method may require additional 231 source code modifications. 232 </p> 233 <p> 234 The historic dbm_dirfno and dbm_pagfno macros are supported, but will 235 return identical file descriptors because there is only a single 236 underlying file used by the Berkeley DB hashing access method. 237 Applications using both file descriptors for locking may require 238 additional source code modifications. 239 </p> 240 <p> 241 If applications using the dbm function exits without first closing the 242 database, it may lose updates because the Berkeley DB library buffers 243 writes to underlying databases. Such applications will require 244 additional source code modifications to work correctly with the 245 Berkeley DB library. 246 </p> 247 </div> 248 <div class="sect2" lang="en" xml:lang="en"> 249 <div class="titlepage"> 250 <div> 251 <div> 252 <h3 class="title"><a id="dbm_diagnostics"></a>Dbm Diagnostics</h3> 253 </div> 254 </div> 255 </div> 256 <p> 257 The dbminit function returns -1 on failure, setting <span class="bold"><strong>errno</strong></span>, and 0 on success. 258 </p> 259 <p> 260 The fetch function sets the <span class="bold"><strong>dptr</strong></span> 261 field of the returned <span class="bold"><strong>datum</strong></span> to NULL 262 on failure, setting <span class="bold"><strong>errno</strong></span>, and 263 returns a non-NULL <span class="bold"><strong>dptr</strong></span> on success. 264 </p> 265 <p> 266 The store function returns -1 on failure, setting <span class="bold"><strong>errno</strong></span>, and 0 on success. 267 </p> 268 <p> 269 The delete function returns -1 on failure, setting <span class="bold"><strong>errno</strong></span>, and 0 on success. 270 </p> 271 <p> 272 The firstkey function sets the <span class="bold"><strong>dptr</strong></span> 273 field of the returned <span class="bold"><strong>datum</strong></span> to NULL 274 on failure, setting <span class="bold"><strong>errno</strong></span>, and 275 returns a non-NULL <span class="bold"><strong>dptr</strong></span> on success. 276 </p> 277 <p> 278 The nextkey function sets the <span class="bold"><strong>dptr</strong></span> 279 field of the returned <span class="bold"><strong>datum</strong></span> to NULL 280 on failure, setting <span class="bold"><strong>errno</strong></span>, and 281 returns a non-NULL <span class="bold"><strong>dptr</strong></span> on success. 282 </p> 283 </div> 284 <div class="sect2" lang="en" xml:lang="en"> 285 <div class="titlepage"> 286 <div> 287 <div> 288 <h3 class="title"><a id="dbm_errors"></a>Dbm Errors</h3> 289 </div> 290 </div> 291 </div> 292 <p> 293 The dbminit, fetch, store, delete, firstkey, and nextkey functions may 294 fail and return an error for errors specified for other Berkeley DB 295 and C library or system functions. 296 </p> 297 </div> 298 <div class="sect2" lang="en" xml:lang="en"> 299 <div class="titlepage"> 300 <div> 301 <div> 302 <h3 class="title"><a id="ndbm_diagnostics"></a>Ndbm Diagnostics</h3> 303 </div> 304 </div> 305 </div> 306 <p> 307 The dbm_close method returns non-zero when an error has occurred 308 reading or writing the database. 309 </p> 310 <p> 311 The dbm_close method resets the error condition on the named database. 312 </p> 313 <p> 314 The dbm_open function returns NULL on failure, setting <span class="bold"><strong>errno</strong></span>, and a DBM reference on success. 315 </p> 316 <p> 317 The dbm_fetch function sets the <span class="bold"><strong>dptr</strong></span> 318 field of the returned <span class="bold"><strong>datum</strong></span> to NULL 319 on failure, setting <span class="bold"><strong>errno</strong></span>, and 320 returns a non-NULL <span class="bold"><strong>dptr</strong></span> on success. 321 </p> 322 <p> 323 The dbm_store function returns -1 on failure, setting <span class="bold"><strong>errno</strong></span>, 0 on success, and 1 if DBM_INSERT was 324 set and the specified key already existed in the database. 325 </p> 326 <p> 327 The dbm_delete function returns -1 on failure, setting <span class="bold"><strong>errno</strong></span>, and 0 on success. 328 </p> 329 <p> 330 The dbm_firstkey function sets the <span class="bold"><strong>dptr</strong></span> field of the returned <span class="bold"><strong>datum</strong></span> to NULL on failure, setting <span class="bold"><strong>errno</strong></span>, and returns a non-NULL <span class="bold"><strong>dptr</strong></span> on success. 331 </p> 332 <p> 333 The dbm_nextkey function sets the <span class="bold"><strong>dptr</strong></span> field of the returned <span class="bold"><strong>datum</strong></span> to NULL on failure, setting <span class="bold"><strong>errno</strong></span>, and returns a non-NULL <span class="bold"><strong>dptr</strong></span> on success. 334 </p> 335 <p> 336 The dbm_close function returns -1 on failure, setting <span class="bold"><strong>errno</strong></span>, and 0 on success. 337 </p> 338 <p> 339 The dbm_close function returns -1 on failure, setting <span class="bold"><strong>errno</strong></span>, and 0 on success. 340 </p> 341 </div> 342 <div class="sect2" lang="en" xml:lang="en"> 343 <div class="titlepage"> 344 <div> 345 <div> 346 <h3 class="title"><a id="ndbm_errors"></a>Ndbm Errors</h3> 347 </div> 348 </div> 349 </div> 350 <p> 351 The dbm_open, dbm_close, dbm_fetch, dbm_store, dbm_delete, 352 dbm_firstkey, and dbm_nextkey functions may fail and return an error 353 for errors specified for other Berkeley DB and C library or system 354 functions. 355 </p> 356 </div> 357 </div> 358 <div class="navfooter"> 359 <hr /> 360 <table width="100%" summary="Navigation footer"> 361 <tr> 362 <td width="40%" align="left"><a accesskey="p" href="historic.html">Prev</a> </td> 363 <td width="20%" align="center"> 364 <a accesskey="u" href="historic.html">Up</a> 365 </td> 366 <td width="40%" align="right"> <a accesskey="n" href="hsearch.html">Next</a></td> 367 </tr> 368 <tr> 369 <td width="40%" align="left" valign="top">Appendix 2. 370 Historic Interfaces 371 </td> 372 <td width="20%" align="center"> 373 <a accesskey="h" href="index.html">Home</a> 374 </td> 375 <td width="40%" align="right" valign="top"> hsearch</td> 376 </tr> 377 </table> 378 </div> 379 </body> 380</html> 381