<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html><head><meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
<title>Heimbase</title>
<link href="doxygen.css" rel="stylesheet" type="text/css">
<link href="tabs.css" rel="stylesheet" type="text/css">
</head><body>
<p>
<a href="http://www.h5l.org/"><img src="http://www.h5l.org/keyhole-heimdal.png" alt="keyhole logo"/></a>
</p>
<!-- end of header marker -->
<!-- Generated by Doxygen 1.9.1 -->
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */
$(function() {
initMenu('',false,false,'search.php','Search');
});
/* @license-end */</script>
<div id="main-nav"></div>
</div><!-- top -->
<div class="header">
<div class="headertitle">
<div class="title">Heimbase</div> </div>
</div><!--header-->
<div class="contents">
<p>Registers a DB type for use with heim_db_create().
</p>
<p>Registers a DB type for use with heim_db_create(). </p>
<p>heim_db_register</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">dbtype</td><td>Name of DB type </td></tr>
<tr><td class="paramname">data</td><td>Private data argument to the dbtype's openf method </td></tr>
<tr><td class="paramname">plugin</td><td>Structure with DB type methods (function pointers)</td></tr>
</table>
</dd>
</dl>
<p>Backends that provide begin/commit/rollback methods must provide ACID semantics.</p>
<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>
<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>
<dl class="section return"><dt>Returns</dt><dd>ENOMEM on failure, else 0.</dd></dl>
<p>Open a database of the given dbtype.</p>
<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>
<p>Options may be provided via a dict (an associative array). Existing options include:</p>
<ul>
<li>"create", with any value (create if DB doesn't exist)</li>
<li>"exclusive", with any value (exclusive create)</li>
<li>"truncate", with any value (truncate the DB)</li>
<li>"read-only", with any value (disallow writes)</li>
<li>"sync", with any value (make transactions durable)</li>
<li>"journal-name", with a string value naming a journal file name</li>
</ul>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">dbtype</td><td>Name of DB type </td></tr>
<tr><td class="paramname">dbname</td><td>Name of DB (likely a file path) </td></tr>
<tr><td class="paramname">options</td><td>Options dict </td></tr>
<tr><td class="paramname">db</td><td>Output open DB handle </td></tr>
<tr><td class="paramname">error</td><td>Output error object</td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>a DB handle</dd></dl>
<p>Clone (duplicate) an open DB handle.</p>
<p>This is useful for multi-threaded applications. Applications must synchronize access to any given DB handle.</p>
<p>Returns EBUSY if there is an open transaction for the input db.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">db</td><td>Open DB handle </td></tr>
<tr><td class="paramname">error</td><td>Output error object</td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>a DB handle</dd></dl>
<p>Open a transaction on the given db.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">db</td><td>Open DB handle </td></tr>
<tr><td class="paramname">error</td><td>Output error object</td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>0 on success, system error otherwise</dd></dl>
<p>Commit an open transaction on the given db.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">db</td><td>Open DB handle </td></tr>
<tr><td class="paramname">error</td><td>Output error object</td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>0 on success, system error otherwise</dd></dl>
<p>Rollback an open transaction on the given db.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">db</td><td>Open DB handle </td></tr>
<tr><td class="paramname">error</td><td>Output error object</td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>0 on success, system error otherwise</dd></dl>
<p>Get type ID of heim_db_t objects.</p>
<p>Lookup a key's value in the DB.</p>
<p>Returns 0 on success, -1 if the key does not exist in the DB, or a system error number on failure.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">db</td><td>Open DB handle </td></tr>
<tr><td class="paramname">key</td><td>Key </td></tr>
<tr><td class="paramname">error</td><td>Output error object</td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>the value (retained), if there is one for the given key</dd></dl>
<p>Set a key's value in the DB.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">db</td><td>Open DB handle </td></tr>
<tr><td class="paramname">key</td><td>Key </td></tr>
<tr><td class="paramname">value</td><td>Value (if NULL the key will be deleted, but empty is OK) </td></tr>
<tr><td class="paramname">error</td><td>Output error object</td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>0 on success, system error otherwise</dd></dl>
<p>Delete a key and its value from the DB</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">db</td><td>Open DB handle </td></tr>
<tr><td class="paramname">key</td><td>Key </td></tr>
<tr><td class="paramname">error</td><td>Output error object</td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>0 on success, system error otherwise</dd></dl>
<p>Iterate a callback function over keys and values from a DB.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">db</td><td>Open DB handle </td></tr>
<tr><td class="paramname">iter_data</td><td>Callback function's private data </td></tr>
<tr><td class="paramname">iter_f</td><td>Callback function, called once per-key/value pair </td></tr>
<tr><td class="paramname">error</td><td>Output error object</td></tr>
</table>
</dd>
</dl>
<p>Get a node in a heim_object tree by path</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">ptr</td><td>tree </td></tr>
<tr><td class="paramname">error</td><td>error (output) </td></tr>
<tr><td class="paramname">ap</td><td>NULL-terminated va_list of heim_object_ts that form a path</td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>object (not retained) if found</dd></dl>
<p>Get a node in a tree by path, with retained reference</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">ptr</td><td>tree </td></tr>
<tr><td class="paramname">error</td><td>error (output) </td></tr>
<tr><td class="paramname">ap</td><td>NULL-terminated va_list of heim_object_ts that form a path</td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>retained object if found</dd></dl>
<p>Get a node in a tree by path</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">ptr</td><td>tree </td></tr>
<tr><td class="paramname">error</td><td>error (output) </td></tr>
<tr><td class="paramname">...</td><td>NULL-terminated va_list of heim_object_ts that form a path</td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>object (not retained) if found</dd></dl>
<p>Get a node in a tree by path, with retained reference</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">ptr</td><td>tree </td></tr>
<tr><td class="paramname">error</td><td>error (output) </td></tr>
<tr><td class="paramname">...</td><td>NULL-terminated va_list of heim_object_ts that form a path</td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>retained object if found</dd></dl>
<p>Create a path in a heim_object_t tree</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">ptr</td><td>the tree </td></tr>
<tr><td class="paramname">size</td><td>the size of the heim_dict_t nodes to be created </td></tr>
<tr><td class="paramname">leaf</td><td>leaf node to be added, if any </td></tr>
<tr><td class="paramname">error</td><td>error (output) </td></tr>
<tr><td class="paramname">ap</td><td>NULL-terminated of path component objects</td></tr>
</table>
</dd>
</dl>
<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>
<dl class="section return"><dt>Returns</dt><dd>0 on success, else a system error</dd></dl>
<p>Create a path in a heim_object_t tree</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">ptr</td><td>the tree </td></tr>
<tr><td class="paramname">size</td><td>the size of the heim_dict_t nodes to be created </td></tr>
<tr><td class="paramname">leaf</td><td>leaf node to be added, if any </td></tr>
<tr><td class="paramname">error</td><td>error (output) </td></tr>
<tr><td class="paramname">...</td><td>NULL-terminated list of path component objects</td></tr>
</table>
</dd>
</dl>
<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>
<dl class="section return"><dt>Returns</dt><dd>0 on success, else a system error</dd></dl>
<p>Delete leaf node named by a path in a heim_object_t tree</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">ptr</td><td>the tree </td></tr>
<tr><td class="paramname">error</td><td>error (output) </td></tr>
<tr><td class="paramname">ap</td><td>NULL-terminated list of path component objects</td></tr>
</table>
</dd>
</dl>
<p>Dump a heimbase object to stderr (useful from the debugger!)</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">obj</td><td>object to dump using JSON or JSON-like format </td></tr>
</table>
</dd>
</dl>
</div><!-- contents -->
<hr size="1"><address style="text-align: right;"><small>
Generated 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>
</body>
</html>