NAME¶
mtbl_writer - create an MTBL file
SYNOPSIS¶
#include <mtbl.h>
Writer objects:
struct mtbl_writer *
mtbl_writer_init(const char *fname, const struct mtbl_writer_options *wopt);
struct mtbl_writer *
mtbl_writer_init_fd(int fd, const struct mtbl_writer_options *wopt);
void
mtbl_writer_destroy(struct mtbl_writer **w);
mtbl_res
mtbl_writer_add(struct mtbl_writer *w,
const uint8_t *key, size_t len_key,
const uint8_t *val, size_t len_val);
Writer options:
struct mtbl_writer_options *
mtbl_writer_options_init(void);
void
mtbl_writer_options_destroy(struct mtbl_writer_options **wopt);
void
mtbl_writer_options_set_compression(
struct mtbl_writer_options *wopt,
mtbl_compression_type compression_type);
void
mtbl_writer_options_set_block_size(
struct mtbl_writer_options *wopt,
size_t block_size);
void
mtbl_writer_options_set_block_restart_interval(
struct mtbl_writer_options *wopt,
size_t block_restart_interval);
DESCRIPTION¶
MTBL files are written to disk by creating an
mtbl_writer object, calling
mtbl_writer_add() for each key-value entry, and then calling
mtbl_writer_destroy().
mtbl_writer_add() copies key-value pairs from the caller into the
mtbl_writer 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.
Keys must be in sorted, lexicographical byte order. The same key may not be
added to an
mtbl_writer more than once. If the input entries are not
sorted or may contain duplicate keys, then the
mtbl_sorter(3) interface
should be used instead.
mtbl_writer objects may be created by calling
mtbl_writer_init()
with an
fname argument specifying a filename to be created. The
filename must not already exist on the filesystem. Or,
mtbl_writer_init_fd() may be called with an
fd argument
specifying an open, writable file descriptor. No data may have been written to
the file descriptor.
If the
wopt parameter to
mtbl_writer_init() or
mtbl_writer_init_fd() is non-NULL, the parameters specified in the
mtbl_writer_options object will be configured into the
mtbl_writer object.
Writer options¶
compression
Specifies the compression algorithm to use on data blocks. Possible values are
MTBL_COMPRESSION_NONE,
MTBL_COMPRESSION_SNAPPY, or
MTBL_COMPRESSION_ZLIB (the default).
block_size
The maximum size of uncompressed data blocks, specified in bytes. The default is
8 kilobytes.
block_restart_interval
How frequently to restart intra-block key prefix compression. The default is
every 16 keys.
RETURN VALUE¶
mtbl_writer_init() and
mtbl_writer_init_fd() return NULL on
failure, and non-NULL on success.
mtbl_writer_add() returns
mtbl_res_success if the key-value entry
was successfully copied into the
mtbl_writer object, and
mtbl_res_failure if not, for instance if there has been a key-ordering
violation.