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.

                                                   01/31/2014                                     MTBL_READER(3)