---
name: "mtbl_merger"
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_merger"
---

# mtbl\_merger(3)

merge multiple MTBL data sources into a single output

## NAME

mtbl\_merger - merge multiple MTBL data sources into a single output

## SYNOPSIS

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

Merger objects:

```
struct mtbl_merger *
mtbl_merger_init(const struct mtbl_merger_options *mopt);
```

```
void
mtbl_merger_destroy(struct mtbl_merger **m);
```

```
void
mtbl_merger_add_source(struct mtbl_merger *m, const struct mtbl_source *s);
```

```
const struct mtbl_source *
mtbl_merger_source(struct mtbl_merger *m);
```

Merger options:

```
struct mtbl_merger_options *
mtbl_merger_options_init(void);
```

```
void
mtbl_merger_options_destroy(struct mtbl_merger_options **mopt);
```

```
void
mtbl_merger_options_set_merge_func(
        struct mtbl_merger_options *mopt,
        mtbl_merge_func fp,
        void *clos);
```

```
void
mtbl_merger_options_set_dupsort_func(
        struct mtbl_merger_options *mopt,
        mtbl_dupsort_func fp,
        void *clos);
```

```
typedef void
(*mtbl_merge_func)(void *clos,
        const uint8_t *key, size_t len_key,
        const uint8_t *val0, size_t len_val0,
        const uint8_t *val1, size_t len_val1,
        uint8_t **merged_val, size_t *len_merged_val);
```

```
typedef int
(*mtbl_dupsort_func)(void *clos,
        const uint8_t *key, size_t len_key,
        const uint8_t *val0, size_t len_val0,
        const uint8_t *val1, size_t 'len_val1);
```

## DESCRIPTION

Multiple MTBL data sources may be merged together using the **mtbl\_merger** interface, which reads key-value entries from one or more sources and provides these entries in sorted order. The sorted entries may be consumed via the [**mtbl\_source**(3)](/mtbl_source/3.md) and [**mtbl\_iter**(3)](/mtbl_iter/3.md) interfaces.

Because the MTBL format does not allow duplicate keys, the caller must provide a function which will accept a key and two conflicting values for that key and return a replacement value. This function may be called multiple times for the same key if more than two sources are being merged.

**mtbl\_merger** objects are created with the **mtbl\_merger\_init**() function, which requires a non-NULL *mopt* argument which has been configured with a merge function *fp*.

One or more **mtbl\_reader** objects must be provided as input to the **mtbl\_merger** object by calling **mtbl\_merger\_add\_source**(). After the desired sources have been configured, **mtbl\_merger\_source**() should be called in order to consume the merged output via the [**mtbl\_source**(3)](/mtbl_source/3.md) interface.

### Merger options

**merge\_func**

This option specifies a merge function callback, consisting of a function pointer *fp* and a pointer to user data *clos* which will be passed as the first argument to *fp*. The merge function callback will be used during iteration over the **mtbl\_merger** object to merge entries with duplicate keys in the input sources.

The remaining arguments to the merge function are:

*key* — pointer to the key for which there exist duplicate values.

*len\_key* — length of the key.

*val0* — pointer to the first value.

*len\_val\_0* — length of the first value.

*val1* — pointer to the second value.

*len\_val\_1* — length of the second value.

*merged\_val* — pointer to where the callee should place its merged value.

*len\_merged\_val* — pointer to where the callee should place the length of its merged value.

*merged\_val* must be allocated with the system allocator, and the **mtbl\_merger** interface takes responsibility for free()ing the value once it is no longer needed.

The callee may provide an empty value as the merged value, in which case *merged\_val* must still contain an allocated, non-NULL value and *len\_merged\_val* must contain the value 0.

The callee may indicate an error by returning NULL in the *merged\_val* argument, which will abort iteration over the **mtbl\_merger** object.

**dupsort\_func**

This option provides a comparison function for multiple data with the same key. It will be used to sort the data during the merge process. If the **merge\_func** option is set to or left NULL, the **dupsort\_func** will order the results returned by the merge process for data with identical keys.

## RETURN VALUE

If the merge function callback is unable to provide a merged value (that is, it fails to return a non-NULL value in its *merged\_val* argument), the merge process will be aborted, and any iterators over the **mtbl\_merger** object (via the [**mtbl\_source**(3)](/mtbl_source/3.md) interface) will return **mtbl\_res\_failure**.