heimbase(3)

💖 NAME 💖

heimbase(3) from the Heimdal base library — heimbase — Heimbase ✨

• Registers a DB type for use with heim_db_create(). 💅

---

🌸 SYNOPSIS 🌸

Detailed Description

Registers a DB type for use with heim_db_create(). Okay bestie, let's get into it. 💖

heim_db_register

Parameters:

• dbtype — Name of DB type
• data — Private data argument to the dbtype's openf method
• plugin — Structure with DB type methods (function pointers)

Backends that provide begin/commit/rollback methods must provide ACID semantics. No cap. 🔥

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). Slay. ✨

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. Periodt. 💅

Returns:

• ENOMEM on failure, else 0.

---

Open a database of the given dbtype. 🎀

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. Iconic.

Options may be provided via a dict (an associative array). Existing options include:

(bestie, the source literally has six blank bullet points here — no cap 💀)

Parameters:

• dbtype — Name of DB type
• dbname — Name of DB (likely a file path)
• options — Options dict
• db — Output open DB handle
• error — Output error object

Returns:

• a DB handle

---

Clone (duplicate) an open DB handle. 🦋

This is useful for multi-threaded applications. Applications must synchronize access to any given DB handle. Fr fr.

Returns EBUSY if there is an open transaction for the input db.

Parameters:

• db — Open DB handle
• error — Output error object

Returns:

• a DB handle

---

Open a transaction on the given db. 💜

Parameters:

• db — Open DB handle
• error — Output error object

Returns:

• 0 on success, system error otherwise

---

Commit an open transaction on the given db. ✨

Parameters:

• db — Open DB handle
• error — Output error object

Returns:

• 0 on success, system error otherwise

---

Rollback an open transaction on the given db. 💅

Parameters:

• db — Open DB handle
• error — Output error object

Returns:

• 0 on success, system error otherwise

---

Get type ID of heim_db_t objects. 👑

---

Lookup a key's value in the DB. 🔍

Returns 0 on success, -1 if the key does not exist in the DB, or a system error number on failure.

Parameters:

• db — Open DB handle
• key — Key
• error — Output error object

Returns:

• the value (retained), if there is one for the given key

---

Set a key's value in the DB. 💖

Parameters:

• db — Open DB handle
• key — Key
• value — Value (if NULL the key will be deleted, but empty is OK)
• error — Output error object

Returns:

• 0 on success, system error otherwise

---

Delete a key and its value from the DB. 🗑️

Parameters:

• db — Open DB handle
• key — Key
• error — Output error object

Returns:

• 0 on success, system error otherwise

---

Iterate a callback function over keys and values from a DB. 🌈

Parameters:

• db — Open DB handle
• iter_data — Callback function's private data
• iter_f — Callback function, called once per-key/value pair
• error — Output error object

---

Get a node in a heim_object tree by path. 🌳

Parameters:

• ptr — tree
• error — error (output)
• ap — NULL-terminated va_list of heim_object_ts that form a path

Returns:

• object (not retained) if found

---

Get a node in a tree by path, with retained reference. 💫

Parameters:

• ptr — tree
• error — error (output)
• ap — NULL-terminated va_list of heim_object_ts that form a path

Returns:

• retained object if found

---

Get a node in a tree by path. 🌸

Parameters:

• ptr — tree
• error — error (output)
• ... — NULL-terminated va_list of heim_object_ts that form a path

Returns:

• object (not retained) if found

---

Get a node in a tree by path, with retained reference. 🎀

Parameters:

• ptr — tree
• error — error (output)
• ... — NULL-terminated va_list of heim_object_ts that form a path

Returns:

• retained object if found

---

Create a path in a heim_object_t tree. 🛠️

Parameters:

• ptr — the tree
• size — the size of the heim_dict_t nodes to be created
• leaf — leaf node to be added, if any
• error — error (output)
• ap — NULL-terminated of path component objects

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). 💅

Returns:

• 0 on success, else a system error

---

Create a path in a heim_object_t tree. 🧚

Parameters:

• ptr — the tree
• size — the size of the heim_dict_t nodes to be created
• leaf — leaf node to be added, if any
• error — error (output)
• ... — NULL-terminated list of path component objects

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). ✨

Returns:

• 0 on success, else a system error

---

Delete leaf node named by a path in a heim_object_t tree. 🍂

Parameters:

• ptr — the tree
• error — error (output)
• ap — NULL-terminated list of path component objects

---

Dump a heimbase object to stderr (useful from the debugger!). 🐛

Parameters:

• obj — object to dump using JSON or JSON-like format

---

👑 Author 👑

Generated automatically by Doxygen for Heimdal base library from the source code. 💖

---

Version 7.8.0, dated Tue Nov 15 2022, and it's the heimbase(3) page. Bye bestie! 🫶💅