mirror of
https://github.com/berkeleydb/libdb.git
synced 2024-11-16 17:16:25 +00:00
383 lines
16 KiB
HTML
383 lines
16 KiB
HTML
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
||
<html xmlns="http://www.w3.org/1999/xhtml">
|
||
<head>
|
||
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
|
||
<title>dbm/ndbm</title>
|
||
<link rel="stylesheet" href="apiReference.css" type="text/css" />
|
||
<meta name="generator" content="DocBook XSL Stylesheets V1.73.2" />
|
||
<link rel="start" href="index.html" title="Berkeley DB C API Reference" />
|
||
<link rel="up" href="historic.html" title="Appendix B. Historic Interfaces" />
|
||
<link rel="prev" href="historic.html" title="Appendix B. Historic Interfaces" />
|
||
<link rel="next" href="hsearch.html" title="hsearch" />
|
||
</head>
|
||
<body>
|
||
<div xmlns="" class="navheader">
|
||
<div class="libver">
|
||
<p>Library Version 11.2.5.3</p>
|
||
</div>
|
||
<table width="100%" summary="Navigation header">
|
||
<tr>
|
||
<th colspan="3" align="center">dbm/ndbm</th>
|
||
</tr>
|
||
<tr>
|
||
<td width="20%" align="left"><a accesskey="p" href="historic.html">Prev</a> </td>
|
||
<th width="60%" align="center">Appendix B.
|
||
Historic Interfaces
|
||
</th>
|
||
<td width="20%" align="right"> <a accesskey="n" href="hsearch.html">Next</a></td>
|
||
</tr>
|
||
</table>
|
||
<hr />
|
||
</div>
|
||
<div class="sect1" lang="en" xml:lang="en">
|
||
<div class="titlepage">
|
||
<div>
|
||
<div>
|
||
<h2 class="title" style="clear: both"><a id="dbm"></a>dbm/ndbm</h2>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<pre class="programlisting">#define DB_DBM_HSEARCH 1
|
||
#include <db.h>
|
||
|
||
typedef struct {
|
||
char *dptr;
|
||
int dsize;
|
||
} datum; </pre>
|
||
<p>
|
||
<span class="bold"><strong>Dbm Functions</strong></span>
|
||
</p>
|
||
<pre class="programlisting">int
|
||
dbminit(char *file);
|
||
|
||
int
|
||
dbmclose();
|
||
|
||
datum
|
||
fetch(datum key);
|
||
|
||
int
|
||
store(datum key, datum content);
|
||
|
||
int
|
||
delete(datum key);
|
||
|
||
datum
|
||
firstkey(void);
|
||
|
||
datum
|
||
nextkey(datum key);</pre>
|
||
<p>
|
||
<span class="bold"><strong>Ndbm Functions</strong></span>
|
||
</p>
|
||
<pre class="programlisting">DBM *
|
||
dbm_open(char *file, int flags, int mode);
|
||
|
||
void
|
||
dbm_close(DBM *db);
|
||
|
||
datum
|
||
dbm_fetch(DBM *db, datum key);
|
||
|
||
int
|
||
dbm_store(DBM *db, datum key, datum content, int flags);
|
||
|
||
int
|
||
dbm_delete(DBM *db, datum key);
|
||
|
||
datum
|
||
dbm_firstkey(DBM *db);
|
||
|
||
datum
|
||
dbm_nextkey(DBM *db);
|
||
|
||
int
|
||
dbm_error(DBM *db);
|
||
|
||
int
|
||
dbm_clearerr(DBM *db); </pre>
|
||
<p>
|
||
The dbm functions are intended to provide high-performance
|
||
implementations and source code compatibility for applications written
|
||
to historic interfaces. They are not recommended for any other
|
||
purpose. The historic dbm database format <span class="bold"><strong>is not
|
||
supported</strong></span>, and databases previously built using the real
|
||
dbm libraries cannot be read by the Berkeley DB functions.
|
||
</p>
|
||
<p>
|
||
To compile dbm applications, replace the application's <span class="bold"><strong>#include</strong></span> of the dbm or ndbm include file (for
|
||
example, <span class="bold"><strong>#include <dbm.h></strong></span> or
|
||
<span class="bold"><strong>#include <ndbm.h></strong></span>) with the
|
||
following two lines:
|
||
</p>
|
||
<pre class="programlisting">#define DB_DBM_HSEARCH 1
|
||
#include <db.h></pre>
|
||
<p>
|
||
and recompile. If the application attempts to load against a dbm
|
||
library (for example, <span class="bold"><strong>-ldbm</strong></span>), remove
|
||
the library from the load line.
|
||
</p>
|
||
<p>
|
||
<span class="bold"><strong>Key</strong></span> and
|
||
<span class="bold"><strong>content</strong></span> parameters are objects described by the
|
||
<span class="bold"><strong>datum</strong></span> typedef. A
|
||
<span class="bold"><strong>datum</strong></span> specifies a string of
|
||
<span class="bold"><strong>dsize</strong></span> bytes pointed to by
|
||
<span class="bold"><strong>dptr</strong></span>. Arbitrary binary data, as well as normal
|
||
text strings, are allowed.
|
||
</p>
|
||
<div class="sect2" lang="en" xml:lang="en">
|
||
<div class="titlepage">
|
||
<div>
|
||
<div>
|
||
<h3 class="title"><a id="dbmfunctions"></a>Dbm Functions</h3>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<p>
|
||
Before a database can be accessed, it must be opened by dbminit. This
|
||
will open and/or create the database
|
||
<span class="bold"><strong>file.db</strong></span>. If created, the database file is
|
||
created read/write by owner only (as described in
|
||
<span class="bold"><strong>chmod</strong></span>(2)) and modified by the process' umask
|
||
value at the time of creation (see
|
||
<span class="bold"><strong>umask</strong></span>(2)). The group ownership of created
|
||
files is based on the system and directory defaults, and is not
|
||
further specified by Berkeley DB.
|
||
</p>
|
||
<p>
|
||
A database may be closed, and any held resources released, by calling
|
||
dbmclose.
|
||
</p>
|
||
<p>
|
||
Once 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)
|
||
are deleted by delete. A linear pass through all keys in a database
|
||
may be made, in an (apparently) random order, by using firstkey and
|
||
nextkey. The firstkey method will return the first key in the
|
||
databaseThe nextkey method will return the next key in satabase.
|
||
</p>
|
||
<p>
|
||
The following code will traverse the database:
|
||
</p>
|
||
<pre class="programlisting">for (key = firstkey(key);
|
||
key.dptr != NULL; key = nextkey(key)) {
|
||
...
|
||
} </pre>
|
||
</div>
|
||
<div class="sect2" lang="en" xml:lang="en">
|
||
<div class="titlepage">
|
||
<div>
|
||
<div>
|
||
<h3 class="title"><a id="ndbmfunctions"></a>Ndbm Functions</h3>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<p>
|
||
Before a database can be accessed, it must be opened by dbm_open. This
|
||
will open and/or create the database file
|
||
<span class="bold"><strong>file.db</strong></span>, depending on the flags parameter (see
|
||
<span class="bold"><strong>open</strong></span>(2)). If created, the database
|
||
file is created with mode <span class="bold"><strong>mode</strong></span> (as
|
||
described in <span class="bold"><strong>chmod</strong></span>(2)) and modified
|
||
by the process' umask value at the time of creation (see <span class="bold"><strong>umask</strong></span>(2)). The group ownership of created
|
||
files is based on the system and directory defaults, and is not
|
||
further specified by Berkeley DB.
|
||
</p>
|
||
<p>
|
||
Once open, the data stored under a key is accessed by dbm_fetch, and
|
||
data is placed under a key by dbm_store. The
|
||
<span class="bold"><strong>flags</strong></span> field can be either
|
||
<span class="bold"><strong>DBM_INSERT</strong></span> or
|
||
<span class="bold"><strong>DBM_REPLACE</strong></span>.
|
||
<span class="bold"><strong>DBM_INSERT</strong></span> will only insert new entries into
|
||
the database, and will not change an existing entry with the same key.
|
||
<span class="bold"><strong>DBM_REPLACE</strong></span> will replace an existing
|
||
entry if it has the same key. A key (and its associated contents) are
|
||
deleted by dbm_delete. A linear pass through all keys in a database
|
||
may be made, in an (apparently) random order, by using dbm_firstkey
|
||
and dbm_nextkey. The dbm_firstkey method will return the first key in
|
||
the database. The dbm_nextkey method will return the next key in the
|
||
database.
|
||
</p>
|
||
<p>
|
||
The following code will traverse the database:
|
||
</p>
|
||
<pre class="programlisting">for (key = dbm_firstkey(db);
|
||
key.dptr != NULL; key = dbm_nextkey(db)) {
|
||
...
|
||
} </pre>
|
||
</div>
|
||
<div class="sect2" lang="en" xml:lang="en">
|
||
<div class="titlepage">
|
||
<div>
|
||
<div>
|
||
<h3 class="title"><a id="dbm_compat_notes"></a>Compatibility Notes</h3>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<p>
|
||
The historic dbm library created two underlying database files,
|
||
traditionally named <span class="bold"><strong>file.dir</strong></span> and
|
||
<span class="bold"><strong>file.pag</strong></span>. The Berkeley DB library
|
||
creates a single database file named <span class="bold"><strong>file.db</strong></span>. Applications that are aware of the
|
||
underlying database filenames may require additional source code
|
||
modifications.
|
||
</p>
|
||
<p>
|
||
The historic dbminit function required that the underlying <span class="bold"><strong>.dir</strong></span> and <span class="bold"><strong>.pag</strong></span>
|
||
files already exist (empty databases were created by first manually
|
||
creating zero-length <span class="bold"><strong>.dir</strong></span> and
|
||
<span class="bold"><strong>.pag</strong></span> files). Applications that
|
||
expect to create databases using this method may require additional
|
||
source code modifications.
|
||
</p>
|
||
<p>
|
||
The historic dbm_dirfno and dbm_pagfno macros are supported, but will
|
||
return identical file descriptors because there is only 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.
|
||
</p>
|
||
<p>
|
||
If applications using the dbm function exits without first closing the
|
||
database, it may lose updates because the Berkeley DB library buffers
|
||
writes to underlying databases. Such applications will require
|
||
additional source code modifications to work correctly with the
|
||
Berkeley DB library.
|
||
</p>
|
||
</div>
|
||
<div class="sect2" lang="en" xml:lang="en">
|
||
<div class="titlepage">
|
||
<div>
|
||
<div>
|
||
<h3 class="title"><a id="dbm_diagnostics"></a>Dbm Diagnostics</h3>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<p>
|
||
The dbminit function returns -1 on failure, setting <span class="bold"><strong>errno</strong></span>, and 0 on success.
|
||
</p>
|
||
<p>
|
||
The fetch 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.
|
||
</p>
|
||
<p>
|
||
The store function returns -1 on failure, setting <span class="bold"><strong>errno</strong></span>, and 0 on success.
|
||
</p>
|
||
<p>
|
||
The delete function returns -1 on failure, setting <span class="bold"><strong>errno</strong></span>, and 0 on success.
|
||
</p>
|
||
<p>
|
||
The 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.
|
||
</p>
|
||
<p>
|
||
The 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.
|
||
</p>
|
||
</div>
|
||
<div class="sect2" lang="en" xml:lang="en">
|
||
<div class="titlepage">
|
||
<div>
|
||
<div>
|
||
<h3 class="title"><a id="dbm_errors"></a>Dbm Errors</h3>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<p>
|
||
The dbminit, fetch, store, delete, firstkey, and nextkey functions may
|
||
fail and return an error for errors specified for other Berkeley DB
|
||
and C library or system functions.
|
||
</p>
|
||
</div>
|
||
<div class="sect2" lang="en" xml:lang="en">
|
||
<div class="titlepage">
|
||
<div>
|
||
<div>
|
||
<h3 class="title"><a id="ndbm_diagnostics"></a>Ndbm Diagnostics</h3>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<p>
|
||
The dbm_close method returns non-zero when an error has occurred
|
||
reading or writing the database.
|
||
</p>
|
||
<p>
|
||
The dbm_close method resets the error condition on the named database.
|
||
</p>
|
||
<p>
|
||
The dbm_open function returns NULL on failure, setting <span class="bold"><strong>errno</strong></span>, and a DBM reference on success.
|
||
</p>
|
||
<p>
|
||
The dbm_fetch 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.
|
||
</p>
|
||
<p>
|
||
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
|
||
set and the specified key already existed in the database.
|
||
</p>
|
||
<p>
|
||
The dbm_delete function returns -1 on failure, setting <span class="bold"><strong>errno</strong></span>, and 0 on success.
|
||
</p>
|
||
<p>
|
||
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.
|
||
</p>
|
||
<p>
|
||
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.
|
||
</p>
|
||
<p>
|
||
The dbm_close function returns -1 on failure, setting <span class="bold"><strong>errno</strong></span>, and 0 on success.
|
||
</p>
|
||
<p>
|
||
The dbm_close function returns -1 on failure, setting <span class="bold"><strong>errno</strong></span>, and 0 on success.
|
||
</p>
|
||
</div>
|
||
<div class="sect2" lang="en" xml:lang="en">
|
||
<div class="titlepage">
|
||
<div>
|
||
<div>
|
||
<h3 class="title"><a id="ndbm_errors"></a>Ndbm Errors</h3>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<p>
|
||
The dbm_open, dbm_close, dbm_fetch, dbm_store, dbm_delete,
|
||
dbm_firstkey, and dbm_nextkey functions may fail and return an error
|
||
for errors specified for other Berkeley DB and C library or system
|
||
functions.
|
||
</p>
|
||
</div>
|
||
</div>
|
||
<div class="navfooter">
|
||
<hr />
|
||
<table width="100%" summary="Navigation footer">
|
||
<tr>
|
||
<td width="40%" align="left"><a accesskey="p" href="historic.html">Prev</a> </td>
|
||
<td width="20%" align="center">
|
||
<a accesskey="u" href="historic.html">Up</a>
|
||
</td>
|
||
<td width="40%" align="right"> <a accesskey="n" href="hsearch.html">Next</a></td>
|
||
</tr>
|
||
<tr>
|
||
<td width="40%" align="left" valign="top">Appendix B.
|
||
Historic Interfaces
|
||
</td>
|
||
<td width="20%" align="center">
|
||
<a accesskey="h" href="index.html">Home</a>
|
||
</td>
|
||
<td width="40%" align="right" valign="top"> hsearch</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
</body>
|
||
</html>
|