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

# NAME

cdb_find, cdb_find_start, cdb_find_next - finding element in a cdb

# SYNOPSIS

    #include <limb/cdb.h>

```pre hl
int cdb_find(const cdb *<em>c</em>, cdb_data *<em>data</em>, const char *<em>key</em>, u32 <em>klen</em>);

void cdb_find_start(cdb_find_state *<em>find</em>)
int cdb_find_next(const cdb *<em>c</em>, cdb_data *<em>data</em>, const char *<em>key</em>, u32 <em>klen</em>, cdb_find_state *<em>find</em>)
```

# DESCRIPTION

The `cdb_find`() function looks up the key pointed by `key` of length `klen` in
the *cdb* pointed by `c`. If found, it will set the members `s` and `len` of the
*cdb_data* pointed by `data` to represent the data associated with the first
element found by that key.

Only the first element with that key can be found using this function.

The `cdb_find_start`() macro initialize the state pointed by `find` so that the
next invocation of `cdb_find_next`() using that state will find the first
element associated with the given key.

The `cdb_find_next`() function is similar to `cdb_find`() when the state pointed
by `find` has been initialized by `cdb_find_start`().
However, said state will be updated so that the next call to `cdb_find_next`()
using the same arguments for `key`, `klen` and `state` return the next element
associated with the key, and so on for all elements for said key.

Note that it is invalid and undefined what happens if calling `cdb_find_next`()
with an uninitialized state, or one initialized for a different key.

# RETURN VALUE

The `cdb_find`() and `cdb_find_next`() functions return -1 when the *cdb* pointed
by `c` is invalid; They return 1 on success, i.e. an element was found and
information about its associated data was set inside the *cdb_data* pointed by
`data`.

Otherwise, i.e. no element with that key was found, or - in the case of
`cdb_find_next`() - there are no more elements with that key, they return 0.