зеркало из https://github.com/mozilla/gecko-dev.git
327 строки
13 KiB
HTML
327 строки
13 KiB
HTML
<HTML>
|
|
<HEAD>
|
|
<TITLE>db_dbm</TITLE>
|
|
</HEAD>
|
|
<BODY BGCOLOR=white>
|
|
<H1>db_dbm</H1>
|
|
<HR SIZE=1 NOSHADE>
|
|
<PRE>
|
|
<!-- Manpage converted by man2html 3.0.1 -->
|
|
dbm_firstkey, dbm_nextkey, dbm_error, dbm_clearerr
|
|
|
|
|
|
</PRE>
|
|
<H2>SYNOPSIS</H2><PRE>
|
|
<B>#define</B> <B>DB</B>_<B>DBM</B>_<B>HSEARCH</B> <B>1</B>
|
|
<B>#include</B> <B><db.h></B>
|
|
|
|
<B>typedef</B> <B>struct</B> <B>{</B>
|
|
<B>char</B> <B>*dptr;</B>
|
|
<B>int</B> <B>dsize;</B>
|
|
<B>}</B> <B>datum;</B>
|
|
|
|
|
|
</PRE>
|
|
<H2>DBM FUNCTIONS</H2><PRE>
|
|
<B>int</B>
|
|
<B>dbminit(char</B> <B>*file);</B>
|
|
|
|
<B>datum</B>
|
|
<B>fetch(datum</B> <B>key);</B>
|
|
|
|
<B>int</B>
|
|
<B>store(datum</B> <B>key,</B> <B>datum</B> <B>content);</B>
|
|
|
|
<B>int</B>
|
|
<B>delete(datum</B> <B>key);</B>
|
|
|
|
<B>datum</B>
|
|
<B>firstkey(void);</B>
|
|
|
|
<B>datum</B>
|
|
<B>nextkey(datum</B> <B>key);</B>
|
|
|
|
|
|
</PRE>
|
|
<H2>NDBM FUNCTIONS</H2><PRE>
|
|
<B>DBM</B> <B>*</B>
|
|
<B>dbm</B>_<B>open(char</B> <B>*file,</B> <B>int</B> <B>flags,</B> <B>int</B> <B>mode);</B>
|
|
|
|
<B>void</B>
|
|
<B>dbm</B>_<B>close(DBM</B> <B>*db);</B>
|
|
|
|
<B>datum</B>
|
|
<B>dbm</B>_<B>fetch(DBM</B> <B>*db,</B> <B>datum</B> <B>key);</B>
|
|
|
|
<B>int</B>
|
|
<B>dbm</B>_<B>store(DBM</B> <B>*db,</B> <B>datum</B> <B>key,</B> <B>datum</B> <B>content,</B> <B>int</B> <B>flags);</B>
|
|
|
|
<B>int</B>
|
|
<B>dbm</B>_<B>delete(DBM</B> <B>*db,</B> <B>datum</B> <B>key);</B>
|
|
|
|
<B>datum</B>
|
|
<B>dbm</B>_<B>firstkey(DBM</B> <B>*db);</B>
|
|
|
|
<B>datum</B>
|
|
<B>dbm</B>_<B>nextkey(DBM</B> <B>*db);</B>
|
|
|
|
<B>int</B>
|
|
<B>dbm</B>_<B>error(DBM</B> <B>*db);</B>
|
|
<B>int</B>
|
|
<B>dbm</B>_<B>clearerr(DBM</B> <B>*db);</B>
|
|
|
|
|
|
</PRE>
|
|
<H2>DESCRIPTION</H2><PRE>
|
|
The dbm and ndbm interfaces to the DB library are intended
|
|
to provide source code compatibility for historic
|
|
applications. They are not recommended for any other
|
|
purpose. The historic dbm and ndbm database format is <B>not</B>
|
|
supported, and databases previously built using the real
|
|
dbm or ndbm libraries cannot be read by the DB functions.
|
|
|
|
To compile dbm or ndbm applications, replace the
|
|
application's #include of the dbm or ndbm include file
|
|
(e.g., ``#include <dbm.h>'' or ``#include <ndbm.h>'') with
|
|
the following two lines:
|
|
|
|
#define DB_DBM_HSEARCH 1
|
|
#include <db.h>
|
|
|
|
and recompile. If the application attempts to load
|
|
against a dbm library (e.g., ``-ldbm''), remove the
|
|
library from the load line.
|
|
|
|
Keys and contents are described by the datum typedef. A
|
|
datum specifies a string of dsize bytes pointed to by
|
|
dptr. Arbitrary binary data, as well as normal text
|
|
strings, are allowed.
|
|
|
|
|
|
</PRE>
|
|
<H2>DBM FUNCTIONS</H2><PRE>
|
|
Before a database can be accessed, it must be opened by
|
|
dbminit. This will open and/or create the database
|
|
file.db. If created, the database file is created
|
|
read/write by owner only (as described in <B>chmod(2)</B>) and
|
|
modified by the process' umask value at the time of
|
|
creation (see <B>umask(2)</B>). The group ownership of created
|
|
files is based on the system and directory defaults, and
|
|
is not further specified by DB.
|
|
|
|
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) 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. With
|
|
any key nextkey will return the next key in the database.
|
|
This code will traverse the data base:
|
|
|
|
for (key = firstkey();
|
|
key.dptr != NULL; key = nextkey(key))
|
|
|
|
|
|
</PRE>
|
|
<H2>NDBM FUNCTIONS</H2><PRE>
|
|
Before a database can be accessed, it must be opened by
|
|
dbm_open. This will open and/or create the database file
|
|
file.db depending on the flags parameter (see <B>open(2)</B>).
|
|
If created, the database file is created with mode mode
|
|
(as described in <B>chmod(2)</B>) and modified by the process'
|
|
umask value at the time of creation (see <B>umask(2)</B>). The
|
|
group ownership of created files is based on the system
|
|
and directory defaults, and is not further specified by
|
|
DB.
|
|
|
|
Once open, the data stored under a key is accessed by
|
|
dbm_fetch and data is placed under a key by dbm_store.
|
|
The flags field can be either <B>DBM</B>_<B>INSERT</B> or <B>DBM</B>_<B>REPLACE.</B>
|
|
<B>DBM</B>_<B>INSERT</B> will only insert new entries into the database
|
|
and will not change an existing entry with the same key.
|
|
<B>DBM</B>_<B>REPLACE</B> will replace an existing entry if it has the
|
|
same key. A key (and its associated contents) is deleted
|
|
by dbm_delete. A 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. This code will
|
|
traverse the data base:
|
|
|
|
for (key = dbm_firstkey(db);
|
|
key.dptr != NULL; key = dbm_nextkey(db))
|
|
|
|
Dbm_error returns non-zero when an error has occurred
|
|
reading or writing the database. Dbm_clearerr resets the
|
|
error condition on the named database.
|
|
|
|
|
|
</PRE>
|
|
<H2>COMPATIBILITY NOTES</H2><PRE>
|
|
The historic dbm and ndbm libraries created two underlying
|
|
database files, traditionally named file.dir and file.pag.
|
|
The DB library creates a single database file named
|
|
file.db. Applications that are aware of the underlying
|
|
database file names may require additional source code
|
|
modifications.
|
|
|
|
The historic dbminit interface required that the
|
|
underlying ``.dir'' and ``.pag'' files already exist
|
|
(empty databases were created by creating zero-length
|
|
``.dir'' and ``.pag'' files). Applications that expect to
|
|
create databases using this method may require additional
|
|
source code modifications.
|
|
|
|
The historic dbm_dirfno and dbm_pagfno macros are
|
|
supported, but will return identical file descriptors as
|
|
there is only a single underlying file used by the DB
|
|
hashing access method. Applications using both file
|
|
descriptors for locking may require additional source code
|
|
modifications.
|
|
|
|
If an application using the ndbm interface exits without
|
|
closing the database, it may lose updates because the DB
|
|
library buffers all writes. Such applications will
|
|
require additional source code modifications to work
|
|
correctly with the DB library.
|
|
|
|
|
|
</PRE>
|
|
<H2>DBM DIAGNOSTICS</H2><PRE>
|
|
The dbminit function returns -1 on failure, setting errno,
|
|
and 0 on success.
|
|
|
|
The fetch function sets the returned datum's dptr field to
|
|
NULL on failure, setting errno, and returns a non-NULL
|
|
dptr on success.
|
|
|
|
The store function returns -1 on failure, setting errno,
|
|
and 0 on success.
|
|
|
|
The delete function returns -1 on failure, setting errno,
|
|
and 0 on success.
|
|
|
|
The firstkey function sets the returned datum's dptr field
|
|
to NULL on failure, setting errno, and returns a non-NULL
|
|
dptr on success.
|
|
|
|
The nextkey function sets the returned datum's dptr field
|
|
to NULL on failure, setting errno, and returns a non-NULL
|
|
dptr on success.
|
|
|
|
|
|
</PRE>
|
|
<H2>NDBM DIAGNOSTICS</H2><PRE>
|
|
The dbm_open function returns NULL on failure, setting
|
|
errno, and 0 on success.
|
|
|
|
The dbm_fetch function sets the returned datum's dptr
|
|
field to NULL on failure, setting errno, and returns a
|
|
non-NULL dptr on success.
|
|
|
|
The dbm_store function returns -1 on failure, setting
|
|
errno, 0 on success, and 1 if DBM_INSERT was set and the
|
|
specified key already existed in the database.
|
|
|
|
The dbm_delete function returns -1 on failure, setting
|
|
errno, and 0 on success.
|
|
|
|
The dbm_firstkey function sets the returned datum's dptr
|
|
field to NULL on failure, setting errno, and returns a
|
|
non-NULL dptr on success.
|
|
|
|
The dbm_nextkey function sets the returned datum's dptr
|
|
field to NULL on failure, setting errno, and returns a
|
|
non-NULL dptr on success.
|
|
|
|
The dbm_error function returns -1 on failure, setting
|
|
errno, and 0 on success.
|
|
|
|
The dbm_clearerr function returns -1 on failure, setting
|
|
errno, and 0 on success.
|
|
|
|
|
|
</PRE>
|
|
<H2>ERRORS</H2><PRE>
|
|
The dbminit function may fail and return errno for any of
|
|
the errors specified for the following DB and library
|
|
functions: <B><A HREF="db_dbm.html">dbm_close(3)</A></B>, and <B><A HREF="db_dbm.html">dbm_open(3)</A></B>.
|
|
|
|
The fetch function may fail and return errno for any of
|
|
the errors specified for the following DB and library
|
|
functions: <B><A HREF="db_dbm.html">dbm_fetch(3)</A></B>.
|
|
|
|
The store function may fail and return errno for any of
|
|
the errors specified for the following DB and library
|
|
functions: <B><A HREF="db_dbm.html">dbm_store(3)</A></B>.
|
|
|
|
The delete function may fail and return errno for any of
|
|
the errors specified for the following DB and library
|
|
functions: <B><A HREF="db_dbm.html">dbm_delete(3)</A></B>.
|
|
|
|
The firstkey function may fail and return errno for any of
|
|
the errors specified for the following DB and library
|
|
functions: <B><A HREF="db_dbm.html">dbm_firstkey(3)</A></B>.
|
|
|
|
The nextkey function may fail and return errno for any of
|
|
the errors specified for the following DB and library
|
|
functions: <B><A HREF="db_dbm.html">dbm_nextkey(3)</A></B>.
|
|
|
|
The dbm_open function may fail and return errno for any of
|
|
the errors specified for the following DB and library
|
|
functions: <B><A HREF="db_open.html">db_open(3)</A></B>, and <B>memset(3)</B>.
|
|
|
|
The dbm_close function may fail and return errno for any
|
|
of the errors specified for the following DB and library
|
|
functions: <B><A HREF="db_open.html">DB->close(3)</A></B>.
|
|
|
|
The dbm_fetch function may fail and return errno for any
|
|
of the errors specified for the following DB and library
|
|
functions: <B><A HREF="db_open.html">DB->get(3)</A></B>, and <B>memset(3)</B>.
|
|
|
|
The dbm_store function may fail and return errno for any
|
|
of the errors specified for the following DB and library
|
|
functions: <B><A HREF="db_open.html">DB->put(3)</A></B>, and <B>memset(3)</B>.
|
|
|
|
The dbm_delete function may fail and return errno for any
|
|
of the errors specified for the following DB and library
|
|
functions: <B>memset(3)</B>.
|
|
|
|
The dbm_firstkey function may fail and return errno for
|
|
any of the errors specified for the following DB and
|
|
library functions: <B><A HREF="db_open.html">DB->cursor(3)</A></B>, and <B>memset(3)</B>.
|
|
|
|
The dbm_nextkey function may fail and return errno for any
|
|
of the errors specified for the following DB and library
|
|
functions: <B><A HREF="db_open.html">DB->cursor(3)</A></B>, and <B>memset(3)</B>.
|
|
|
|
|
|
</PRE>
|
|
<H2>SEE ALSO</H2><PRE>
|
|
The DB library is a family of groups of functions that
|
|
provides a modular programming interface to transactions
|
|
and record-oriented file access. The library includes
|
|
support for transactions, locking, logging and file page
|
|
caching, as well as various indexed access methods. Many
|
|
of the functional groups (e.g., the file page caching
|
|
functions) are useful independent of the other DB
|
|
functions, although some functional groups are explicitly
|
|
based on other functional groups (e.g., transactions and
|
|
logging). For a general description of the DB package,
|
|
see <B><A HREF="db_intro.html">db_intro(3)</A></B>.
|
|
|
|
<B><A HREF="db_archive.html">db_archive(1)</A></B>, <B><A HREF="db_checkpoint.html">db_checkpoint(1)</A></B>, <B><A HREF="db_deadlock.html">db_deadlock(1)</A></B>, <B><A HREF="db_dump.html">db_dump(1)</A></B>,
|
|
<B><A HREF="db_load.html">db_load(1)</A></B>, <B><A HREF="db_recover.html">db_recover(1)</A></B>, <B><A HREF="db_stat.html">db_stat(1)</A></B>, <B><A HREF="db_intro.html">db_intro(3)</A></B>,
|
|
<B><A HREF="db_appinit.html">db_appinit(3)</A></B>, <B><A HREF="db_cursor.html">db_cursor(3)</A></B>, <B><A HREF="db_dbm.html">db_dbm(3)</A></B>, <B><A HREF="db_internal.html">db_internal(3)</A></B>,
|
|
<B><A HREF="db_lock.html">db_lock(3)</A></B>, <B><A HREF="db_log.html">db_log(3)</A></B>, <B><A HREF="db_mpool.html">db_mpool(3)</A></B>, <B><A HREF="db_open.html">db_open(3)</A></B>, <B><A HREF="db_thread.html">db_thread(3)</A></B>,
|
|
<B><A HREF="db_txn.html">db_txn(3)</A></B>
|
|
|
|
</PRE>
|
|
<HR SIZE=1 NOSHADE>
|
|
<ADDRESS>
|
|
Man(1) output converted with
|
|
<a href="http://www.oac.uci.edu/indiv/ehood/man2html.html">man2html</a>
|
|
</ADDRESS>
|
|
</BODY>
|
|
</HTML>
|