'\" t
.\"     Title: mtbl
.\"    Author: [FIXME: author] [see http://docbook.sf.net/el/author]
.\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
.\"      Date: 01/31/2014
.\"    Manual: \ \&
.\"    Source: \ \&
.\"  Language: English
.\"
.TH "MTBL" "7" "01/31/2014" "\ \&" "\ \&"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
mtbl \- immutable sorted string library
.SH "SYNOPSIS"
.sp
\fB#include <mtbl\&.h>\fR
.sp
\fBgcc [\fR\fB\fIflags\fR\fR\fB] \fR\fB\fIfiles\fR\fR\fB \-lmtbl [\fR\fB\fIlibraries\fR\fR\fB]\fR
.SH "DESCRIPTION"
.sp
The mtbl library provides interfaces for creating, searching, and merging Sorted String Table (SSTable) files in the \fIMTBL\fR format, which provide an immutable mapping of keys to values\&. Sorted String Tables are compact and provide fast random access to keys and key ranges\&. Keys and values are arbitrary byte arrays, and MTBL SSTables may not contain duplicate keys\&.
.sp
The six main interfaces provided by the mtbl library are:
.PP
\fBmtbl_iter\fR(3)
.RS 4
Iterator objects provide a consistent interface for iterating over the key\-value entries returned by other interfaces\&.
.RE
.PP
\fBmtbl_source\fR(3)
.RS 4
Source objects provide functions for obtaining iterators from an underlying data source\&. The
\fBmtbl_reader\fR
and
\fBmtbl_merger\fR
interfaces provide functions for obtaining references to a source object\&. The source methods return an
\fBmtbl_iter\fR
object\&.
.RE
.PP
\fBmtbl_reader\fR(3)
.RS 4
Reader objects provide read\-only access to
\fIMTBL\fR
files\&.
.RE
.PP
\fBmtbl_writer\fR(3)
.RS 4
Writer objects initialize a new
\fIMTBL\fR
file from a sequence of key\-value entries provided by the caller\&. Keys must be in sorted order based on lexicographical byte value, and keys may not be duplicated\&.
.RE
.PP
\fBmtbl_merger\fR(3)
.RS 4
Merger objects receive multiple sequences of key\-value entries from one or more
\fBmtbl_source\fR
objects and combine them into a single, sorted sequence\&. The combined, merged output sequence is provided via the
\fBmtbl_source\fR
interface\&.
.RE
.PP
\fBmtbl_sorter\fR(3)
.RS 4
Sorter objects receive a sequence of key\-value entries provided by the caller and return them in sorted order\&. The caller must provide a callback function to merge values in the case of entries with duplicate keys\&. The sorted output sequence may be retrieved via the
\fBmtbl_iter\fR
interface or be dumped to an
\fBmtbl_writer\fR
object\&.
.RE
.PP
\fBmtbl_fileset\fR(3)
.RS 4
Fileset objects automatically maintain an
\fBmtbl_source\fR
built on top of the
\fBmtbl_merger\fR
and
\fBmtbl_reader\fR
interfaces\&. The set of underlying
\fBmtbl_reader\fR
objects is kept synchronized with a "setfile" on disk listing
\fIMTBL\fR
files\&.
.RE
.sp
Additionally, several utility interfaces are provided:
.PP
\fBmtbl_crc32c\fR(3)
.RS 4
Calculates the CRC32C checksum of a byte array\&.
.RE
.PP
\fBmtbl_fixed\fR(3)
.RS 4
Functions for fixed\-width encoding and decoding of 32 and 64 bit integers\&.
.RE
.PP
\fBmtbl_varint\fR(3)
.RS 4
Functions for varint encoding and decoding of 32 and 64 bit integers\&.
.RE