dksdbi.h File Reference

Simple unique API to access different databases. More...

#include <dk.h>

Go to the source code of this file.

Defines

#define DK_SDBI_TYPE_AUTO   0
 Database type: Choose automatically.
#define DK_SDBI_TYPE_BDB   1
 Database type: Berkeley DB.
#define DK_SDBI_TYPE_NDBM   2
 Database type: NDBM.
#define DK_SDBI_TYPE_GDBM   3
 Database type: GDBM.
#define DK_SDBI_MODE_READ   1
 Database access mode: read.
#define DK_SDBI_MODE_WRITE   2
 Database access mode: write.
#define DK_SDBI_MODE_RDWR   (DK_SDBI_MODE_READ|DK_SDBI_MODE_WRITE)
 Database access mode: read and write.
#define DK_SDBI_MODE_TRUNCATE   4
 Database access mode: Truncate existing database.
#define DK_SDBI_INSMOD_NO_REPLACE   1
 Insertion mode: Do not replace exising entries.

Typedefs

typedef void * dk_sdbi_t
 Pointer to database.
typedef int dk_sdbi_fct_t (\void *o, void *kp, size_t kl, void *vp, size_t vl)
 Traversal function.

Functions

dk_sdbi_t dksdbi_open (char *n, int t, int a, int m, int b)
 Open a database and return database access structure.
void dksdbi_close (dk_sdbi_t d)
 Destroy database access structure obtained from dksdbi_open() and release memory.
int dksdbi_store (\dk_sdbi_t d, void *kp, size_t kl, void *vp, size_t vl, int i)
 Store key/value pair in database.
int dksdbi_string_store (dk_sdbi_t d, char *k, char *v, int i)
 Store key/value pair of strings in database.
int dksdbi_fetch (dk_sdbi_t d, void *kp, size_t kl, void *vp, size_t *vl)
 Fetch key/value pair from database.
int dksdbi_string_fetch (dk_sdbi_t d, char *k, char *v, size_t s)
 Fetch string entry from database.
int dksdbi_delete (dk_sdbi_t d, char *k, size_t l)
 Delete entry from database.
int dksdbi_string_delete (dk_sdbi_t d, char *k)
 Delete string entry from database.
int dksdbi_remove_file (char *n, int t)
 Remove a database file (or file pair).
int dksdbi_traverse (dk_sdbi_t d, void *o, dk_sdbi_fct_t *f)
 Traverse database.
int dksdbi_sync (dk_sdbi_t d)
 Flush database to disk.


Detailed Description

Simple unique API to access different databases.

This module provides a simple unique API to access GDBM, NDBM and Berkeley DB data bases. The appropriate libraries are used to do the real work, this module only provides an API.

Unless otherwise stated, int functions in this module return a positive number to indicate success or a true condition, 0 to indicate an error or an unfullfilled condition. Pointer functions return valid pointers on success, NULL on error.


Define Documentation

#define DK_SDBI_INSMOD_NO_REPLACE   1

Insertion mode: Do not replace exising entries.

#define DK_SDBI_MODE_RDWR   (DK_SDBI_MODE_READ|DK_SDBI_MODE_WRITE)

Database access mode: read and write.

#define DK_SDBI_MODE_READ   1

Database access mode: read.

#define DK_SDBI_MODE_TRUNCATE   4

Database access mode: Truncate existing database.

#define DK_SDBI_MODE_WRITE   2

Database access mode: write.

#define DK_SDBI_TYPE_AUTO   0

Database type: Choose automatically.

#define DK_SDBI_TYPE_BDB   1

Database type: Berkeley DB.

#define DK_SDBI_TYPE_GDBM   3

Database type: GDBM.

#define DK_SDBI_TYPE_NDBM   2

Database type: NDBM.


Typedef Documentation

typedef int dk_sdbi_fct_t(\void *o, void *kp, size_t kl, void *vp, size_t vl)

Traversal function.

When traversing a database this function is invoked once for each key/value pair. The function must return the following values:

  • 0: No error, we can continue.
  • 1: Warning, we can continue.
  • -1: Error, we must stop database traversal.

Pointer o is an additional data object to be changes during traversal.
Buffer kp is kl bytes long, it receives the key.
Buffer vp is vl bytes long, it receives the value.


Function Documentation

void dksdbi_close ( dk_sdbi_t  d  ) 

Destroy database access structure obtained from dksdbi_open() and release memory.

Parameters:
d Pointer to database access structure.

int dksdbi_delete ( dk_sdbi_t  d,
char *  k,
size_t  l 
)

Delete entry from database.

Parameters:
d Pointer to database access structure.
k Pointer to key buffer.
l Number of bytes in k.
Returns:
Flag to indicate success.

int dksdbi_fetch ( dk_sdbi_t  d,
void *  kp,
size_t  kl,
void *  vp,
size_t *  vl 
)

Fetch key/value pair from database.

Parameters:
d Pointer to database access structure.
kp Pointer to key buffer.
kl Number of bytes in kp.
vp Pointer to buffer for result.
vl Pointer to size variable. In: size of buffer. Out: number of bytes used.
Returns:
Flag to indicate success.

dk_sdbi_t dksdbi_open ( char *  n,
int  t,
int  a,
int  m,
int  b 
)

Open a database and return database access structure.

The structure is created in dynamically allocated memory, call dksdbi_close() to destory the structure and release the memory after usage.

Parameters:
n Name of data base file.
t Database type (DK_SDBI_TYPE_BDB, DK_SDBI_TYPE_NDBM, DK_SDBI_TYPE_GDBM or DK_SDBI_TYPE_AUTO).
a Access mode (DK_SDBI_MODE_READ, DK_SDBI_MODE_WRITE or DK_SDBI_MODE_RDWR). Optionally you can or-combine the value with DK_SDBI_MODE_TRUNCATE to truncate existing database files.
m File mode. File permissions, i.e. 0600.
b Block size.

int dksdbi_remove_file ( char *  n,
int  t 
)

Remove a database file (or file pair).

Parameters:
n File name.
t Database type (DK_SDBI_TYPE_xxx).
Returns:
Flag to indicate success.

int dksdbi_store ( \dk_sdbi_t  d,
void *  kp,
size_t  kl,
void *  vp,
size_t  vl,
int  i 
)

Store key/value pair in database.

Parameters:
d Pointer to database access structure.
kp Pointer to key buffer.
kl Number of bytes in kp.
vp Pointer to value buffer.
vl Number of bytes in vp.
i Insertion mode. Use 0 to allow replacements of existing entries, DK_SDBI_INSMOD_NO_REPLACE to deny replacements.
Returns:
Flag to indicate success.

int dksdbi_string_delete ( dk_sdbi_t  d,
char *  k 
)

Delete string entry from database.

Parameters:
d Pointer to database access structure.
k Pointer to key string.
Returns:
Flag to indicate success.

int dksdbi_string_fetch ( dk_sdbi_t  d,
char *  k,
char *  v,
size_t  s 
)

Fetch string entry from database.

Parameters:
d Pointer to database access structure.
k Pointer to key string.
v Pointer to value buffer.
s Size of v in bytes.
Returns:
Flag to indicate success.

int dksdbi_string_store ( dk_sdbi_t  d,
char *  k,
char *  v,
int  i 
)

Store key/value pair of strings in database.

Parameters:
d Pointer to database access structure.
k Pointer to key string.
v Pointer to value string.
i Insertion mode. Use 0 to allow replacements of existing entries, DK_SDBI_INSMOD_NO_REPLACE to deny replacements.
Returns:
Flag to indicate success.

int dksdbi_sync ( dk_sdbi_t  d  ) 

Flush database to disk.

Some database libraries provide a sync-to-disk function for this purposes, for other database types this function does nothing.

Parameters:
d Pointer to database access structure.
Returns:
Flag to indicate success.

int dksdbi_traverse ( dk_sdbi_t  d,
void *  o,
dk_sdbi_fct_t f 
)

Traverse database.

This function walks through all database entries, the function f is called for each database entries.

Parameters:
d Pointer to database access structure.
o Pointer to object which is modified during database traversal.
f Traversal function.
Returns:
Flag to indicate success.


Generated on Mon Feb 16 17:12:04 2009 for dklibs by  doxygen 1.5.6