<-- Back to AG_Intro.3


#include <agar/core.h>


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 */
	size_t size;		/* Key/data size (bytes) */
} AG_Dbt;


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:
hashExtended Linear Hashing (Berkeley DB)
btreeSorted, Balanced Tree Structure (Berkeley DB)
mysqlMySQL 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.




The AG_Db interface first appeared in Agar 1.5.0.