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

libs6dns
s6-dns
Software
skarnet.org

# The `s6dns_domain` library interface

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

## General information

`s6dns_domain` provides primitives to perform basic operations on domain names.

## Data structures

A `s6dns_domain_t` is a structure that s6dns uses internally to represent a domain name. It can be in string form (or decoded form), which is close to the printable form seen by users, or in packet form (or encoded form), which is the format used in the DNS protocol.

A `s6dns_domain_t` is a flat structure and can be declared on the stack.

## Functions

`int s6dns_domain_fromstring (s6dns_domain_t *d, char const *s, size_t len)`
Makes a (string form) domain from string s of length len, and stores it into *d. Returns 1 if it succeeds, otherwise it returns 0 and sets errno appropriately - most likely ENAMETOOLONG, i.e. the name in s is not a well-formed domain name.

`unsigned int s6dns_domain_tostring (char *s, unsigned int max, s6dns_domain_t const *d)`
Writes into string s the domain contained in *d (in string form). Returns the number of bytes written, or 0 in case of failure. If the output would be more than max bytes, 0 ENAMETOOLONG is returned.

`int s6dns_domain_noqualify (s6dns_domain_t *d)`
Makes sure that *d is fully qualified. This is done without using qualification: a trailing dot is simply appended if the domain doesn't already have one. Returns 1 if it succeeds, or 0 if it fails.

`unsigned int s6dns_domain_qualify (s6dns_domain_t *list, s6dns_domain_t const *d, char const *rules, unsigned int rulesnum)`
Performs qualification on domain *d according to the first rulesnum rules stored in string rules. Stores the output (at most rulesnum domains) into the array pointed to by list. Returns 0 on failure, or the number of written domains if it succeeds. This number can be lesser than rulesnum, for instance if *d is already fully qualified.
Valid rules and rulesnum can be obtained via functions declared in s6dns-rci.h.

`int s6dns_domain_encode (s6dns_domain_t *d)`
Encodes domain *d from string form to packet form. Returns 1 if it succeeds or 0 if it fails - for instance, *d is not a valid string form (EINVAL).

`unsigned int s6dns_domain_encodelist (s6dns_domain_t *list, unsigned int n)`
Encodes n domains pointed to by list from string form to packet form, stopping at the first failure. Returns the number of successfully encoded domains, normally n.

`int s6dns_domain_decode (s6dns_domain_t *d)`
Decodes domain *d from packet form to string form. Returns 1 if it succeeds or 0 if it fails - for instance, *d is not a valid packet form (EPROTO).

`int s6dns_domain_fromstring_noqualify_encode (s6dns_domain_t *d, char const *s, size_t len)`
Higher-level function wrapping some of the above. Makes an encoded, fully qualified (without resorting to qualification) domain from string s of length len. Returns 1 if it succeeds and 0 if it fails.

`unsigned int s6dns_domain_fromstring_qualify_encode (s6dns_domain_t *list, char const *s, size_t len, char const *rules, unsigned int rulesnum)`
Another wrapping function. It makes a list of encoded, fully qualified domains, from string s of length len using rulesnum qualification rules in rules. It writes at most rulesnum domains into the array pointed to by list and returns the number of written domains, or 0 on an error.

`void s6dns_domain_arpafromip4 (s6dns_domain_t *d, char const *ip)`
Writes into d the `in-addr.arpa.` domain corresponding to IPv4 address ip (4 bytes, in network byte order), in string form.

`void s6dns_domain_arpafromip6 (s6dns_domain_t *d, char const *ip, unsigned int mask)`
Writes into d the `ip6.arpa.` domain corresponding to the first mask bits of IPv6 address ip (16 bytes, in network byte order), in string form. Only multiples of 4 count for mask, i.e. the output will be the same if mask is (for instance) 125, 126, 127 or 128.