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

# NAME

cdbmaker_sa_start, cdbmaker_sa_add, cdbmaker_sa_finish - create a new cdb file

# SYNOPSIS

    #include <limb/cdbmake.h>

```pre hl
#define CDBMAKER_ZERO

int cdbmaker_start(cdbmaker *<em>mkr</em>, int <em>fd</em>)
int cdbmaker_add(cdbmaker *<em>mkr</em>, const char *<em>key</em>, u32 <em>klen</em>, const char *<em>data</em>, u32 <em>dlen</em>)
int cdbmaker_finish(cdbmaker *<em>mkr</em>)
```

# DESCRIPTION

The `cdbmaker_start`() prepares the opaque structure pointed to by `mkr` in
order to begin creation of a new cdb, which will be written into the file
represented by the file descriptor `fd`, which must be opened for writing.

The `cdbmaker_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_add`().

Finally, the `cdbmaker_finish`() function must be called after all elements
have been added via `cdbmaker_add`(), in order for the cdb to be finalized.

Note that the file descriptor given to `cdbmake_start`() will /not/ be closed.

# RETURN VALUE

The `cdbmaker_start`(), `cdbmaker_add`() and `cdbmaker_finish`() functions
return 1 on success. Otherwise, they return 0 and set `errno` to indicate the
error.

# ERRORS

The `cdbmaker_start`() and `cdbmaker_finish`() functions may fail for any of
the errors described for [lseek](3).

The `cdbmaker_add`() and `cdbmaker_finish`() functions may fail if :

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

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

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

The `cdbmaker_add`() and `cdbmaker_finish`() functions may also fail for any of
the errors described for [buffer_flush](3).