The `s6dns_hosts` library interface

The following functions are declared in the s6-dns/hosts.h header, and implemented in the libs6dns.a or libs6dns.so library.

General information

s6dns_hosts provides functions and macros - mostly macros - to perform name-to-IP or IP-to-name resolution according to the local /etc/hosts file.

Most of the functions declared here are variations of another, more generic function. Typically, a foobar_r function is the generic one, and will take additional arguments such as: a pointer to a local hosts database (compiled to an efficient format), and/or a list and number of rules for qualification. The corresponding foobar function is the same, except that it uses global variables to fill these additional arguments: for instance, the hosts database made from /etc/hosts, or the qualification rules computed from /etc/resolv.conf. We document the simpler functions — even though they're macros, we pretend they're functions; please refer to the s6-dns/hosts.h file for the exact prototypes or if you want to use the generic functions.

s6dns_engine_here: a global s6dns_engine_t storing the current query, for sequential queries.
s6dns_debughook_zero: a global s6dns_debughook_t meaning no debugging is needed.
s6dns_rci_here: a global s6dns_rci_t containing the current resolv.conf information.

Global variables

cdb s6dns_hosts_here
s6dns_hosts_here is the global cdb database containing the compiled data from /etc/hosts. You normally do not need to use it manually because it is implicitly supplied to functions when you use the macros without a _r suffix.

Functions

Preparation

int s6dns_hosts_compile (int fdr, int fdw)
Compiles the text file data from file descriptor fdr, which should be in /etc/hosts format, into a cdb file written to file descriptor fdw. fdr must be open for reading, and fdw must be open for writing and seekable. The function returns 1 on success and 0 (and sets errno) on failure.

You normally don't need to use this function yourself, because it's implicitly used by the following one.

int s6dns_hosts_init (void)
Initializes the database from the /etc/hosts file. If there's a pre-compiled /etc/hosts.cdb file that is more recent than /etc/hosts, then it is used; else, the /etc/hosts file is compiled into a temporary file under /tmp, which is used and immediately unlinked. The function returns 1 on success and 0 (and sets errno) on failure.

int s6dns_hosts_init_r (cdb *c, char const *txtfile, char const *cdbfile, char const *prefix)
The generic version of the above function. Initializes the database in *c from the compiled file cdbfile if it exists and is more recent than txtfile, else compiles txtfile into a temporary file with a path starting with prefix, makes it accessible in *c and immediately unlinks it.

void s6dns_hosts_free (void)
Frees the compiled hosts database. Only use this if you're certain you'll have no more use for it.

void s6dns_hosts_free_r (cdb *c)
The generic version of the above function.

IP to name resolution