1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> 2<html><head><meta http-equiv="Content-Type" content="text/html;charset=UTF-8"> 3<title>Heimbase</title> 4<link href="doxygen.css" rel="stylesheet" type="text/css"> 5<link href="tabs.css" rel="stylesheet" type="text/css"> 6</head><body> 7<p> 8<a href="http://www.h5l.org/"><img src="http://www.h5l.org/keyhole-heimdal.png" alt="keyhole logo"/></a> 9</p> 10<!-- end of header marker --> 11<!-- Generated by Doxygen 1.9.1 --> 12<script type="text/javascript" src="menudata.js"></script> 13<script type="text/javascript" src="menu.js"></script> 14<script type="text/javascript"> 15/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */ 16$(function() { 17 initMenu('',false,false,'search.php','Search'); 18}); 19/* @license-end */</script> 20<div id="main-nav"></div> 21</div><!-- top --> 22<div class="header"> 23 <div class="headertitle"> 24<div class="title">Heimbase</div> </div> 25</div><!--header--> 26<div class="contents"> 27 28<p>Registers a DB type for use with heim_db_create(). 29</p> 30<p>Registers a DB type for use with heim_db_create(). </p> 31<p>heim_db_register</p> 32<dl class="params"><dt>Parameters</dt><dd> 33 <table class="params"> 34 <tr><td class="paramname">dbtype</td><td>Name of DB type </td></tr> 35 <tr><td class="paramname">data</td><td>Private data argument to the dbtype's openf method </td></tr> 36 <tr><td class="paramname">plugin</td><td>Structure with DB type methods (function pointers)</td></tr> 37 </table> 38 </dd> 39</dl> 40<p>Backends that provide begin/commit/rollback methods must provide ACID semantics.</p> 41<p>The registered DB type will have ACID semantics for backends that do not provide begin/commit/rollback methods but do provide lock/unlock and rdjournal/wrjournal methods (using a replay log journalling scheme).</p> 42<p>If the registered DB type does not natively provide read vs. write transaction isolation but does provide a lock method then the DB will provide read/write transaction isolation.</p> 43<dl class="section return"><dt>Returns</dt><dd>ENOMEM on failure, else 0.</dd></dl> 44<p>Open a database of the given dbtype.</p> 45<p>Database type names can be composed of one or more pseudo-DB types and one concrete DB type joined with a '+' between each. For example: "transaction+bdb" might be a Berkeley DB with a layer above that provides transactions.</p> 46<p>Options may be provided via a dict (an associative array). Existing options include:</p> 47<ul> 48<li>"create", with any value (create if DB doesn't exist)</li> 49<li>"exclusive", with any value (exclusive create)</li> 50<li>"truncate", with any value (truncate the DB)</li> 51<li>"read-only", with any value (disallow writes)</li> 52<li>"sync", with any value (make transactions durable)</li> 53<li>"journal-name", with a string value naming a journal file name</li> 54</ul> 55<dl class="params"><dt>Parameters</dt><dd> 56 <table class="params"> 57 <tr><td class="paramname">dbtype</td><td>Name of DB type </td></tr> 58 <tr><td class="paramname">dbname</td><td>Name of DB (likely a file path) </td></tr> 59 <tr><td class="paramname">options</td><td>Options dict </td></tr> 60 <tr><td class="paramname">db</td><td>Output open DB handle </td></tr> 61 <tr><td class="paramname">error</td><td>Output error object</td></tr> 62 </table> 63 </dd> 64</dl> 65<dl class="section return"><dt>Returns</dt><dd>a DB handle</dd></dl> 66<p>Clone (duplicate) an open DB handle.</p> 67<p>This is useful for multi-threaded applications. Applications must synchronize access to any given DB handle.</p> 68<p>Returns EBUSY if there is an open transaction for the input db.</p> 69<dl class="params"><dt>Parameters</dt><dd> 70 <table class="params"> 71 <tr><td class="paramname">db</td><td>Open DB handle </td></tr> 72 <tr><td class="paramname">error</td><td>Output error object</td></tr> 73 </table> 74 </dd> 75</dl> 76<dl class="section return"><dt>Returns</dt><dd>a DB handle</dd></dl> 77<p>Open a transaction on the given db.</p> 78<dl class="params"><dt>Parameters</dt><dd> 79 <table class="params"> 80 <tr><td class="paramname">db</td><td>Open DB handle </td></tr> 81 <tr><td class="paramname">error</td><td>Output error object</td></tr> 82 </table> 83 </dd> 84</dl> 85<dl class="section return"><dt>Returns</dt><dd>0 on success, system error otherwise</dd></dl> 86<p>Commit an open transaction on the given db.</p> 87<dl class="params"><dt>Parameters</dt><dd> 88 <table class="params"> 89 <tr><td class="paramname">db</td><td>Open DB handle </td></tr> 90 <tr><td class="paramname">error</td><td>Output error object</td></tr> 91 </table> 92 </dd> 93</dl> 94<dl class="section return"><dt>Returns</dt><dd>0 on success, system error otherwise</dd></dl> 95<p>Rollback an open transaction on the given db.</p> 96<dl class="params"><dt>Parameters</dt><dd> 97 <table class="params"> 98 <tr><td class="paramname">db</td><td>Open DB handle </td></tr> 99 <tr><td class="paramname">error</td><td>Output error object</td></tr> 100 </table> 101 </dd> 102</dl> 103<dl class="section return"><dt>Returns</dt><dd>0 on success, system error otherwise</dd></dl> 104<p>Get type ID of heim_db_t objects.</p> 105<p>Lookup a key's value in the DB.</p> 106<p>Returns 0 on success, -1 if the key does not exist in the DB, or a system error number on failure.</p> 107<dl class="params"><dt>Parameters</dt><dd> 108 <table class="params"> 109 <tr><td class="paramname">db</td><td>Open DB handle </td></tr> 110 <tr><td class="paramname">key</td><td>Key </td></tr> 111 <tr><td class="paramname">error</td><td>Output error object</td></tr> 112 </table> 113 </dd> 114</dl> 115<dl class="section return"><dt>Returns</dt><dd>the value (retained), if there is one for the given key</dd></dl> 116<p>Set a key's value in the DB.</p> 117<dl class="params"><dt>Parameters</dt><dd> 118 <table class="params"> 119 <tr><td class="paramname">db</td><td>Open DB handle </td></tr> 120 <tr><td class="paramname">key</td><td>Key </td></tr> 121 <tr><td class="paramname">value</td><td>Value (if NULL the key will be deleted, but empty is OK) </td></tr> 122 <tr><td class="paramname">error</td><td>Output error object</td></tr> 123 </table> 124 </dd> 125</dl> 126<dl class="section return"><dt>Returns</dt><dd>0 on success, system error otherwise</dd></dl> 127<p>Delete a key and its value from the DB</p> 128<dl class="params"><dt>Parameters</dt><dd> 129 <table class="params"> 130 <tr><td class="paramname">db</td><td>Open DB handle </td></tr> 131 <tr><td class="paramname">key</td><td>Key </td></tr> 132 <tr><td class="paramname">error</td><td>Output error object</td></tr> 133 </table> 134 </dd> 135</dl> 136<dl class="section return"><dt>Returns</dt><dd>0 on success, system error otherwise</dd></dl> 137<p>Iterate a callback function over keys and values from a DB.</p> 138<dl class="params"><dt>Parameters</dt><dd> 139 <table class="params"> 140 <tr><td class="paramname">db</td><td>Open DB handle </td></tr> 141 <tr><td class="paramname">iter_data</td><td>Callback function's private data </td></tr> 142 <tr><td class="paramname">iter_f</td><td>Callback function, called once per-key/value pair </td></tr> 143 <tr><td class="paramname">error</td><td>Output error object</td></tr> 144 </table> 145 </dd> 146</dl> 147<p>Get a node in a heim_object tree by path</p> 148<dl class="params"><dt>Parameters</dt><dd> 149 <table class="params"> 150 <tr><td class="paramname">ptr</td><td>tree </td></tr> 151 <tr><td class="paramname">error</td><td>error (output) </td></tr> 152 <tr><td class="paramname">ap</td><td>NULL-terminated va_list of heim_object_ts that form a path</td></tr> 153 </table> 154 </dd> 155</dl> 156<dl class="section return"><dt>Returns</dt><dd>object (not retained) if found</dd></dl> 157<p>Get a node in a tree by path, with retained reference</p> 158<dl class="params"><dt>Parameters</dt><dd> 159 <table class="params"> 160 <tr><td class="paramname">ptr</td><td>tree </td></tr> 161 <tr><td class="paramname">error</td><td>error (output) </td></tr> 162 <tr><td class="paramname">ap</td><td>NULL-terminated va_list of heim_object_ts that form a path</td></tr> 163 </table> 164 </dd> 165</dl> 166<dl class="section return"><dt>Returns</dt><dd>retained object if found</dd></dl> 167<p>Get a node in a tree by path</p> 168<dl class="params"><dt>Parameters</dt><dd> 169 <table class="params"> 170 <tr><td class="paramname">ptr</td><td>tree </td></tr> 171 <tr><td class="paramname">error</td><td>error (output) </td></tr> 172 <tr><td class="paramname">...</td><td>NULL-terminated va_list of heim_object_ts that form a path</td></tr> 173 </table> 174 </dd> 175</dl> 176<dl class="section return"><dt>Returns</dt><dd>object (not retained) if found</dd></dl> 177<p>Get a node in a tree by path, with retained reference</p> 178<dl class="params"><dt>Parameters</dt><dd> 179 <table class="params"> 180 <tr><td class="paramname">ptr</td><td>tree </td></tr> 181 <tr><td class="paramname">error</td><td>error (output) </td></tr> 182 <tr><td class="paramname">...</td><td>NULL-terminated va_list of heim_object_ts that form a path</td></tr> 183 </table> 184 </dd> 185</dl> 186<dl class="section return"><dt>Returns</dt><dd>retained object if found</dd></dl> 187<p>Create a path in a heim_object_t tree</p> 188<dl class="params"><dt>Parameters</dt><dd> 189 <table class="params"> 190 <tr><td class="paramname">ptr</td><td>the tree </td></tr> 191 <tr><td class="paramname">size</td><td>the size of the heim_dict_t nodes to be created </td></tr> 192 <tr><td class="paramname">leaf</td><td>leaf node to be added, if any </td></tr> 193 <tr><td class="paramname">error</td><td>error (output) </td></tr> 194 <tr><td class="paramname">ap</td><td>NULL-terminated of path component objects</td></tr> 195 </table> 196 </dd> 197</dl> 198<p>Create a path of heim_dict_t interior nodes in a given heim_object_t tree, as necessary, and set/replace a leaf, if given (if leaf is NULL then the leaf is not deleted).</p> 199<dl class="section return"><dt>Returns</dt><dd>0 on success, else a system error</dd></dl> 200<p>Create a path in a heim_object_t tree</p> 201<dl class="params"><dt>Parameters</dt><dd> 202 <table class="params"> 203 <tr><td class="paramname">ptr</td><td>the tree </td></tr> 204 <tr><td class="paramname">size</td><td>the size of the heim_dict_t nodes to be created </td></tr> 205 <tr><td class="paramname">leaf</td><td>leaf node to be added, if any </td></tr> 206 <tr><td class="paramname">error</td><td>error (output) </td></tr> 207 <tr><td class="paramname">...</td><td>NULL-terminated list of path component objects</td></tr> 208 </table> 209 </dd> 210</dl> 211<p>Create a path of heim_dict_t interior nodes in a given heim_object_t tree, as necessary, and set/replace a leaf, if given (if leaf is NULL then the leaf is not deleted).</p> 212<dl class="section return"><dt>Returns</dt><dd>0 on success, else a system error</dd></dl> 213<p>Delete leaf node named by a path in a heim_object_t tree</p> 214<dl class="params"><dt>Parameters</dt><dd> 215 <table class="params"> 216 <tr><td class="paramname">ptr</td><td>the tree </td></tr> 217 <tr><td class="paramname">error</td><td>error (output) </td></tr> 218 <tr><td class="paramname">ap</td><td>NULL-terminated list of path component objects</td></tr> 219 </table> 220 </dd> 221</dl> 222<p>Dump a heimbase object to stderr (useful from the debugger!)</p> 223<dl class="params"><dt>Parameters</dt><dd> 224 <table class="params"> 225 <tr><td class="paramname">obj</td><td>object to dump using JSON or JSON-like format </td></tr> 226 </table> 227 </dd> 228</dl> 229</div><!-- contents --> 230<hr size="1"><address style="text-align: right;"><small> 231Generated on Tue Nov 15 2022 14:04:25 for Heimdal base library by <a href="http://www.doxygen.org/index.html"><img src="doxygen.png" alt="doxygen" align="middle" border="0"></a> 1.9.1</small></address> 232</body> 233</html> 234
