mtbl_reader(3) [debian man page]

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)

MTBL_FILESET(3) 														   MTBL_FILESET(3)

NAME

       mtbl_fileset - automatic multiple MTBL data file merger

SYNOPSIS

       #include <mtbl.h>

       Fileset objects:

       struct mtbl_fileset *
       mtbl_fileset_init(const char *fname, const struct mtbl_fileset_options *fopt);

       void
       mtbl_fileset_destroy(struct mtbl_fileset **f);

       void
       mtbl_fileset_reload(struct mtbl_fileset *f);

       const struct mtbl_source *
       mtbl_fileset_source(struct mtbl_fileset *f);

       Fileset options:

       struct mtbl_fileset_options *
       mtbl_fileset_options_init(void);

       void
       mtbl_fileset_options_destroy(struct mtbl_fileset_options **fopt);

       void
       mtbl_fileset_options_set_merge_func(
	       struct mtbl_fileset_options *fopt,
	       mtbl_merge_func fp,
	       void *clos);

       void
       mtbl_fileset_options_set_reload_frequency(
	       struct mtbl_fileset_options *fopt,
	       uint32_t reload_frequency);

DESCRIPTION

       The mtbl_fileset is a convenience interface for automatically maintaining a merged view of a set of MTBL data files. The merged entries may
       be consumed via the mtbl_source(3) and mtbl_iter(3) interfaces.

       mtbl_fileset objects are initialized from a "setfile", which specifies a list of filenames of MTBL data files, one per line. Internally, an
       mtbl_reader object is initialized from each filename and added to an mtbl_merger object. The setfile is watched for changes and the
       addition or removal of filenames from the setfile will result in the corresponding addition or removal of mtbl_reader objects.

       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_fileset objects are created with the mtbl_fileset_init() function, which requires the path to a "setfile", fname, and a non-NULL fopt
       argument which has been configured with a merge function fp. mtbl_fileset_source() should then be called in order to consume output via the
       mtbl_source(3) interface.

       Accesses via the mtbl_source(3) interface will implicitly check for updates to the setfile. However, it may be necessary to explicitly call
       the mtbl_fileset_reload() function in order to check for updates, especially if files are being removed from the setfile.

   Fileset options
       merge_func
	   See mtbl_merger(3). An mtbl_merger object is used internally for the external sort.

       reload_interval
	   Specifies the interval between checks for updates to the setfile, in seconds. Defaults to 60 seconds.

								    05/29/2012							   MTBL_FILESET(3)