MTBL_READER(3)MTBL_READER(3)NAME
mtbl_reader - read an MTBL file
SYNOPSIS
#include <mtbl.h>
Reader objects:
struct mtbl_reader *
mtbl_reader_init(const char *fname, const struct mtbl_reader_options *ropt);
struct mtbl_reader *
mtbl_reader_init_fd(int fd, const struct mtbl_reader_options *ropt);
void
mtbl_reader_destroy(struct mtbl_reader **r);
const struct mtbl_source *
mtbl_reader_source(struct mtbl_reader *r);
Reader options:
struct mtbl_reader_options *
mtbl_reader_options_init(void);
void
mtbl_reader_options_destroy(struct mtbl_reader_options **ropt);
void
mtbl_reader_options_set_verify_checksums(
struct mtbl_reader_options *ropt,
bool verify_checksums);
DESCRIPTION
MTBL files are accessed by creating an mtbl_reader object, calling mtbl_reader_source() to obtain an mtbl_source handle, and using the
mtbl_source(3) interface to read entries.
mtbl_reader objects may be created by calling mtbl_reader_init() with an fname argument specifying the filename to be opened, or
mtbl_reader_init_fd() may be called with an fd argument specifying an open, readable file descriptor. Since MTBL files are immutable, the
same MTBL file may be opened and read from concurrently by independent threads or processes.
If the ropt parameter to mtbl_reader_init() or mtbl_reader_init_fd() is non-NULL, the parameters specified in the mtbl_reader_options
object will be configured into the mtbl_reader object.
Reader options
verify_checksums
Specifies whether or not the CRC32C checksum on each data block should be verified or not. If verify_checksums is enabled, a checksum
mismatch will cause a runtime error. Note that the checksum on the index block is always verified, since the overhead of doing this
once when the reader object is instantiated is minimal. The default is to not verify data block checksums.
RETURN VALUE
mtbl_reader_init() and mtbl_reader_init_fd() return NULL on failure, and non-NULL on success.
05/29/2012 MTBL_READER(3)
Check Out this Related Man Page
MTBL_SORTER(3)MTBL_SORTER(3)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) 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) 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). 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.
05/29/2012 MTBL_SORTER(3)