% limb manual
% cdb.h(0)
% limb 0.1.0
% 2023-07-24

# NAME

cdb.h - accessing constant databases


# SYNOPSIS

    #include <limb/cdb.h>


# DESCRIPTION

The header defines the needed functions to access constant databases, known as
.cdb files.

<inc skalibs.md>

## Structures

The following structures are defined :

: *struct cdb_data_s*
:: A structure to hold information about an element in a cdb, defined as such :

    struct cdb_data_s {
        const char *s;
        u32 len;
    }

:: Member `s` points to the data, of length `len` bytes. (cdb database must be
:: under 4 GiB, therefore any length can fit within a 32bit value.)

## Types

The following types are defined :

: *cdb*
:: An opaque structure representing a cdb.

: *cdb_data*
:: A *struct cdb_data_s*, usually given to a cdb-reading function for it to be
:: filled with information about the wanted element. Pointers set in such a
:: *cdb_data* are read-only (hence the `const`) and remain valid until the *cdb*
:: is closed.

: *cdb_find_state*
:: An opaque structure used when searching inside a cdb, notably to find all
:: elements stored with the same key.

: *cdb_traverse*
:: An opaque structure used when iterating over a cdb.

## Macros

The following macros are defined :

: *CDB_ZERO*
:: Value to initialize a stack-allocated *cdb*.

: *CDB_FIND_STATE_ZERO*
:: Value to initialize a stack-allocated *cdb_find_state*.

: *CDB_TRAVERSE_ZERO*
:: Value to initialize a stack-allocated *cdb_traverse*.

## Objects

The following objects are defined :

: *cdb_zero*
:: An empty *cdb*, which can be used for (re-)initialization.

## Functions

The following functions are defined :

: [cdb_find_start](3)
:: Initialize a *cdb_find_state*.

: [cdb_find_next](3)
:: Similar to [cdb_find](3) except that it takes a *cdb_find_state* argument,
:: allowing to find all elements with the same key.

: [cdb_find](3)
:: Find the first element for the given key in a *cdb*.

: [cdb_free](3)
:: Free memory associated with a *cdb* from a file (descriptor).

: [cdb_init](3)
:: Initialize a cdb from a file.

: [cdb_initat](3)
:: Similar to [cdb_init](3) except for relative path, relative to the given file
:: descriptor.

: [cdb_init_fromfd](3)
:: Similar to [cdb_init](3) but taking a file descriptor instead of a file name.

: [cdb_init_frommem](3)
:: Similar to [cdb_init](3) but taking a pointer to a memory area, which must
:: contain a valid CDB file.

: [cdb_traverse_init](3)
:: Initialize a *cdb_traverse*.

: [cdb_traverse_next](3)
:: Find the next element when iterating over a *cdb*.