API Documentation

Where possible, the API functions included in libtdbrepl aim to emulate those
in TDB to facilitate drop-in-replacement with pre-existing code.

The following API functions are available:

$Id: API,v 1.1.1.1 2002/04/01 07:44:27 liam Exp $

FUNCTION
	TDB_REPL_CONTEXT *tdb_repl_open(char *name, int hash_size, int tdb_flags,
	                                int open_flags, mode_t mode);

DESCRIPTION
	Open the database, creating it if necessary. The  hash  size
	is  advisory, use zero for a default value. tdb_flags can be any 
	of the values defined by TDB. Note: Usage of inappropriate flags 
	such as TDB_INTERNAL may result in undefined behavior.

	The open_flags and mode are passed straight to the open call
	on the database file. A flags value of O_WRONLY is invalid.

	Note: tdb_repl_init() must be called prior to calling tdb_repl_open().

RETURNS
	A pointer to a dynamically allocated TDB_REPL_CONTEXT data structure
	or NULL if an error has occured. The structure will be freed by 
	calling tdb_repl_close().

FUNCTION	
       int tdb_repl_close(TDB_REPL_CONTEXT *tdb_context);

DESCRIPTIONS
	Closes the database and frees the tdb_context structure.

RETURNS
	A value of 0 if the close succeeded or any other value for failure.

FUNCTION
	TDB_DATA tdb_repl_fetch(TDB_REPL_CONTEXT *tdb_context, TDB_DATA key);

DESCRIPTION
	Fetches (locally) data with key 'key' from the database referenced 
	by 'tdb_context'.

RETURNS
	If the call succeeds, then a TDB_DATA structure is  returned
	with  the  dptr  structure filled in. If the call fails then
	dptr will be set to NULL.

	Note: The caller is responsible for freeing the data pointed
	to by dptr.

FUNCTION
	int tdb_repl_delete(TDB_REPL_CONTEXT *tdb_context, TDB_DATA key);

DESCRIPTION
     Delete the record from the tdb database whose key matches 'key'.

RETURNS
     A return value of  0  indicates  success  and  -1  indicates
     failure.

FUNCTION
	int tdb_repl_store(TDB_REPL_CONTEXT *tdb_context, TDB_DATA key,
	                   TDB_DATA dbuf, int flag);
DESCRIPTION
	Store a lump of data pointed to by record in the  tdb  data-
	base  under the index pointed to by key. The TDB_DATA struc-
	ture used by both key and record is defined as:

	typedef struct {
		char *dptr;
		size_t dsize;
	} TDB_DATA;

	The flag determines the way that tdb_repl_store behaves in the
	same way as it does with tdb_store. It can one any of the 
	following values: TDB_REPLACE, TDB_INSERT, TBD_MODIFY.

RETURNS
	A return value of  0  indicates  success  and  -1  indicates
	failure.

FUNCTION
	int tdb_repl_init(const char *);

DESCRIPTION
	This function performs internal tdbrepl intialisation and must be 
	called prior to performing ANY tdbrepl operations.

RETURNS
	A return value of  0  indicates  success  and  -1  indicates
	failure. If failure occurs, no tdbrepl functions are allowed
	to be used.

FUNCTION
	int tdb_repl_shutdown(void);

DESCRIPTION
	This function performs internal cleanup operations and must be
	called on program termination.

RETURNS
	A return value of  0  indicates  success  and  -1  indicates
	failure. 

FUNCTION
	int tdb_repl_flush(TDB_REPL_CONTEXT *tdb_context);

DESCRIPTION
	This function forces a flush of the failed transaction log for the 
	database specified by tdb_context.

RETURNS
	A return value of  0  indicates  success  and  -1  indicates
	failure. 

FUNCTION
	TDB_DATA tdb_repl_firstkey(TDB_REPL_CONTEXT *tdb_context);
	TDB_DATA tdb_repl_nextkey(TDB_REPL_CONTEXT *tdb_context, TDB_DATA key);

DESCRIPTION
	The tdb_repl_firstkey function fetches the key of the first entry 
	in the database. The tdb_repl_nextkey function fetches the key of 
	the entry immediately after prev_key in the database.

RETURNS
	If the call succeeds, then a TDB_DATA structure is  returned
	with  the dptr structure filled in. If the call fails or you
	have reached the end of the database then dptr will  be  set
	to NULL.

	Note: The caller is responsible for freeing the data pointed
	to by dptr.

FUNCTION
	int tdb_repl_exists(TDB_REPL_CONTEXT *tdb_context, TDB_DATA key);

DESCRIPTION

	Test to see if a key exists in the database referenced by 
	tdb_context.

RETURNS
	If the key is found, 1 is returned; otherwise 0 is returned.

FUNCTION
	int tdb_repl_traverse(TDB_REPL_CONTEXT *tdb_context,
	                      int (*fn)(TDB_CONTEXT *tdb, TDB_DATA key,
	                      TDB_DATA dbuf, void* state), void* state);

DESCRIPTION
	The tdb_repl_traverse function is the only sure way to traverse the
	specified database as this function has intimate knowledge of the 
	internals of the database. It is a nasty wrapper to the tdb_traverse
	function.

	If fn is supplied it will be called with the state parameter
	for each element in the database, as the forth argument. The
	First argument is the database tdb the second is the key and
	the  third  is  the data. If this function call returns anything but 
	0, the traversal will stop. Unlike in  tdb_repl_fetch()
	the programmer is  not required to free either the pointer from 
	either the key or data parameters that are passed into
	the function. The fn function should have the prototype:

		int (*tdb_traverse_func)(TDB_CONTEXT *, TDB_DATA, TDB_DATA, void *);

	Calling tdb_repl_traverse with a NULL fn parameter  is  the
	appropriate way to count the number of elements in the data-
	base.

RETURNS
	The return value is the number of elements traversed  or  -1
	if there was an error.

FUNCTION
	char *tdb_repl_strerror(int status)

DESCRIPTION
	The tdb_repl_strerror function maps the error number in status to
	an  error  message  string,  and  returns  a pointer to that
	string. The status variable should be the return value supplied
	by any of the above calls.

	Note: The tdb_repl_errno used internally by this function is NOT 
	thread safe and as such can be over-written by concurrently
	executing functions in  erroneous states.

RETURNS
	A dynamically allocated string that must be freed by the caller.