---
name: "mtbl_sorter"
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_sorter"
---

# mtbl\_sorter(3)

sort a sequence of unordered key-value pairs

## NAME

mtbl\_sorter - sort a sequence of unordered key-value pairs

## SYNOPSIS

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

Sorter objects:

```
struct mtbl_sorter *
mtbl_sorter_init(const struct mtbl_sorter_options *sopt);
```

```
void
mtbl_sorter_destroy(struct mtbl_sorter **s);
```

```
mtbl_res
mtbl_sorter_add(struct mtbl_sorter *s,
        const uint8_t *key, size_t len_key,
        const uint8_t *val, size_t len_val);
```

```
mtbl_res
mtbl_sorter_write(struct mtbl_sorter *s, struct mtbl_writer *w);
```

```
struct mtbl_iter *
mtbl_sorter_iter(struct mtbl_sorter *s);
```

Sorter options:

```
struct mtbl_sorter_options *
mtbl_sorter_options_init(void);
```

```
void
mtbl_sorter_options_destroy(struct mtbl_sorter_options **sopt);
```

```
void
mtbl_sorter_options_set_merge_func(
        struct mtbl_sorter_options *sopt,
        mtbl_merge_func fp,
        void *clos);
```

```
void
mtbl_sorter_options_set_temp_dir(
        struct mtbl_sorter_options *sopt,
        const char *temp_dir);
```

```
void
mtbl_sorter_options_set_max_memory(
        struct mtbl_sorter_options *sopt,
        size_t max_memory);
```

## DESCRIPTION

The **mtbl\_sorter** interface accepts a sequence of key-value pairs with keys in arbitrary order and provides these entries in sorted order. The sorted entries may be consumed via the **mtbl\_iter** interface using the **mtbl\_sorter\_iter**() function, or they may be dumped to an **mtbl\_writer** object using the **mtbl\_sorter\_write**() function. The **mtbl\_sorter** implementation buffers entries in memory up to a configurable limit before sorting them and writing them to disk in chunks. When the caller has finishing adding entries and requests the sorted output, entries from these sorted chunks are then read back and merged. (Thus, [**mtbl\_sorter**(3)](/mtbl_sorter/3.md) is an "external sorting" implementation.)

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 the same key is inserted more than twice. See [**mtbl\_merger**(3)](/mtbl_merger/3.md) for further details about the merge function.

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

**mtbl\_sorter\_add**() copies key-value pairs from the caller into the **mtbl\_sorter** object. Keys are specified as a pointer to a buffer, *key*, and the length of that buffer, *len\_key*. Values are specified as a pointer to a buffer, *val*, and the length of that buffer, *len\_val*.

Once the caller has finished adding entries to the **mtbl\_sorter** object, either **mtbl\_sorter\_write**() or **mtbl\_sorter\_iter**() should be called in order to consume the sorted output. It is a runtime error to call **mtbl\_sorter\_add**() on an **mtbl\_sorter** object after iteration has begun, and once the sorted output has been consumed, it is also a runtime error to call any other function but **mtbl\_sorter\_destroy**() on the depleted **mtbl\_sorter** object.

### Sorter options

**temp\_dir**

Specifies the temporary directory to use. Defaults to /var/tmp.

**max\_memory**

Specifies the maximum amount of memory to use for in-memory sorting, in bytes. Defaults to 1 Gigabyte. This specifies a limit on the total number of bytes allocated for key-value entries and does not include any allocation overhead.

**merge\_func**

See [**mtbl\_merger**(3)](/mtbl_merger/3.md). An **mtbl\_merger** object is used internally for the external sort.

## 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 sort process will be aborted, and **mtbl\_sorter\_write**() or **mtbl\_iter\_next**() will return **mtbl\_res\_failure**.

**mtbl\_sorter\_write**() returns **mtbl\_res\_success** if the sorted output was successfully written, and **mtbl\_res\_failure** otherwise.