= MTBL_READER(3) =

== NAME ==

mtbl_reader - read an MTBL file

== SYNOPSIS ==

^#include <mtbl.h>^

Reader objects:

[verse]
^struct mtbl_reader *
mtbl_reader_init(const char *'fname', const struct mtbl_reader_options *'ropt');^

[verse]
^struct mtbl_reader *
mtbl_reader_init_fd(int 'fd', const struct mtbl_reader_options *'ropt');^

[verse]
^void
mtbl_reader_destroy(struct mtbl_reader **'r');^

[verse]
^const struct mtbl_source *
mtbl_reader_source(struct mtbl_reader *'r');^

[verse]
^const struct mtbl_metadata *
mtbl_reader_metadata(struct mtbl_reader *'r');^

Reader options:

[verse]
^struct mtbl_reader_options *
mtbl_reader_options_init(void);^

[verse]
^void
mtbl_reader_options_destroy(struct mtbl_reader_options **'ropt');^

[verse]
^void
mtbl_reader_options_set_verify_checksums(
        struct mtbl_reader_options *'ropt',
        bool 'verify_checksums');^

[verse]
^void
mtbl_reader_options_set_madvise_random(
        struct mtbl_reader_options *'ropt',
        bool 'madvise_random');^

== 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.

File-level metadata may be accessed using the ^mtbl_metadata^(3) interface,
using the object returned by ^mtbl_reader_metadata^().  Note that the
metadata object is valid only as long as the reader object exists.

=== Reader options ===

==== verify_checksums ====

Specifies whether or not the CRC32C checksum on the index block and each
data block should be verified or not. If _verify_checksums_ is enabled, a
checksum mismatch will cause a fatal runtime error. The default is to not verify
index or data block checksums.

==== madvise_random ====

Specifies whether the kernel should be advised if the data access patterns are
expected to be random or not. This may hurt some workloads but help others.
The default is to not set this advisory information.

This option can be explicitly overridden by setting the environment variable
^MTBL_READER_MADVISE_RANDOM^ to the string ^"0"^ (force disable) or ^"1"^
(force enable).

This option only has any effect on systems that have the ^posix_madvise^ or
^madvise^ system calls.

== RETURN VALUE ==

^mtbl_reader_init^() and ^mtbl_reader_init_fd^() return NULL on failure, and
non-NULL on success.
