NAME

SYNOPSIS

typedef enum {
    DNSTABLE_ENTRY_TYPE_RRSET,
    DNSTABLE_ENTRY_TYPE_RRSET_NAME_FWD,
    DNSTABLE_ENTRY_TYPE_RDATA,
    DNSTABLE_ENTRY_TYPE_RDATA_NAME_REV,
    DNSTABLE_ENTRY_TYPE_TIME_RANGE,
    DNSTABLE_ENTRY_TYPE_VERSION
} dnstable_entry_type;

typedef enum {
    dnstable_output_format_json,
    dnstable_output_format_text
} dnstable_output_format_type;

typedef enum {
    dnstable_date_format_unix, /* timestamps in Unix seconds since the epoch */
    dnstable_date_format_rfc3339 /* timestamps in RFC3339 string form */
} dnstable_date_format_type;

struct dnstable_entry *
dnstable_entry_decode(
    const uint8_t *key, size_t len_key,
    const uint8_t *val, size_t len_val);

void
dnstable_entry_destroy(struct dnstable_entry **ent);

char *
dnstable_entry_to_text(struct dnstable_entry *ent);

char *
dnstable_entry_to_json(struct dnstable_entry *ent);

struct dnstable_formatter *
dnstable_formatter_init();

void
dnstable_formatter_destroy(struct dnstable_formatter **fp);

void
dnstable_formatter_set_output_format(
    struct dnstable_formatter *f,
    dnstable_output_format_type format);

void
dnstable_formatter_set_date_format(
    struct dnstable_formatter *f,
    dnstable_date_format_type format);

void
dnstable_formatter_set_rdata_array(
    struct dnstable_formatter *f,
    bool always_array);

void
dnstable_formatter_set_raw_rdata(
   struct dnstable_formatter *f,
   bool add_raw_rdata);

char *
dnstable_entry_format(
    const struct dnstable_formatter *f,
    const struct dnstable_entry *ent);

dnstable_entry_type
dnstable_entry_get_type(struct dnstable_entry *ent);

const char *
dnstable_entry_type_to_string(dnstable_entry_type type);

dnstable_res
dnstable_entry_type_from_string(dnstable_entry_type *type, const char *str);

void
dnstable_entry_set_iszone(struct dnstable_entry *ent, bool iszone);

/* valid for entry types:
 *      DNSTABLE_ENTRY_TYPE_RRSET
 *      DNSTABLE_ENTRY_TYPE_RRSET_NAME_FWD
 *      DNSTABLE_ENTRY_TYPE_RDATA
 */
dnstable_res
dnstable_entry_get_rrname(
    struct dnstable_entry *ent,
    const uint8_t **owner, size_t *len_owner);

/* valid for entry types:
 *      DNSTABLE_ENTRY_TYPE_RRSET
 *      DNSTABLE_ENTRY_TYPE_RDATA
 */
dnstable_res
dnstable_entry_get_rrtype(
    struct dnstable_entry *ent,
    uint16_t *rrtype);

/* valid for entry types:
 *      DNSTABLE_ENTRY_TYPE_RRSET
 */
dnstable_res
dnstable_entry_get_bailiwick(
    struct dnstable_entry *ent,
    const uint8_t **bailiwick, size_t *len_bailiwick);

/* valid for entry types:
 *      DNSTABLE_ENTRY_TYPE_RRSET
 *      DNSTABLE_ENTRY_TYPE_RDATA
 */
dnstable_res
dnstable_entry_get_num_rdata(
    struct dnstable_entry *ent,
    size_t *num_rdata);

/* valid for entry types:
 *      DNSTABLE_ENTRY_TYPE_RRSET
 *      DNSTABLE_ENTRY_TYPE_RDATA
 */
dnstable_res
dnstable_entry_get_rdata(
    struct dnstable_entry *ent, size_t idx,
    const uint8_t **rdata, size_t *len_rdata);

/* valid for entry types:
 *      DNSTABLE_ENTRY_TYPE_RDATA_NAME_REV
 */
dnstable_res
dnstable_entry_get_rdata_name(
    struct dnstable_entry *ent,
    const uint8_t **rdata_name, size_t *len_rdata_name);

/* valid for entry types:
 *      DNSTABLE_ENTRY_TYPE_RRSET
 *      DNSTABLE_ENTRY_TYPE_RDATA
 *      DNSTABLE_ENTRY_TYPE_TIME_RANGE
 */
dnstable_res
dnstable_entry_get_time_first(
    struct dnstable_entry *ent,
    uint64_t *time_first);

/* valid for entry types:
 *      DNSTABLE_ENTRY_TYPE_RRSET
 *      DNSTABLE_ENTRY_TYPE_RDATA
 *      DNSTABLE_ENTRY_TYPE_TIME_RANGE
 */
dnstable_res
dnstable_entry_get_time_last(
    struct dnstable_entry *ent,
    uint64_t *time_last);

/* valid for entry types:
 *      DNSTABLE_ENTRY_TYPE_RRSET
 *      DNSTABLE_ENTRY_TYPE_RDATA
 */
dnstable_res
dnstable_entry_get_count(
    struct dnstable_entry *ent,
    uint64_t *count);

/* valid for entry types:
 * DNSTABLE_ENTRY_TYPE_VERSION
 */
dnstable_res
dnstable_entry_get_version(
    struct dnstable_entry *ent,
    uint32_t *version);

/* valid for entry types:
 * DNSTABLE_ENTRY_TYPE_VERSION
 */
dnstable_res
dnstable_entry_get_version_type(
    struct dnstable_entry *ent,
    dnstable_entry_type *type);

DESCRIPTION

A dnstable_entry object has a particular type which can be retrieved with the dnstable_entry_get_type() function. Possible values are enumerated in dnstable_entry_type. For details about how each type is encoded, see dnstable-encoding(5).

For presentation or interchange purposes, the dnstable_entry_to_text(), dnstable_entry_to_json(), or more general dnstable_entry_format() functions can be used to generate the text or JSON-encoded form of a dnstable_entry object. These functions return a dynamically allocated string which must be free()'d by the caller.

To use the dnstable_entry_format() function, first create a formatter with dnstable_formatter_init(). The formatter must be destroyed, eventually, with dnstable_formatter_destroy().

Use dnstable_formatter_set_output_format() to select an available output format.

Use dnstable_formatter_set_date_format() to select a date format.

Use dnstable_formatter_set_rdata_array() to control if the JSON output format has rdata always as an array. If always_array is true, the rdata is always rendered as an array, even if there is only one rdata value. Default is false, in which case an rrset with only one rdata value will have the rdata rendered as a single string.

Use dnstable_formatter_set_raw_rdata() to control if the JSON output format will contain an additional raw_rdata field. If add_raw_rdata is true, the returned JSON objects will contain an additional raw_rdata field. Default is false.

The default formatter settings are: JSON format, always_array = False, UNIX date format — this is identical behavior to dnstable_entry_to_json() function.

The dnstable_entry_set_iszone() function sets or clears a flag if this entry is from a zone file. This controls how the timestamp fields are named in the formatted output.

The remaining dnstable_entry_get_*() accessor functions return particular fields of the dnstable_entry object, if present. dnstable_res_success will be returned if the entry has the requested field, and dnstable_res_failure if not. None of the accessor functions allocate memory. For the accessors which return pointers, these pointers are valid as long as the dnstable_entry object is valid. For field descriptions, see dnstable-encoding(5).

SEE ALSO