NAME

cdbmaker_sa_init, cdbmaker_sa_start, cdbmaker_sa_add, cdbmaker_sa_finish, cdbmaker_sa_data, cdbmaker_sa_dlen, cdbmaker_sa_free - create a cdb in memory

SYNOPSIS

#include <limb/cdbmake.h>

#define CDBMAKER_SA_ZERO

void cdbmaker_sa_init(cdbmaker_sa *mkr)
int cdbmaker_sa_start(cdbmaker_sa *mkr)
int cdbmaker_sa_add(cdbmaker_sa *mkr, const char *key, u32 klen, const char *data, u32 dlen)
int cdbmaker_sa_finish(cdbmaker_sa *mkr)
const char *cdbmaker_sa_data(cdbmaker_sa *mkr)
size_t cdbmaker_sa_dlen(cdbmaker_sa *mkr)
void cdbmaker_sa_free(cdbmaker_sa *mkr)

DESCRIPTION

Before using a cdbmaker_sa it should first be properly initialized. This can be done upon declaration using the CDBMAKER_SA_ZERO macro. If not, the cdbmaker_sa_init() function should then be called first.

The cdbmaker_sa_start(), cdbmaker_sa_add() and cdbmaker_sa_finish() functions are similar to cdbmake_start(3), cdbmake_add(3) and cdbmake_finish(3) respectively, only the resulting cdb will not be written to a file but instead be available in memory.

The cdbmaker_sa_start() prepares the opaque structure pointed to by mkr in order to begin creation of a new cdb. Said structure must have previously been initialized as mentioned before.

Note that, after a successful call to cdbmaker_sa_finish() it is possible to re-use the same cdbmaker_sa structure, to create another cdb, by calling cdbmaker_sa_start() again.

The cdbmaker_sa_add() function is to be called for each element to be added to the cdb, specifying the key pointed to by key of length klen bytes, and the data pointed to by data of length dlen bytes. The actual content of both key and data will be of course be copied into the cdb.

Elements will be added into the cdb in the order of the calls made to cdbmaker_sa_add().

Finally, the cdbmaker_sa_finish() function must be called after all elements have been added via cdbmaker_sa_add(), in order for the cdb to be actually created.

Then, the cdbmaker_sa_data() function will return a pointer to the in-memory cdb data, i.e. the content of a cdb file, whose length will be returned by the cdbmaker_sa_dlen() function.

The returned pointer can be used until the cdbmaker_sa_free() function is called, which will free memory associated with the opaque structure pointed to by mkr, starting with the generated cdb data. It is not needed to use it before calling cdbmaker_sa_start() again in order to generate a new cdb, thusly re-using the already allocated memory area.

RETURN VALUE

The cdbmaker_sa_start(), cdbmaker_sa_add() and cdbmaker_sa_finish() functions return 1 on success. Otherwise, they return 0 and set errno to indicate the error.

The cdbmaker_sa_data() function returns a pointer to the generated cdb data.

The cdbmaker_sa_dlen() function returns the length (in bytes) of the generated cdb data, of which a pointer to can be obtained via cdbmaker_sa_data().

It is invalid to call either cdbmaker_sa_data() or cdbmaker_sa_dlen() before a successful call to cdbmaker_sa_finish() was made.

ERRORS

The cdbmaker_sa_start(), cdbmaker_sa_add() and cdbmaker_sa_finish() may fail if :

The cdbmaker_sa_start() function may also fail if :

The cdbmaker_sa_add() function may also fail if :