cdb.html (5502B)
1 <html> 2 <head> 3 <meta name="viewport" content="width=device-width, initial-scale=1.0" /> 4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> 5 <meta http-equiv="Content-Language" content="en" /> 6 <title>skalibs: the cdb header</title> 7 <meta name="Description" content="skalibs: the cdb header" /> 8 <meta name="Keywords" content="skalibs header cdb constant database map hashmap reading" /> 9 <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> --> 10 </head> 11 <body> 12 13 <p> 14 <a href="index.html">libstddjb</a><br /> 15 <a href="../libskarnet.html">libskarnet</a><br /> 16 <a href="../index.html">skalibs</a><br /> 17 <a href="//skarnet.org/software/">Software</a><br /> 18 <a href="//skarnet.org/">skarnet.org</a> 19 </p> 20 21 <h1> The <tt>skalibs/cdb.h</tt> header </h1> 22 23 <h2> General information </h2> 24 25 <p> 26 A <a href="https://cr.yp.to/cdb/cdb.txt">cdb</a>, for <em>constant database</em>, 27 is an immutable key-value store. In skalibs, a cdb is built once via the 28 <a href="cdbmake.html">cdbmake</a> primitives and stored on disk; the <tt>cdb</tt> 29 primitives, documented here, are about accessing the information. 30 </p> 31 32 <h2> Data structures </h2> 33 34 <ul> 35 <li> A <tt>cdb</tt> is an opaque structure, that must be initialized to <tt>CDB_ZERO</tt> when declared. </li> 36 <li> A <tt>cdb_data</tt> is a structure that is passed by address to cdb-reading primitives, which fill 37 it with record information. It contains (at least) two fields: 38 <ul> 39 <li> <tt>s</tt>, a <tt>char const *</tt>, which holds a pointer to the record; the <tt>const</tt> indicates 40 that a cdb is read-only, you cannot write to the record even when you have a pointer to it. </li> 41 <li> <tt>len</tt>, a <tt>uint32_t</tt>, which holds the record length. It can be zero (records can be 42 empty). A cdb must fit into 4 GB, so record lengths always fit in 32 bits. </li> 43 </ul> 44 Pointers returned in a <tt>cdb_data</tt> are only valid while the cdb is mapped. 45 Make sure to copy the information before calling <tt>cdb_free()</tt>. 46 </li> 47 <li> A <tt>cdb_find_state</tt> is an opaque structure, that should be initialized to <tt>CDB_FIND_STATE_ZERO</tt> 48 when declared. It is passed by address to <tt>cdb_findnext</tt>, to maintain position state when looking for 49 all the data records under one key. </li> 50 </ul> 51 52 <h2> Macros and functions </h2> 53 54 <h3> Starting and ending </h3> 55 56 <p> 57 <code> int cdb_init (cdb *c, char const *file) </code> <br /> 58 Maps the file named <em>file</em> to the cdb pointed to by <em>c</em>. 59 <em>*c</em> must be CDB_ZERO before the call. The function returns a 60 positive integer if it succeeds, and 0 (and sets errno) if it fails. 61 </p> 62 63 <p> 64 <code> int cdb_init_at (cdb *c, int dfd, char const *file) </code> <br /> 65 Like <tt>cdb_init</tt>, but <em>file</em> is interpreted relative to the 66 file descriptor <em>dfd</em>, which must be open on a directory. 67 </p> 68 69 <p> 70 <code> int cdb_init_fromfd (cdb *c, int fd) </code> <br /> 71 Like <tt>cdb_init</tt>, but the database file is already open and 72 readable via then file descriptor <em>fd</em>. 73 </p> 74 75 <p> 76 <code> void cdb_free (cdb *c) </code> <br /> 77 Frees the resources used by a cdb mapping. After the call, <em>c</em> 78 is immediately reusable by another <tt>cdb_init</tt> function. 79 </p> 80 81 <h3> cdb lookup </h3> 82 83 <h4> Single record lookup </h4> 84 85 <p> 86 <code> int cdb_find (cdb const *c, cdb_data *data, char const *key, uint32_t klen) </code> <br /> 87 Looks up key <em>key</em> of length <em>klen</em> in the cdb <em>*c</em>. The function returns 88 -1 if <em>*c</em> isn't a valid cdb; 0 if no record can be found for the key; and 1 on success, in 89 which case the corresponding value is returned in <em>*data</em>: <tt><em>data</em>→s</tt> 90 points to the start of the value, and <tt><em>data</em>→len</tt> contains the length of 91 the value. Only the first record with the same key can be obtained this way. 92 </p> 93 94 <h4> Multiple record lookup </h4> 95 96 <p> 97 <code> void cdb_findstart (cdb_find_state *state) </code> <br /> 98 Initializes <em>state</em> so that the next invocation of <tt>cdb_findnext()</tt> 99 finds the first record for a given key. 100 </p> 101 102 <p> 103 <code> int cdb_findnext (cdb const *c, cdb_data *data, char const *key, uint32_t klen, cdb_find_state *state) </code> <br /> 104 Like <tt>cdb_find</tt>, except that the extra argument <em>state</em> memorizes 105 internal cdb lookup data, so the next <tt>cdb_findnext()</tt> invocation with the 106 same <em>key</em>, <em>klen</em> and <em>state</em> will yield the next record 107 for the key. <tt>cdb_findnext</tt> returns 0 when all the records for the key have 108 been exhausted. 109 </p> 110 111 <h3> cdb enumeration </h3> 112 113 <p> 114 <code> void cdb_traverse_init (uint32_t *pos) </code> <br /> 115 Initializes <em>*pos</em> so that the next invocation of <tt>cdb_traverse_next</tt> 116 finds the first entry in the cdb. <em>*pos</em> can also be initialized to the 117 macro CDB_TRAVERSE_INIT() instead. 118 </p> 119 120 <p> 121 <code> int cdb_traverse_next (cdb const *c, cdb_data *key, cdb_data *data, uint32_t *pos) </code> <br /> 122 Gets the next entry in the cdb <em>*c</em>. On success, the key is stored in <em>*key</em> and the 123 data is stored in <em>*data</em>. <em>*pos*</em> is an opaque integer storing internal 124 state; it is automatically updated so that the next invocation of <tt>cdb_traverse_next()</tt> 125 yields the next entry. The function returns -1 if <em>*c</em> is not a valid cdb or <em>*pos</em> 126 is not valid state, 1 on success, and 0 if no entry can be found, i.e. the end of the cdb has 127 been reached. 128 </p> 129 130 </body> 131 </html>