-r--r--r-- 9499 cdb-20251021/doc/html/cdb.html raw
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<style type="text/css">
html{overflow-y:scroll;background-color:#35492a}
body{font-family:"Noto Sans","Droid Sans","DejaVu Sans","Arial",sans-serif;line-height:1.5}
tt,code{background-color:#f0f0f0;font-family:"Noto Sans Mono","Droid Sans Mono","DejaVu Sans Mono","Courier New",monospace,sans-serif;font-size:1em;}
pre{margin-left:3em}
p,ul,ol,blockquote,pre{font-size:1.0em;line-height:1.6}
li p{font-size:1.0em}
blockquote p{font-size:1.0em}
h1{font-size:1.5em}
h2{font-size:1.3em}
h3{font-size:1.0em}
h1 a{text-decoration:none}
table{border-collapse:collapse}
th,td{border:1px solid black}
table a{text-decoration:none}
table tr{font-size:1.0em;line-height:1.6em}
table tr{font-size:1.0em;line-height:1.5}
tbody tr:nth-child(12n+1){background-color:#f0ffff}
tbody tr:nth-child(12n+2){background-color:#f0ffff}
tbody tr:nth-child(12n+3){background-color:#f0ffff}
tbody tr:nth-child(12n+4){background-color:#f0ffff}
tbody tr:nth-child(12n+5){background-color:#f0ffff}
tbody tr:nth-child(12n+6){background-color:#f0ffff}
tbody tr:nth-child(12n+7){background-color:#fffff0}
tbody tr:nth-child(12n+8){background-color:#fffff0}
tbody tr:nth-child(12n+9){background-color:#fffff0}
tbody tr:nth-child(12n+10){background-color:#fffff0}
tbody tr:nth-child(12n+11){background-color:#fffff0}
tbody tr:nth-child(12n+12){background-color:#fffff0}
#headline{display:block;margin:0;padding:0;color:#ffffff;background-color:#35492a}
#headline .text{font-weight:bold;font-size:1.0em}
#headline input{display:none}
#nav ul{margin:0;padding:0}
#nav li{list-style-type:none;margin:0;padding:0}
.navtop{padding-bottom:0.5em;font-weight:bold;font-size:1.0em}
.navtop{background-color:#35492a;color:#ffffff}
#nav .here{background-color:#35492a;color:#ffffff}
#nav .away{background-color:#35492a;color:#ffffff}
#nav .away a{text-decoration:none;display:block;color:#ffffff}
#nav .away a:hover,.away a:active{text-decoration:underline}
#hidemenu{visibility:hidden;display:none;overflow:hidden;position:fixed;top:0;left:0;height:100%;width:100%}
.main{padding:5px}
.main{background-color:#ffffff}
.pagetitle{font-size:1.4em;font-weight:bold}
@media only screen and (min-width:512px) {
.navtop{padding-top:5px}
#headline{top:0;margin:0;width:160px;height:100%;position:fixed;overflow:auto}
#headline .noselect{display:none}
#headline #nav{visibility:visible;display:block;width:auto;height:auto}
.main{margin-left:170px}
#headline #hidemenu{visibility:hidden}
}
@media not screen and (min-width:512px) {
#headline .noselect{-webkit-user-select:none;-ms-user-select:none;user-select:none;}
#headline #nav #navbot{visibility:hidden;position:fixed;top:0;left:-70%;z-index:2;transition:0.2s;margin:0;padding:0}
#headline input:checked ~ #nav #navbot{height:100%;position:fixed;top:0;left:0;visibility:visible;display:block;box-sizing:border-box;-moz-box-sizing:border-box;-webkit-box-sizing:border-box;vertical-align:center;font-size:1.0em;width:70%;overflow:auto}
#headline input:checked ~ #hidemenu{visibility:visible;display:block;background:black;opacity:0.3;z-index:1}
}
</style>
<title>
cdb: Read API</title>
</head>
<body>
<label id=headline>
<input type=checkbox />
<nav id=nav>
<div class=navtop>
<span class=noselect>≡</span>
cdb</div>
<ul id=navbot>
<li class=away><a href=index.html>Intro</a>
</li><li class=away><a href=download.html>Download</a>
</li><li class=away><a href=install.html>Install</a>
</li><li class=away><a href=test.html>Test</a>
</li><li class=here>Read API
</li><li class=away><a href=cdbget.html>cdbget</a>
</li><li class=away><a href=cdbdump.html>cdbdump</a>
</li><li class=away><a href=cdbmake.html>cdbmake</a>
</li><li class=away><a href=cdbmake-12.html>cdbmake-12</a>
</li><li class=away><a href=cdbmake-sv.html>cdbmake-sv</a>
</li><li class=away><a href=cdbstats.html>cdbstats</a>
</li><li class=away><a href=cdbtest.html>cdbtest</a>
</li><li class=away><a href=format.html>Format</a>
</li><li class=away><a href=license.html>License</a>
</li></ul></nav>
<div id=hidemenu></div>
</label>
<div class=main>
<div class=pagetitle>cdb: Read API</div>
<h3>NAME</h3>
<p>cdb - read a constant database</p>
<h3>SYNOPSIS</h3>
<pre><code>#include "cdb.h"
static struct cdb c;
num fd;
char *k;
num klen;
num result;
char *d;
num dlen;
num dpos;
cdb_init(&c,fd);
result = cdb_find(&c,k,klen);
/* optional decomposition of cdb_find: */
cdb_findstart(&c);
result = cdb_findnext(&c,k,klen);
dlen = cdb_datalen(&c);
dpos = cdb_datapos(&c);
result = cdb_read(&c,d,dlen,dpos);
cdb_free(&c);
</code></pre>
<h3>DESCRIPTION</h3>
<p>You can read records in a constant database
from file descriptor <code>fd</code> as follows:</p>
<ul>
<li>
<p>Use <code>cdb_init</code> to place information about <code>fd</code>
into a <code>struct cdb</code> variable <code>c</code>.</p>
</li>
<li>
<p>Carry out any number of searches, as described below.</p>
</li>
<li>
<p>Use <code>cdb_free</code> to remove any memory map
that might have been reserved by <code>cdb_init</code>.</p>
</li>
</ul>
<p>Each search works as follows:</p>
<ul>
<li>
<p>Use <code>cdb_find</code> to search for a record under key <code>k</code>.
If <code>cdb_find</code> returns <code>0</code>, the database does not contain that key; stop.
If <code>cdb_find</code> returns <code>-1</code>, there was a read error; abort.</p>
</li>
<li>
<p>Use <code>cdb_datalen</code> to find the number of bytes of data in this record.
Allocate a pointer <code>d</code> to a region of memory
large enough to hold the data.
If not enough memory is available, abort.</p>
</li>
<li>
<p>Use <code>cdb_read</code> with <code>cdb_datapos</code>
to read the data.
If <code>cdb_read</code> returns <code>-1</code>, there was a read error; abort.</p>
</li>
<li>
<p>Do something with the data,
and then free the allocated region of memory.</p>
</li>
</ul>
<p>There may be several records under a single key.
You can use <code>cdb_findnext</code> to find the next record under this key.</p>
<h3>DETAILS</h3>
<p>A <code>struct cdb</code> variable such as <code>c</code>
is either unallocated or allocated.
If it is allocated,
it holds information about a constant database:</p>
<ul>
<li>
<p>a file descriptor <code>fd</code> reading from the database;</p>
</li>
<li>
<p>if convenient,
a shared memory map reading from the database; and</p>
</li>
<li>
<p>information about a search in progress.</p>
</li>
</ul>
<p><code>c</code> must be initialized to zero, meaning unallocated.</p>
<p><code>cdb_free</code> unallocates <code>c</code>
if <code>c</code> is allocated.
Otherwise it leaves <code>c</code> alone.
<code>cdb_free</code> does not close <code>fd</code>.</p>
<p><code>cdb_init</code>
allocates <code>c</code> to hold information
about a constant database read by descriptor <code>fd</code>.
You may call <code>cdb_init</code> repeatedly;
if <code>c</code> is already allocated,
<code>cdb_init</code> unallocates it first.</p>
<p><code>cdb_read</code>
reads <code>dlen</code> bytes into <code>d</code>
from byte position <code>dpos</code> in the database.
You must allocate <code>c</code> before calling <code>cdb_read</code>.
Normally <code>cdb_read</code> returns <code>0</code>.
If the database file is shorter than <code>dpos+dlen</code> bytes,
or if there is a disk read error,
<code>cdb_read</code> returns <code>-1</code>, setting <code>errno</code> appropriately.</p>
<p><code>cdb_findstart</code>
prepares <code>c</code> to search for the first record under a new key.
You must allocate <code>c</code> before calling <code>cdb_findstart</code>,
and you must call <code>cdb_findstart</code>
before calling <code>cdb_findnext</code>.</p>
<p><code>cdb_findnext</code>
looks for the nth record under key <code>k</code> in the database,
where <code>n</code> is the number of calls to <code>cdb_findnext</code>
after the most recent call to <code>cdb_findstart</code>.
If it finds the record,
<code>cdb_findnext</code> returns 1;
if there are exactly <code>n-1</code> such records,
<code>cdb_findnext</code> returns <code>0</code>;
if there are fewer than <code>n-1</code> such records,
the behavior of <code>cdb_findnext</code> is undefined;
if there is a database format error or disk error,
<code>cdb_findnext</code> returns <code>-1</code>, setting <code>errno</code> appropriately.
Each call to <code>cdb_findnext</code>
(before another call to <code>cdb_findstart</code>)
must use the same <code>k</code>
and <code>klen</code>.</p>
<p>If <code>cdb_findnext</code> returns 1,
it arranges for <code>cdb_datapos</code> to return the starting byte position
of the data in the record, and for <code>cdb_datalen</code>
to return the number of bytes of data in the record.
Otherwise the results of <code>cdb_datapos</code> and <code>cdb_datalen</code>
are undefined.</p>
<p><code>cdb_find</code> is the same as <code>cdb_findstart</code>
followed by <code>cdb_findnext</code>:
it finds the first record under key <code>k</code>.</p>
<p>Beware that these functions
may rely on non-atomic operations on the <code>fd</code> ofile,
such as seeking to a particular position and then reading.
Do not attempt two simultaneous database reads
using a single ofile.</p>
<h3>SEE ALSO</h3>
<p><strong>cdbget</strong>(1)</p><hr><font size=1><b>Version:</b>
This is version 2025.10.21 of the "Read API" web page.
</font>
</div>
</body>
</html>