.\"	$NetBSD: heimbase.3,v 1.3 2023/06/19 21:41:39 christos Exp $
.\"
.TH "heimbase" 3 "Tue Nov 15 2022" "Version 7.8.0" "Heimdal base library" \" -*- nroff -*-
.ad l
.nh
.SH NAME
heimbase \- Heimbase
.PP
 \- Registers a DB type for use with heim_db_create()\&.  

.SH SYNOPSIS
.br
.PP
.SH "Detailed Description"
.PP 
Registers a DB type for use with heim_db_create()\&. 

heim_db_register
.PP
\fBParameters\fP
.RS 4
\fIdbtype\fP Name of DB type 
.br
\fIdata\fP Private data argument to the dbtype's openf method 
.br
\fIplugin\fP Structure with DB type methods (function pointers)
.RE
.PP
Backends that provide begin/commit/rollback methods must provide ACID semantics\&.
.PP
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)\&.
.PP
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\&.
.PP
\fBReturns\fP
.RS 4
ENOMEM on failure, else 0\&.
.RE
.PP
Open a database of the given dbtype\&.
.PP
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\&.
.PP
Options may be provided via a dict (an associative array)\&. Existing options include:
.PP
.IP "\(bu" 2
'create', with any value (create if DB doesn't exist)
.IP "\(bu" 2
'exclusive', with any value (exclusive create)
.IP "\(bu" 2
'truncate', with any value (truncate the DB)
.IP "\(bu" 2
'read-only', with any value (disallow writes)
.IP "\(bu" 2
'sync', with any value (make transactions durable)
.IP "\(bu" 2
'journal-name', with a string value naming a journal file name
.PP
.PP
\fBParameters\fP
.RS 4
\fIdbtype\fP Name of DB type 
.br
\fIdbname\fP Name of DB (likely a file path) 
.br
\fIoptions\fP Options dict 
.br
\fIdb\fP Output open DB handle 
.br
\fIerror\fP Output error object
.RE
.PP
\fBReturns\fP
.RS 4
a DB handle
.RE
.PP
Clone (duplicate) an open DB handle\&.
.PP
This is useful for multi-threaded applications\&. Applications must synchronize access to any given DB handle\&.
.PP
Returns EBUSY if there is an open transaction for the input db\&.
.PP
\fBParameters\fP
.RS 4
\fIdb\fP Open DB handle 
.br
\fIerror\fP Output error object
.RE
.PP
\fBReturns\fP
.RS 4
a DB handle
.RE
.PP
Open a transaction on the given db\&.
.PP
\fBParameters\fP
.RS 4
\fIdb\fP Open DB handle 
.br
\fIerror\fP Output error object
.RE
.PP
\fBReturns\fP
.RS 4
0 on success, system error otherwise
.RE
.PP
Commit an open transaction on the given db\&.
.PP
\fBParameters\fP
.RS 4
\fIdb\fP Open DB handle 
.br
\fIerror\fP Output error object
.RE
.PP
\fBReturns\fP
.RS 4
0 on success, system error otherwise
.RE
.PP
Rollback an open transaction on the given db\&.
.PP
\fBParameters\fP
.RS 4
\fIdb\fP Open DB handle 
.br
\fIerror\fP Output error object
.RE
.PP
\fBReturns\fP
.RS 4
0 on success, system error otherwise
.RE
.PP
Get type ID of heim_db_t objects\&.
.PP
Lookup a key's value in the DB\&.
.PP
Returns 0 on success, -1 if the key does not exist in the DB, or a system error number on failure\&.
.PP
\fBParameters\fP
.RS 4
\fIdb\fP Open DB handle 
.br
\fIkey\fP Key 
.br
\fIerror\fP Output error object
.RE
.PP
\fBReturns\fP
.RS 4
the value (retained), if there is one for the given key
.RE
.PP
Set a key's value in the DB\&.
.PP
\fBParameters\fP
.RS 4
\fIdb\fP Open DB handle 
.br
\fIkey\fP Key 
.br
\fIvalue\fP Value (if NULL the key will be deleted, but empty is OK) 
.br
\fIerror\fP Output error object
.RE
.PP
\fBReturns\fP
.RS 4
0 on success, system error otherwise
.RE
.PP
Delete a key and its value from the DB
.PP
\fBParameters\fP
.RS 4
\fIdb\fP Open DB handle 
.br
\fIkey\fP Key 
.br
\fIerror\fP Output error object
.RE
.PP
\fBReturns\fP
.RS 4
0 on success, system error otherwise
.RE
.PP
Iterate a callback function over keys and values from a DB\&.
.PP
\fBParameters\fP
.RS 4
\fIdb\fP Open DB handle 
.br
\fIiter_data\fP Callback function's private data 
.br
\fIiter_f\fP Callback function, called once per-key/value pair 
.br
\fIerror\fP Output error object
.RE
.PP
Get a node in a heim_object tree by path
.PP
\fBParameters\fP
.RS 4
\fIptr\fP tree 
.br
\fIerror\fP error (output) 
.br
\fIap\fP NULL-terminated va_list of heim_object_ts that form a path
.RE
.PP
\fBReturns\fP
.RS 4
object (not retained) if found
.RE
.PP
Get a node in a tree by path, with retained reference
.PP
\fBParameters\fP
.RS 4
\fIptr\fP tree 
.br
\fIerror\fP error (output) 
.br
\fIap\fP NULL-terminated va_list of heim_object_ts that form a path
.RE
.PP
\fBReturns\fP
.RS 4
retained object if found
.RE
.PP
Get a node in a tree by path
.PP
\fBParameters\fP
.RS 4
\fIptr\fP tree 
.br
\fIerror\fP error (output) 
.br
\fI\&.\&.\&.\fP NULL-terminated va_list of heim_object_ts that form a path
.RE
.PP
\fBReturns\fP
.RS 4
object (not retained) if found
.RE
.PP
Get a node in a tree by path, with retained reference
.PP
\fBParameters\fP
.RS 4
\fIptr\fP tree 
.br
\fIerror\fP error (output) 
.br
\fI\&.\&.\&.\fP NULL-terminated va_list of heim_object_ts that form a path
.RE
.PP
\fBReturns\fP
.RS 4
retained object if found
.RE
.PP
Create a path in a heim_object_t tree
.PP
\fBParameters\fP
.RS 4
\fIptr\fP the tree 
.br
\fIsize\fP the size of the heim_dict_t nodes to be created 
.br
\fIleaf\fP leaf node to be added, if any 
.br
\fIerror\fP error (output) 
.br
\fIap\fP NULL-terminated of path component objects
.RE
.PP
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)\&.
.PP
\fBReturns\fP
.RS 4
0 on success, else a system error
.RE
.PP
Create a path in a heim_object_t tree
.PP
\fBParameters\fP
.RS 4
\fIptr\fP the tree 
.br
\fIsize\fP the size of the heim_dict_t nodes to be created 
.br
\fIleaf\fP leaf node to be added, if any 
.br
\fIerror\fP error (output) 
.br
\fI\&.\&.\&.\fP NULL-terminated list of path component objects
.RE
.PP
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)\&.
.PP
\fBReturns\fP
.RS 4
0 on success, else a system error
.RE
.PP
Delete leaf node named by a path in a heim_object_t tree
.PP
\fBParameters\fP
.RS 4
\fIptr\fP the tree 
.br
\fIerror\fP error (output) 
.br
\fIap\fP NULL-terminated list of path component objects
.RE
.PP
Dump a heimbase object to stderr (useful from the debugger!)
.PP
\fBParameters\fP
.RS 4
\fIobj\fP object to dump using JSON or JSON-like format 
.RE
.PP

.SH "Author"
.PP 
Generated automatically by Doxygen for Heimdal base library from the source code\&.