AG_DB(3)

NAME
AG_Db - agar key/value database access object

SYNOPSIS

    #include <agar/core.h>

DESCRIPTION
AG_Db provides a simple interface for accessing databases of key/value pairs. Various database backends are implemented, such as "hash", "btree" and "mysql". Different backends may support different key types (e.g., raw data, C strings or record numbers).

Many of the functions described below accept Berkeley DB style AG_Dbt arguments. This structure is defined as:

    typedef struct ag_dbt {
    	void   *data;		/* Pointer to key or data */
    	AG_Size size;		/* Key/data size (bytes) */
    } AG_Dbt;

INHERITANCE HIERARCHY
AG_Object(3) -> AG_Db.

INTERFACE
AG_Db * AG_DbNew(const char *backend)

int AG_DbOpen(AG_Db *db, const char *path, Uint flags)

void AG_DbClose(AG_Db *db)

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

int AG_DbDel(AG_Db *db, const AG_Dbt *key)

int AG_DbGet(AG_Db *db, const AG_Dbt *key, AG_Dbt *val)

int AG_DbPut(AG_Db *db, const AG_Dbt *key, const AG_Dbt *val)

int AG_DbSync(AG_Db *db)

The AG_DbNew() function creates a new AG_Db object instance. The backend argument specifies the database backend to use. Available backends include:
hash
    Extended Linear Hashing (Berkeley DB)
btree
    Sorted, Balanced Tree Structure (Berkeley DB)
mysql
    MySQL database storage

The AG_DbOpen() function opens the database for further access. The path argument is backend-specific. With "hash" and "btree, it may be a file name. With "mysql", it may be set to a database name (or set to NULL to use the default database settings).

The AG_DbClose() function closes the database.

The AG_DbExists() function returns 1 if the given key matches an entry in the database, or 0 if no match was found.

The AG_DbDel() function deletes the named entry associated with key.

The AG_DbGet() function retrieves the database entry referenced by the specified key. The data is returned as newly-allocated memory in val, and must be freed after use. It is not necessary to initialize the supplied val argument.

The AG_DbPut() function writes the specified database entry.

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

EXAMPLES
The following code creates a new database or accesses the existing database my.db, checks whether a record exists under "mykey" and if not, create one containing the string "myval".

    AG_Db *db;
    AG_Dbt dbtKey, dbtVal;
    char key[8];
    if ((db = AG_DbNew("btree")) == NULL)
    	AG_FatalError(NULL);
    if (AG_DbOpen(db, "my.db", 0) != 0)
    	AG_FatalError(NULL);
    dbtKey.data = "mykey";
    dbtKey.size = 5;
    if (!AG_DbExists(db, &dbtKey)) {
    	dbtVal.data = "myval";
    	dbtVal.size = 5;
    	if (AG_DbPut(db, &dbtKey, &dbtVal)) != 0)
    		AG_Verbose("Put failed (%s)\n", AG_GetError());
    }
    AG_DbClose(db);
    AG_ObjectDestroy(db);

SEE ALSO
AG_Intro(3), AG_Object(3)

HISTORY
The AG_Db interface first appeared in Agar 1.5.0.