s6-dns: the s6dns_rci library interface
Keywords: s6-dns dns s6dns_rci resolv.conf library libs6dns

libs6dns
s6-dns
Software
skarnet.org

# The `s6dns_rci` library interface

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

## General information

`s6dns_rci` provides functions to get information from the `/etc/resolv.conf` file.

## Data structures

A `s6dns_rci_t` is a structure storing information provided by the `/etc/resolv.conf` file, i.e.

- The list of "nameserver" addresses, i.e. IP addresses of DNS caches contacted by clients for recursive queries
- The list of qualification rules provided by "domain" or "search" lines

Nameserver addresses are stored in a s6dns_ip46list_t. Qualification rules are stored in a stralloc with an additional integer storing the number of rules.

Most programs won't need more than one `s6dns_rci_t`, so the library provides the global variable `s6dns_rci_here`, used by default in simple resolution macros.

## Functions

`int s6dns_rci_init (s6dns_rci_t *rci, char const *file)`
Extracts information from file, which must be in `/etc/resolv.conf` format, and stores it into *rci. rci must be previously initialized to the `S6DNS_RCI_ZERO` constant. The function returns 1 if it succeeds, or 0 (and sets errno) if it fails.

If the DNSCACHEIP environment variable is set, and contains a list of IP addresses separated by commas, semicolons, spaces, tabs, newlines or carriage returns, then this list overrides any nameserver information from file. If the variable is empty, file will be used as the source of the information.

If the DNSQUALIFY environment variable is set, a list of domain suffixes, separated by spaces, tabs, newlines or carriage returns, is read from it, and overrides any qualification information from file. If the variable is empty, it amounts to one rule saying "no qualification".

`s6dns_init()` is an alias to `s6dns_rci_init(&s6dns_rci_here, "/etc/resolv.conf")`.

`void s6dns_rci_free (s6dns_rci_t *rci)`
Frees the memory used by *rci. rci is then suitable to be reused in a `s6dns_rci_init` call.

`s6dns_finish()` calls `s6dns_rci_free(&s6dns_rci_here)`.

`unsigned int s6dns_qualify (s6dns_domain_t *list, s6dns_domain_t const *d)`
Qualifies domain *d into the list of domains pointed to by list according to the rules stored in `s6dns_rci_here`. Returns the number of written domains (0 if it fails); this number cannot exceed `s6dns_rci_here.rulesnum`.