'\" t
.\"     Title: mtbl_merger
.\"    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_MERGER" "3" "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_merger \- merge multiple MTBL data sources into a single output
.SH "SYNOPSIS"
.sp
\fB#include <mtbl\&.h>\fR
.sp
Merger objects:
.sp
.nf
\fBstruct mtbl_merger *
mtbl_merger_init(const struct mtbl_merger_options *\fR\fB\fImopt\fR\fR\fB);\fR
.fi
.sp
.nf
\fBvoid
mtbl_merger_destroy(struct mtbl_merger **\fR\fB\fIm\fR\fR\fB);\fR
.fi
.sp
.nf
\fBvoid
mtbl_merger_add_source(struct mtbl_merger *\fR\fB\fIm\fR\fR\fB, const struct mtbl_source *\fR\fB\fIs\fR\fR\fB);\fR
.fi
.sp
.nf
\fBconst struct mtbl_source *
mtbl_merger_source(struct mtbl_merger *\fR\fB\fIm\fR\fR\fB);\fR
.fi
.sp
Merger options:
.sp
.nf
\fBstruct mtbl_merger_options *
mtbl_merger_options_init(void);\fR
.fi
.sp
.nf
\fBvoid
mtbl_merger_options_destroy(struct mtbl_merger_options **\fR\fB\fImopt\fR\fR\fB);\fR
.fi
.sp
.nf
\fBvoid
mtbl_merger_options_set_merge_func(
        struct mtbl_merger_options *\fR\fB\fImopt\fR\fR\fB,
        mtbl_merge_func \fR\fB\fIfp\fR\fR\fB,
        void *\fR\fB\fIclos\fR\fR\fB);\fR
.fi
.sp
.nf
\fBtypedef void
(*mtbl_merge_func)(void *\fR\fB\fIclos\fR\fR\fB,
        const uint8_t *\fR\fB\fIkey\fR\fR\fB, size_t \fR\fB\fIlen_key\fR\fR\fB,
        const uint8_t *\fR\fB\fIval0\fR\fR\fB, size_t \fR\fB\fIlen_val0\fR\fR\fB,
        const uint8_t *\fR\fB\fIval1\fR\fR\fB, size_t \fR\fB\fIlen_val1\fR\fR\fB,
        uint8_t **\fR\fB\fImerged_val\fR\fR\fB, size_t *\fR\fB\fIlen_merged_val\fR\fR\fB);\fR
.fi
.SH "DESCRIPTION"
.sp
Multiple MTBL data sources may be merged together using the \fBmtbl_merger\fR 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 \fBmtbl_source\fR(3) and \fBmtbl_iter\fR(3) interfaces\&.
.sp
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\&.
.sp
\fBmtbl_merger\fR objects are created with the \fBmtbl_merger_init\fR() function, which requires a non\-NULL \fImopt\fR argument which has been configured with a merge function \fIfp\fR\&.
.sp
One or more \fBmtbl_reader\fR objects must be provided as input to the \fBmtbl_merger\fR object by calling \fBmtbl_merger_add_source\fR()\&. After the desired sources have been configured, \fBmtbl_merger_source\fR() should be called in order to consume the merged output via the \fBmtbl_source\fR(3) interface\&.
.SS "Merger options"
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBmerge_func\fR
.RS 4
.sp
This option specifies a merge function callback, consisting of a function pointer \fIfp\fR and a pointer to user data \fIclos\fR which will be passed as the first argument to \fIfp\fR\&. The merge function callback will be used during iteration over the \fBmtbl_merger\fR object to merge entries with duplicate keys in the input sources\&.
.sp
The remaining arguments to the merge function are:
.sp
\fIkey\fR \(em pointer to the key for which there exist duplicate values\&.
.sp
\fIlen_key\fR \(em length of the key\&.
.sp
\fIval0\fR \(em pointer to the first value\&.
.sp
\fIlen_val_0\fR \(em length of the first value\&.
.sp
\fIval1\fR \(em pointer to the second value\&.
.sp
\fIlen_val_1\fR \(em length of the second value\&.
.sp
\fImerged_val\fR \(em pointer to where the callee should place its merged value\&.
.sp
\fIlen_merged_val\fR \(em pointer to where the callee should place the length of its merged value\&.
.sp
\fImerged_val\fR must be allocated with the system allocator, and the \fBmtbl_merger\fR interface takes responsibility for free()ing the value once it is no longer needed\&.
.sp
The callee may provide an empty value as the merged value, in which case \fImerged_val\fR must still contain an allocated, non\-NULL value and \fIlen_merged_val\fR must contain the value 0\&.
.sp
The callee may indicate an error by returning NULL in the \fImerged_val\fR argument, which will abort iteration over the \fBmtbl_merger\fR object\&.
.RE
.SH "RETURN VALUE"
.sp
If the merge function callback is unable to provide a merged value (that is, it fails to return a non\-NULL value in its \fImerged_val\fR argument), the merge process will be aborted, and any iterators over the \fBmtbl_merger\fR object (via the \fBmtbl_source\fR(3) interface) will return \fBmtbl_res_failure\fR\&.