% limb manual
% cdbmaker_sa_start(3)
% limb 0.1.0
% 2023-07-24

# 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>

```pre hl
#define CDBMAKER_SA_ZERO

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

# 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 :

: *ENOMEM*
:: Not enough memory to create to cdb.

The `cdbmaker_sa_start`() function may also fail if :

: *EINVAL*
:: The *cdbmaker_sa* structure is not in a valid/properly initialized state.

The `cdbmaker_sa_add`() function may also fail if :

: *EOVERFLOW*
:: The resulting cdb would overflow, i.e. go over its 4 GiB limit.