Agar


Note: The Agar manual pages follow certain conventions, notably concerning function return values. Please read AG_Intro(3) first.

SYNOPSIS

#include <agar/core.h>

DESCRIPTION

AG_Db provides a simple interface to a database consisting of key/value pairs (e.g., a Berkeley DB file).

In the base AG_Db interface, the key and value consist of arbitrary data. Functions are provided for convenience where C strings are used as keys. Using the AG_DbObject(3) class, the value can be made to consist of serialized AG_Object(3) data.

INTERFACE


AG_Db * AG_DbNew (enum ag_db_type type)

AG_Db * AG_DbNewDB4 (const char *path, enum ag_db4_type type, Uint32 flags)

AG_List * AG_DbListKeys (AG_Db *db)

int AG_DbExists (AG_Db *db, const char *key)

int AG_DbExistsDK (AG_Db *db, const void *keyData, size_t keySize)

int AG_DbLookup (AG_Db *db, AG_DbEntry *dbe, const char *key)

int AG_DbLookupDK (AG_Db *db, AG_DbEntry *dbe, const void *keyData, size_t keySize)

int AG_DbDelete (AG_Db *db, const char *key)

int AG_DbDeleteDK (AG_Db *db, const void *keyData, size_t keySize)

int AG_DbPut (AG_Db *db, AG_DbEntry *dbe)

int AG_DbSync (AG_Db *db)


The AG_DbNew() function creates a new, generic AG_Db object. The type argument specifies the backend to use:
AG_DB_DUMMYDummy (no-op).
AG_DB_DB4Berkeley DB v4 database.

The AG_DbNewDB4() function opens a Berlekey DB database. The path argument specifies the database file name. type specifies the type of database to use:
AG_DB4_BTREESorted, balanced tree structure.
AG_DB4_HASHExtensible, dynamic hashing scheme.
AG_DB4_RECNOEntries associated with record numbers (fixed-length).
AG_DB4_QUEUEEntries associated with record numbers (fixed or variable-length).

Accepted flags options include:
AG_DB4_CREATECreate the database file if it does not already exist.
AG_DB4_EXCLFail if the database file already exists.
AG_DB4_RDONLYOpen the database in read-only mode, such that write operations will fail.
AG_DB4_TRUNCATETruncate the database file (where supported by the filesystem).
AG_DB4_THREADEnable thread safety.
AG_DB4_MULTIVERSIONEnable multiversion concurrency control (see Berkeley DB manual).
AG_DB4_NOMMAPDisable mmap(2) of the database file into the process's address space.
AG_DB4_AUTO_COMMITEnclose the open operation within a transaction (see Berkeley DB manual).

AG_DbListKeys() reads the database entries sequentially and returns an AG_List(3) with the keys (as strings) for all entries.

AG_DbExists() evaluates to 1 if the given key exists in the database. The AG_DbExistsDK() variant accepts arbitrary data as key. If the key is not found, 0 is returned.

The AG_DbLookup() function looks up the specified key as string (the AG_DbLookupDK() variant accepts arbitrary data as key). If an entry is found, a description of its contents are written to dbe and the function returns 0. The AG_DbEntry structure is defined as: 
typedef struct ag_db_entry {
	AG_Db *db;			/* Back pointer to Db */
	void *key, *data;		/* Pointer to key/data */
	size_t keySize, dataSize;	/* Key/data size (bytes) */
} AG_DbEntry;

The AG_DbDelete() function deletes the named entry associated with key, from the database (the AG_DbDeleteDK() variant accepts arbitrary data as key).

The AG_DbPut() function writes the entry described by dbe to the database (see AG_DbLookup() for a description of the AG_DbEntry structure).

AG_DbSync() synchronizes the actual contents of db with any associated database files.

SEE ALSO

AG_Intro(3), AG_DbObject(3), AG_List(3), AG_Variable(3)

HISTORY

The AG_Db interface first appeared in Agar 1.3.4