<!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" />
<meta name="author" content="Bron Gondwana" />
<title>cyrusdb API</title>
</head>
<body>
<h1>cyrusdb API</h1>
<h2>Intro</h2>
<p>The <tt>cyrusdb</tt> API is a common interface to a key-value store, used
throughout the Cyrus code. It allows a choice of different backends for
different access patterns, while ensuring a consistent interface.</p>
<p>This document will describe the interface, and how to use the cyrusdb
interface from within parts of Cyrus code, as well as how to implement
your own backend</p>
<p>If you pass incorrect values to these APIs, you will get an assertion
failure in most cases. That's generally considered safer than silenty
breaking things. Exceptions are noted below.</p>
<h2>Code Layout</h2>
<p>The implementation of each interface is in <tt>lib/cyrusdb_NAME.c</tt>,
for example lib/cyrusdb_flat.c. General functions are in
<tt>lib/cyrusdb.c</tt> and the interface in <tt>lib/cyrusdb.h</tt>.</p>
<h2>Configuration</h2>
<p>The name of the backend for each of the main internal databases can be
configured in imapd.conf, for example: <tt>annotation_db: skiplist</tt>.
This is then read in imap/global.h and imap/global.c during startup, so
that the global variable <tt>config_annotation_db</tt> gets set to the actual
database backend:</p>
<pre>
config_annotation_db =
cyrusdb_fromname(config_getstring(IMAPOPT_ANNOTATION_DB));
</pre>
<p><tt>cyrusdb_fromname</tt> uses the database name to find the
<tt>struct cyrusdb_backend *</tt> of the actual database.</p>
<p>The main module for each database then sets up a "short name" to
refer to the struct containing the funtion pointers for each action
on that database type, giving an "object oriented" API to the database,
for example:</p>
<pre>
#define DB config_annotation_db
r = DB->open(fname, dbflags, &db);
r = DB->fetch(&db, key, keylen, &data, &datalen, &tid);
</pre>
<h2>A full example</h2>
<pre>
struct cyrusdb_backend *BE = NULL;
struct db *db = NULL;
struct txn *tid = NULL;
cyrus_init(alt_config, "toolname", 0);
BE = cyrusdb_fromname("skiplist");
r = BE->open(filename, flags, &db);
r = BE->fetch(db, key, keylen, &data, &datalen, &tid);
r = BE->commit(db, tid);
r = DB->close(db);
cyrus_done();
</pre>
<p>Note that you always open a database first, and close it at the end.
You must always call cyrus_init() and cyrus_done() to properly intialise
and clean up the DB environments.</p>
<p>This example also uses a transaction, meaning that the database is locked
in exclusive mode between the 'fetch' (the first use of the transaction)
and the commit.</p>
<h2>About Transactions</h2>
<p>The cyrusdb interface works in two modes - transactional and
non-transactional. The value of the 'tid' parameter decides which
mode is used. There are three possible values:</p>
<ul>
<li>NULL - non-transactional. Will create a temporary lock for the
duration of the current action - either a write lock for "store"
or a read lock for "fetch". If you call "foreach", the lock will
be dropped between each record fetched</li>
<li>Pointer to NULL - transactional, transaction not yet started. Will
always take a write lock on the database, and update the pointer to
point to the new transaction.</li>
<li>Pointer to a valid transaction. Will keep using this transaction</li>
</ul>
<p>If you are currently in a transaction, you MUST pass the same transaction
to every database call. It is not possible to mix or nest transactions.
There is one exception in the skiplist backend: <i>If you pass NULL to a
fetch or foreach while the database is in a transaction, it will silently
do the read in the current transaction rather than returning an error</i></p>
<h2>API Reference</h2>
<p>All functions follow the normal C API of returning '0' on success,
and an error code on failure</p>
<h3>init(const char *dbdir, int flags)</h3>
<p>Is called once per process. Don't call this yourself, use cyrus_init().
No other calls will be made until this is called. Dbdir is the directory
where database log files and other "state information" is stored.</p>
<p>
Flags:</p>
<ul>
<li>CYRUSDB_RECOVER - called by <tt>ctl_cyrusdb -r</tt> during startup to
do initial setup after a restart</li>
</ul>
<h3>done()</h3>
<p>The opposite of <tt>init()</tt> - called once per process to do any cleaning
up after all database usage is finished</p>
<h3>sync()</h3>
<p>Perform a checkpoint of the database environment. Used by berkeley
backend. Is called by <tt>ctl_cyrusdb -c</tt> on a regular basis</p>
<h3>archive(const char **fnames, const char *dirname)</h3>
<p>Archives the database environment and named database files into
the named directory. Called by <tt>ctl_cyrusdb -c</tt> to take
backups of important databases.</p>
<p>Errors:</p>
<ul>
<li>CYRUSDB_IOERROR - if an error occurs copying a file</li>
</ul>
<h3>open(const char *fname, int flags, struct db **retdb)</h3>
<p>Opens the database with the specified 'file name' (or other descriptor,
for example the sql backend is not a filename), and if successful returns
an opaque database structure</p>
<p>Flags:</p>
<ul>
<li>CYRUSDB_CREATE - create the database if it doesn't exist</li>
<li>CYRUSDB_MBOXSORT - sort '.' first, so folder listing is correct</li>
</ul>
<p>Errors:</p>
<ul>
<li>CYRUSDB_IOERROR - if there is any error reading the file, or any
corruption detected while loading the file</li>
</ul>
<h3>close(struct db *db)</h3>
<p>Close the named database. Will release any locks if they are still
held, but it's bad practice to close without committing or aborting, so
the backend should log an error</p>
<p>Errors:</p>
<ul>
<li>CYRUSDB_IOERROR - if there are any errors during close</li>
</ul>
<h3>fetch(struct db *db, const char *key, size_t keylen,
const char **data, size_t *datalen, struct txn **tidptr)</h3>
<h3>fetchlock(struct db *db, const char *key, size_t keylen,
const char **data, size_t *datalen, struct txn **tidptr)</h3>
<p>Fetch the value for the exact key given by key and keylen. If data
is not NULL, set datalen and return a valid pointer to the start of
the value.</p>
<p>Fetchlock is identical to fetch, but gives a hint to the database
that the record is likely to be modified soon.</p>
<p>NOTE: it is possible to store a key with a zero length data record,
in which case *datalen will be set to zero, and *data will be set to
a non-NULL value</p>
<p>It is an error to call fetch with a NULL key or a zero keylen</p>
<p>It is an error to call fetch with a NULL datalen and a non-NULL data,
however it is acceptable to call with a NULL data and a non-NULL datalen
if you are only interested in the length</p>
<p>Errors:</p>
<ul>
<li>CYRUSDB_IOERROR - if any error occurs reading from the database</li>
<li>CYRUSDB_LOCKED - if tidptr is incorrect</li>
<li>CYRUSDB_NOTFOUND - if there is no record that matches the key</li>
</ul>
<h3>foreach(struct db *db, const char *prefix, size_t prefixlen,
foreach_p *goodp, foreach_p *procp, void *rock, struct txn **tidptr)</h3>
<p>Iterate over all records matching the given prefix, in database
order (which may be MBOXLIST sort, depending on the parameters given
to open</p>
<p>It is legal to give a NULL pointer as prefix if prefixlen is zero, in
which case it will return all records in the database. It is an error
to give a non-zero prefixlen with a NULL prefix.</p>
<p><tt>goodp</tt> - this function is only used for deciding if the record
needs to be further processed. It can be used for basic filtering, and
returns true (non-zero) to process, or zero to skip and move straight to
the next record. Because goodp can't make any database changes, it doesn't
break the lock, so it's faster to use goodp to filter records if you
don't need to process all of them. NULL is a legal value for goodp, and
means that all records will be processed.</p>
<p><tt>procp</tt> - procp is the main callback function. If you use foreach
in non-transactional mode, the database is unlocked before calling procp,
and locked again afterwards. You are allowed to add, delete or modify
values in the same database from within procp. If procp returns non-zero,
the foreach loop breaks at this point, and the return value of the foreach
becomes the return value of procp. If procp returns zero, the foreach loop
will continue at the NEXT record by sort order, regardless of whether the
current record has changed or been removed. procp MUST NOT be NULL.</p>
<p>Errors:</p>
<ul>
<li>procp_result - whatever your callback returns</li>
<li>CYRUSDB_IOERROR - if any error occurs while reading</li>
<li>CYRUSDB_LOCKED - if tidptr is incorrect</li>
</ul>
<h3>create(struct db *db, const char *key, size_t keylen, const char *data,
size_t datalen, struct txn **tidptr)</h3>
<h3>store(struct db *db, const char *key, size_t keylen, const char *data,
size_t datalen, struct txn **tidptr)</h3>
<p>Create a new record or replace an existing one. The only difference
between these two is that <tt>create</tt> will return an error if the record
already exists, while <tt>store</tt> will replace it</p>
<p>If tidptr is NULL, create/store will take a write lock for the duration
of the action.</p>
<p>Any failure during create/store will abort the current transaction as well
as returning an error</p>
<p>It is legal to pass NULL for the data field ONLY if datalen is zero. It
is not legal to pass NULL for key or zero for keylen</p>
<p>Errors:</p>
<ul>
<li>CYRUSDB_IOERROR - any error to write to the database</li>
<li>CYRUSDB_LOCKED - if tidptr is incorrect</li>
<li>CYRUSDB_EXISTS - if <tt>create</tt> is called on an existing key</li>
<li>CYRUSDB_AGAIN - if a deadlock is created. The current transaction has
been aborted, but a retry may succeed</li>
</ul>
<h3>delete(struct db *db, const char *key, size_t keylen,
struct txn **tidptr, int force)</h3>
<p>Delete the given record from the database. If force is true, then
succeed even if the record doesn't currently exist.</p>
<p>It is not legal to pass NULL for key or zero for keylen</p>
<p>Errors:</p>
<ul>
<li>CYRUSDB_IOERROR - any error to write to the database</li>
<li>CYRUSDB_LOCKED - if tidptr is incorrect</li>
<li>CYRUSDB_NOTFOUND - if force is not set and the key doesn't exist</li>
<li>CYRUSDB_AGAIN - if a deadlock is created. The current transaction has
been aborted, but a retry may succeed</li>
</ul>
<h3>commit(struct db *db, struct txn *tid)</h3>
<p>Commit the current transaction. tid will not be valid after this call,
regardless of success</p>
<p>If the commit fails, it will attempt to abort the transaction</p>
<p>Errors:</p>
<ul>
<li>CYRUSDB_IOERROR - any error to write to the database</li>
<li>CYRUSDB_LOCKED - if tidptr is incorrect</li>
<li>CYRUSDB_AGAIN - if a deadlock is created. The current transaction has
been aborted, but a retry may succeed</li>
</ul>
<h3>abort(struct db *db, struct txn *tid)</h3>
<p>Abort the current transaction. tid will not be valid after this call,
regardless of success</p>
<p>Attempt to roll back all changes made in the current transaction.</p>
<p>Errors:</p>
<ul>
<li>CYRUSDB_IOERROR - any error to write to the database</li>
<li>CYRUSDB_LOCKED - if tidptr is incorrect</li>
</ul>
<h3>dump(struct db *db, int detail)</h3>
<p>Optional function to dump the internal structure of the database to stdout
for debugging purposes. Don't use.</p>
<h3>consistent(struct db *db)</h3>
<p>Check if the DB is internally consistent. Looks pretty bogus, and isn't
used anywhere. Don't use.</p>
</body>
</html>
distrib
>
Mageia
>
7
>
i586
>
media
>
core-updates
>
by-pkgid
>
c43d99b5f4a2e8d76a58d7d3790db733
>
files
>
265
