1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
|
<!DOCTYPE html>
<html class="writer-html5" lang="en" >
<head>
<meta charset="utf-8" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>cyrusdb API — Cyrus IMAP 3.12.1 documentation</title>
<link rel="stylesheet" href="../../../_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="../../../_static/css/theme.css" type="text/css" />
<link rel="stylesheet" href="../../../_static/graphviz.css" type="text/css" />
<link rel="stylesheet" href="../../../_static/cyrus.css" type="text/css" />
<script data-url_root="../../../" id="documentation_options" src="../../../_static/documentation_options.js"></script>
<script src="../../../_static/jquery.js"></script>
<script src="../../../_static/underscore.js"></script>
<script src="../../../_static/_sphinx_javascript_frameworks_compat.js"></script>
<script src="../../../_static/doctools.js"></script>
<script src="../../../_static/sphinx_highlight.js"></script>
<script src="../../../_static/js/theme.js"></script>
<link rel="index" title="Index" href="../../../genindex.html" />
<link rel="search" title="Search" href="../../../search.html" />
<link rel="next" title="Index API" href="index-api.html" />
<link rel="prev" title="CyrusDB API" href="cyrusdb.html" />
</head>
<body class="wy-body-for-nav">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search" >
<a href="../../../index.html" class="icon icon-home">
Cyrus IMAP
</a>
<div class="version">
3.12.1
</div>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="../../../search.html" method="get">
<input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
<p class="caption" role="heading"><span class="caption-text">Cyrus IMAP</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../../../download.html">Download</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../quickstart.html">Quickstart Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../overview.html">Overview</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../setup.html">Setup</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../operations.html">Operations</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="../../../developers.html">Developers</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="../../../contribute.html">We need your help</a></li>
<li class="toctree-l2"><a class="reference internal" href="../documentation.html">Contribute docs</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../developer.html">Contribute code and tests</a></li>
<li class="toctree-l2"><a class="reference internal" href="../cyrusworks.html">Cyrus.Works</a></li>
<li class="toctree-l2 current"><a class="reference internal" href="../../../developers.html#cyrus-internals">Cyrus Internals</a><ul class="current">
<li class="toctree-l3 current"><a class="reference internal" href="../API.html">Cyrus APIs</a><ul class="current">
<li class="toctree-l4"><a class="reference internal" href="cyrusdb.html">CyrusDB API</a></li>
<li class="toctree-l4 current"><a class="current reference internal" href="#">cyrusdb API</a></li>
<li class="toctree-l4"><a class="reference internal" href="index-api.html">Index API</a></li>
<li class="toctree-l4"><a class="reference internal" href="mailbox-api.html">Mailbox API</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="../thoughts.html">Thoughts & Notes</a></li>
<li class="toctree-l3"><a class="reference internal" href="../guidance.html">Guidance for Developers</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="../../../developers.html#unit-tests">Unit Tests</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../../support.html">Support/Community</a></li>
</ul>
<p class="caption" role="heading"><span class="caption-text">Cyrus SASL</span></p>
<ul>
<li class="toctree-l1"><a class="reference external" href="http://www.cyrusimap.org/sasl">Cyrus SASL</a></li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="../../../index.html">Cyrus IMAP</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="Page navigation">
<ul class="wy-breadcrumbs">
<li><a href="../../../index.html" class="icon icon-home" aria-label="Home"></a></li>
<li class="breadcrumb-item"><a href="../../../developers.html">Developers</a></li>
<li class="breadcrumb-item"><a href="../API.html">Developer APIs</a></li>
<li class="breadcrumb-item active">cyrusdb API</li>
<li class="wy-breadcrumbs-aside">
<a href="https://github.com/cyrusimap/cyrus-imapd/blob/master/docsrc/imap/developer/API/cyrusdb2.rst" class="fa fa-github"> Edit on GitHub</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<span class="target" id="imap-developer-api-cyrusdb2"></span><section id="cyrusdb-api">
<h1>cyrusdb API<a class="headerlink" href="#cyrusdb-api" title="Permalink to this heading"></a></h1>
<section id="intro">
<h2>Intro<a class="headerlink" href="#intro" title="Permalink to this heading"></a></h2>
<p>The <code class="docutils literal notranslate"><span class="pre">cyrusdb</span></code> 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 silently
breaking things. Exceptions are noted below.</p>
</section>
<section id="code-layout">
<h2>Code Layout<a class="headerlink" href="#code-layout" title="Permalink to this heading"></a></h2>
<p>The implementation of each interface is in <code class="docutils literal notranslate"><span class="pre">lib/cyrusdb_NAME.c</span></code>, for
example lib/cyrusdb_flat.c. General functions are in <code class="docutils literal notranslate"><span class="pre">lib/cyrusdb.c</span></code>
and the interface in <code class="docutils literal notranslate"><span class="pre">lib/cyrusdb.h</span></code>.</p>
</section>
<section id="configuration">
<h2>Configuration<a class="headerlink" href="#configuration" title="Permalink to this heading"></a></h2>
<p>The name of the backend for each of the main internal databases can be
configured in imapd.conf, for example: <code class="docutils literal notranslate"><span class="pre">annotation_db:</span> <span class="pre">skiplist</span></code>. This
is then read in imap/global.h and imap/global.c during startup, so that
the global variable <code class="docutils literal notranslate"><span class="pre">config_annotation_db</span></code> gets set to the configured
backend name:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">config_annotation_db</span> <span class="o">=</span> <span class="n">config_getstring</span><span class="p">(</span><span class="n">IMAPOPT_ANNOTATION_DB</span><span class="p">);</span>
</pre></div>
</div>
<p>(Beware the misleading naming here: <code class="docutils literal notranslate"><span class="pre">config_annotation_db</span></code> is a string
describing the <em>backend</em> used by the database, not, say, its location on
disk.)</p>
<p>Internally, the main module for each database sets up struct of pointers
to the cyrusdb functions it implements, which is registered in
<code class="docutils literal notranslate"><span class="pre">lib/cyrusdb.c</span></code></p>
<p><code class="docutils literal notranslate"><span class="pre">lib/cyrusdb.c</span></code> provides backend-agnostic wrapper functions for
interacting with cyrusdb databases.</p>
</section>
<section id="a-full-example">
<h2>A full example<a class="headerlink" href="#a-full-example" title="Permalink to this heading"></a></h2>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">struct</span> <span class="n">db</span> <span class="o">*</span><span class="n">db</span> <span class="o">=</span> <span class="n">NULL</span><span class="p">;</span>
<span class="n">struct</span> <span class="n">txn</span> <span class="o">*</span><span class="n">tid</span> <span class="o">=</span> <span class="n">NULL</span><span class="p">;</span>
<span class="n">const</span> <span class="n">char</span> <span class="o">*</span><span class="n">filename</span> <span class="o">=</span> <span class="n">NULL</span><span class="p">;</span>
<span class="nb">int</span> <span class="n">flags</span> <span class="o">=</span> <span class="n">CYRUSDB_CREATE</span><span class="p">;</span>
<span class="n">cyrus_init</span><span class="p">(</span><span class="n">alt_config</span><span class="p">,</span> <span class="s2">"toolname"</span><span class="p">,</span> <span class="mi">0</span><span class="p">);</span>
<span class="n">filename</span> <span class="o">=</span> <span class="n">config_getstring</span><span class="p">(</span><span class="n">IMAPOPT_ANNOTATION_DB_PATH</span><span class="p">);</span>
<span class="n">r</span> <span class="o">=</span> <span class="n">cyrusdb_open</span><span class="p">(</span><span class="n">config_annotation_db</span><span class="p">,</span> <span class="n">filename</span><span class="p">,</span> <span class="n">flags</span><span class="p">,</span> <span class="o">&</span><span class="n">db</span><span class="p">);</span>
<span class="n">r</span> <span class="o">=</span> <span class="n">cyrusdb_fetch</span><span class="p">(</span><span class="n">db</span><span class="p">,</span> <span class="n">key</span><span class="p">,</span> <span class="n">keylen</span><span class="p">,</span> <span class="o">&</span><span class="n">data</span><span class="p">,</span> <span class="o">&</span><span class="n">datalen</span><span class="p">,</span> <span class="o">&</span><span class="n">tid</span><span class="p">);</span>
<span class="n">r</span> <span class="o">=</span> <span class="n">cyrusdb_commit</span><span class="p">(</span><span class="n">db</span><span class="p">,</span> <span class="n">tid</span><span class="p">);</span>
<span class="n">r</span> <span class="o">=</span> <span class="n">cyrusdb_close</span><span class="p">(</span><span class="n">db</span><span class="p">);</span>
<span class="n">cyrus_done</span><span class="p">();</span>
</pre></div>
</div>
<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 initialize
and clean up the <code class="docutils literal notranslate"><span class="pre">cyrusdb</span></code> 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>
</section>
<section id="about-transactions">
<h2>About Transactions<a class="headerlink" href="#about-transactions" title="Permalink to this heading"></a></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 class="simple">
<li><p>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</p></li>
<li><p>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.</p></li>
<li><p>Pointer to a valid transaction. Will keep using this transaction</p></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: <em>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</em></p>
</section>
<section id="api-reference">
<h2>API Reference<a class="headerlink" href="#api-reference" title="Permalink to this heading"></a></h2>
<p>All functions follow the normal C API of returning '0' on success, and
an error code on failure</p>
<section id="cyrusdb-init-void">
<h3>cyrusdb_init(void)<a class="headerlink" href="#cyrusdb-init-void" title="Permalink to this heading"></a></h3>
<p>Is called once per process. Don't call this yourself, use
<code class="docutils literal notranslate"><span class="pre">cyrus_init()</span></code>. No other calls will be made until this is called.</p>
</section>
<section id="cyrusdb-done-void">
<h3>cyrusdb_done(void)<a class="headerlink" href="#cyrusdb-done-void" title="Permalink to this heading"></a></h3>
<p>The opposite of <code class="docutils literal notranslate"><span class="pre">cyrusdb_init()</span></code> - called once per process to do any
cleaning up after all database usage is finished. Don't call this
yourself, use <code class="docutils literal notranslate"><span class="pre">cyrus_done()</span></code>.</p>
</section>
<section id="cyrusdb-sync-const-char-backend">
<h3>cyrusdb_sync(const char *backend)<a class="headerlink" href="#cyrusdb-sync-const-char-backend" title="Permalink to this heading"></a></h3>
<p>Perform a checkpoint of the database environment. Used by berkeley
backend. Is called by <code class="docutils literal notranslate"><span class="pre">ctl_cyrusdb</span> <span class="pre">-c</span></code> on a regular basis</p>
</section>
<section id="cyrusdb-open-const-char-backend-const-char-fname-int-flags-struct-db-retdb">
<h3>cyrusdb_open(const char *backend, const char *fname, int flags, struct db **retdb)<a class="headerlink" href="#cyrusdb-open-const-char-backend-const-char-fname-int-flags-struct-db-retdb" title="Permalink to this heading"></a></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 class="simple">
<li><p>CYRUSDB_CREATE - create the database if it doesn't exist</p></li>
</ul>
<p>Errors:</p>
<ul class="simple">
<li><p>CYRUSDB_IOERROR - if there is any error reading the file, or any
corruption detected while loading the file</p></li>
</ul>
</section>
<section id="cyrusdb-close-struct-db-db">
<h3>cyrusdb_close(struct db *db)<a class="headerlink" href="#cyrusdb-close-struct-db-db" title="Permalink to this heading"></a></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 class="simple">
<li><p>CYRUSDB_IOERROR - if there are any errors during close</p></li>
</ul>
</section>
<section id="cyrusdb-fetch-struct-db-db-const-char-key-size-t-keylen-const-char-data-size-t-datalen-struct-txn-tidptr">
<h3>cyrusdb_fetch(struct db *db, const char *key, size_t keylen, const char **data, size_t *datalen, struct txn **tidptr)<a class="headerlink" href="#cyrusdb-fetch-struct-db-db-const-char-key-size-t-keylen-const-char-data-size-t-datalen-struct-txn-tidptr" title="Permalink to this heading"></a></h3>
</section>
<section id="cyrusdb-fetchlock-struct-db-db-const-char-key-size-t-keylen-const-char-data-size-t-datalen-struct-txn-tidptr">
<h3>cyrusdb_fetchlock(struct db *db, const char *key, size_t keylen, const char **data, size_t *datalen, struct txn **tidptr)<a class="headerlink" href="#cyrusdb-fetchlock-struct-db-db-const-char-key-size-t-keylen-const-char-data-size-t-datalen-struct-txn-tidptr" title="Permalink to this heading"></a></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 class="simple">
<li><p>CYRUSDB_IOERROR - if any error occurs reading from the database</p></li>
<li><p>CYRUSDB_LOCKED - if tidptr is incorrect</p></li>
<li><p>CYRUSDB_NOTFOUND - if there is no record that matches the key</p></li>
</ul>
</section>
<section id="cyrusdb-foreach-struct-db-db-const-char-prefix-size-t-prefixlen-foreach-p-goodp-foreach-p-procp-void-rock-struct-txn-tidptr">
<h3>cyrusdb_foreach(struct db *db, const char *prefix, size_t prefixlen, foreach_p *goodp, foreach_p *procp, void *rock, struct txn **tidptr)<a class="headerlink" href="#cyrusdb-foreach-struct-db-db-const-char-prefix-size-t-prefixlen-foreach-p-goodp-foreach-p-procp-void-rock-struct-txn-tidptr" title="Permalink to this heading"></a></h3>
</section>
<section id="cyrusdb-forone-struct-db-db-const-char-key-size-t-keylen-foreach-p-goodp-foreach-p-procp-void-rock-struct-txn-tidptr">
<h3>cyrusdb_forone(struct db *db, const char *key, size_t keylen, foreach_p *goodp, foreach_p *procp, void *rock, struct txn **tidptr)<a class="headerlink" href="#cyrusdb-forone-struct-db-db-const-char-key-size-t-keylen-foreach-p-goodp-foreach-p-procp-void-rock-struct-txn-tidptr" title="Permalink to this heading"></a></h3>
<p><code class="docutils literal notranslate"><span class="pre">cyrusdb_foreach()</span></code> iterates 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><code class="docutils literal notranslate"><span class="pre">cyrusdb_forone()</span></code> "iterates" over the single record matched by the
given key. If you've already built callbacks for processing each record
from a foreach, this lets you use the same interface to process a single
record.</p>
<p><code class="docutils literal notranslate"><span class="pre">goodp</span></code> - 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><code class="docutils literal notranslate"><span class="pre">procp</span></code> - 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 class="simple">
<li><p>procp_result - whatever your callback returns</p></li>
<li><p>CYRUSDB_IOERROR - if any error occurs while reading</p></li>
<li><p>CYRUSDB_LOCKED - if tidptr is incorrect</p></li>
</ul>
</section>
<section id="cyrusdb-create-struct-db-db-const-char-key-size-t-keylen-const-char-data-size-t-datalen-struct-txn-tidptr">
<h3>cyrusdb_create(struct db *db, const char *key, size_t keylen, const char *data, size_t datalen, struct txn **tidptr)<a class="headerlink" href="#cyrusdb-create-struct-db-db-const-char-key-size-t-keylen-const-char-data-size-t-datalen-struct-txn-tidptr" title="Permalink to this heading"></a></h3>
</section>
<section id="cyrusdb-store-struct-db-db-const-char-key-size-t-keylen-const-char-data-size-t-datalen-struct-txn-tidptr">
<h3>cyrusdb_store(struct db *db, const char *key, size_t keylen, const char *data, size_t datalen, struct txn **tidptr)<a class="headerlink" href="#cyrusdb-store-struct-db-db-const-char-key-size-t-keylen-const-char-data-size-t-datalen-struct-txn-tidptr" title="Permalink to this heading"></a></h3>
<p>Create a new record or replace an existing one. The only difference
between these two is that <code class="docutils literal notranslate"><span class="pre">cyrusdb_create</span></code> will return an error if the
record already exists, while <code class="docutils literal notranslate"><span class="pre">cyrusdb_store</span></code> 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 class="simple">
<li><p>CYRUSDB_IOERROR - any error to write to the database</p></li>
<li><p>CYRUSDB_LOCKED - if tidptr is incorrect</p></li>
<li><p>CYRUSDB_EXISTS - if <code class="docutils literal notranslate"><span class="pre">cyrusdb_create</span></code> is called on an existing key</p></li>
<li><p>CYRUSDB_AGAIN - if a deadlock is created. The current transaction
has been aborted, but a retry may succeed</p></li>
</ul>
</section>
<section id="cyrusdb-delete-struct-db-db-const-char-key-size-t-keylen-struct-txn-tidptr-int-force">
<h3>cyrusdb_delete(struct db *db, const char *key, size_t keylen, struct txn **tidptr, int force)<a class="headerlink" href="#cyrusdb-delete-struct-db-db-const-char-key-size-t-keylen-struct-txn-tidptr-int-force" title="Permalink to this heading"></a></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 class="simple">
<li><p>CYRUSDB_IOERROR - any error to write to the database</p></li>
<li><p>CYRUSDB_LOCKED - if tidptr is incorrect</p></li>
<li><p>CYRUSDB_NOTFOUND - if force is not set and the key doesn't exist</p></li>
<li><p>CYRUSDB_AGAIN - if a deadlock is created. The current transaction
has been aborted, but a retry may succeed</p></li>
</ul>
</section>
<section id="cyrusdb-commit-struct-db-db-struct-txn-tid">
<h3>cyrusdb_commit(struct db *db, struct txn *tid)<a class="headerlink" href="#cyrusdb-commit-struct-db-db-struct-txn-tid" title="Permalink to this heading"></a></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 class="simple">
<li><p>CYRUSDB_IOERROR - any error to write to the database</p></li>
<li><p>CYRUSDB_LOCKED - if tidptr is incorrect</p></li>
<li><p>CYRUSDB_AGAIN - if a deadlock is created. The current transaction
has been aborted, but a retry may succeed</p></li>
</ul>
</section>
<section id="cyrusdb-abort-struct-db-db-struct-txn-tid">
<h3>cyrusdb_abort(struct db *db, struct txn *tid)<a class="headerlink" href="#cyrusdb-abort-struct-db-db-struct-txn-tid" title="Permalink to this heading"></a></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 class="simple">
<li><p>CYRUSDB_IOERROR - any error to write to the database</p></li>
<li><p>CYRUSDB_LOCKED - if tidptr is incorrect</p></li>
</ul>
</section>
<section id="cyrusdb-dump-struct-db-db-int-detail">
<h3>cyrusdb_dump(struct db *db, int detail)<a class="headerlink" href="#cyrusdb-dump-struct-db-db-int-detail" title="Permalink to this heading"></a></h3>
<p>Optional function to dump the internal structure of the database to
stdout for debugging purposes. Don't use.</p>
</section>
<section id="cyrusdb-consistent-struct-db-db">
<h3>cyrusdb_consistent(struct db *db)<a class="headerlink" href="#cyrusdb-consistent-struct-db-db" title="Permalink to this heading"></a></h3>
<p>Check if the DB is internally consistent. Looks pretty bogus, and isn't
used anywhere. Don't use.</p>
</section>
</section>
</section>
</div>
</div>
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
<a href="cyrusdb.html" class="btn btn-neutral float-left" title="CyrusDB API" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
<a href="index-api.html" class="btn btn-neutral float-right" title="Index API" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
</div>
<hr/>
<div role="contentinfo">
<p>© Copyright 1993–2025, The Cyrus Team.</p>
</div>
Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
<a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
</div>
</div>
</section>
</div>
<script>
jQuery(function () {
SphinxRtdTheme.Navigation.enable(true);
});
</script>
</body>
</html>
|
