---
name: "mtbl_iter"
section: "3"
platform: "linux"
package: "libmtbl-dev"
version: "1.6.1-1+b1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/mtbl_iter"
---

# mtbl\_iter(3)

iterate over a sequence of key-value pairs

## NAME

mtbl\_iter - iterate over a sequence of key-value pairs

## SYNOPSIS

**#include \<mtbl.h\>**

```
mtbl_res
mtbl_iter_next(struct mtbl_iter *it,
        const uint8_t **key, size_t *len_key,
        const uint8_t **val, size_t *len_val);
```

```
void
mtbl_iter_destroy(struct mtbl_iter **it);
```

```
mtbl_res
mtbl_iter_seek(struct mtbl_iter *it,
        const uint8_t *key, size_t len_key);
```

## DESCRIPTION

The **mtbl\_iter** interface is used to return a sequence of one or more key-value pairs. Once the caller obtains an **mtbl\_iter** object, **mtbl\_iter\_next**() should be repeatedly called on it until there are no more key-value entries to retrieve, at which point the iterator object must be freed by calling **mtbl\_iter\_destroy**(). **mtbl\_iter\_seek**() can be called on the iterator to seek to a different location in the index without having to destroy the iterator and create a new one.

## RETURN VALUE

**mtbl\_iter\_next**() returns **mtbl\_res\_success** if a key-value entry was successfully retrieved, in which case *key* and *val* will point to buffers of length *len\_key* and *len\_val* respectively. The value **mtbl\_res\_failure** is returned if there are no more entries to read, or if the *it* argument is NULL.

## SEE ALSO

[**mtbl\_source**(3)](/mtbl_source/3.md)