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.