mirror of
https://github.com/berkeleydb/libdb.git
synced 2024-11-17 01:26:25 +00:00
384 lines
16 KiB
HTML
384 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.2</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>
|