Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help 
AG_DB(3)		    Library Functions Manual		      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.

Agar 1.7		       December	21, 2022		      AG_DB(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=AG_Db&sektion=3&manpath=FreeBSD+Ports+14.3.quarterly>

home | help