s6-dns: the s6dns library interface
Keywords: s6-dns dns s6dns library libs6dns

s6-dns
Software
skarnet.org

# The `s6dns` library interface

## General information

`libs6dns` is a DNS client library, designed for clarity and simplicity - which translates into smallness of the code.

A major focus of `libs6dns` is to avoid unnecessary use of heap memory. Memory is only allocated in the heap to store queries and response packets during a DNS resolution process, and to store the final answers into a user-provided stralloc; all the other operations use stack memory, and perform as few copies as possible.

## Compiling

- Make sure the s6-dns headers, as well as the skalibs headers, are visible in your header search path.
- Use `#include <s6-dns/s6dns.h>`

## Linking

- Make sure the s6-dns libraries, as well as the skalibs libraries, are visible in your library search path.
- Link against `-ls6dns`, `-lskarnet`, ``cat $SYSDEPS/socket.lib`` and ``cat $SYSDEPS/sysclock.lib``, $SYSDEPS being your skalibs sysdeps directory.

## Programming

The `s6-dns/s6dns.h` header is actually a concatenation of other headers: the libs6dns is separated into several modules, each of them with its own header.

- The `s6-dns/s6dns-constants.h` header provides constants used in other parts of the library.
- The s6-dns/s6dns-ip46.h header provides an abstraction for IPv4 and IPv6 transports.
- The s6-dns/s6dns-domain.h header provides basic string manipulation primitives for domain names.
- The s6-dns/s6dns-message.h header provides function to parse a message following the DNS protocol.
- The s6-dns/s6dns-engine.h header provides the low-level asynchronous networking functions.
- The s6-dns/s6dns-rci.h header provides an interface to `resolv.conf` reading.
- The s6-dns/s6dns-resolve.h header provides the user-level synchronous resolution functions.
- The s6-dns/hosts.h header provides functions to solve name and IP queries according the `/etc/hosts` file.
- The s6-dns/s6dns-fmt.h header provides formatting primitives to display RR contents.

(User-level asynchronous resolution functions are provided in the skadns library.)

Two functional macros are actually directly declared in the `s6dns.h` header:

- Call `s6dns_init()` before all your s6dns operations. s6dns_init() calls s6dns_rci_init(), extracting `resolv.conf` information to an internal global variable. The function returns 1 on success, and 0 (and sets errno) on failure. To also use the hosts database, you can call `s6dns_init_options(1)` instead.
- Call `s6dns_finish()` when you're done with libs6dns. It frees the resources used.