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 argu-
     ments.  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  in-
     clude:
     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+15.1.quarterly>

home | help