From 416ef5e2bf59bb2e45066a1d5d91ac677c0f48e5 Mon Sep 17 00:00:00 2001 From: Laurent Bercot Date: Wed, 10 Dec 2014 03:05:47 +0000 Subject: Initial commit --- doc/libs6dns/index.html | 104 +++++++++++ doc/libs6dns/s6dns-domain.html | 137 ++++++++++++++ doc/libs6dns/s6dns-engine.html | 255 ++++++++++++++++++++++++++ doc/libs6dns/s6dns-fmt.html | 92 ++++++++++ doc/libs6dns/s6dns-ip46.html | 69 +++++++ doc/libs6dns/s6dns-message.html | 261 +++++++++++++++++++++++++++ doc/libs6dns/s6dns-rci.html | 109 +++++++++++ doc/libs6dns/s6dns-resolve.html | 387 ++++++++++++++++++++++++++++++++++++++++ 8 files changed, 1414 insertions(+) create mode 100644 doc/libs6dns/index.html create mode 100644 doc/libs6dns/s6dns-domain.html create mode 100644 doc/libs6dns/s6dns-engine.html create mode 100644 doc/libs6dns/s6dns-fmt.html create mode 100644 doc/libs6dns/s6dns-ip46.html create mode 100644 doc/libs6dns/s6dns-message.html create mode 100644 doc/libs6dns/s6dns-rci.html create mode 100644 doc/libs6dns/s6dns-resolve.html (limited to 'doc/libs6dns') diff --git a/doc/libs6dns/index.html b/doc/libs6dns/index.html new file mode 100644 index 0000000..db7ee35 --- /dev/null +++ b/doc/libs6dns/index.html @@ -0,0 +1,104 @@ + + + + + s6-dns: the s6dns library interface + + + + + + +

+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

+ + + +

Linking

+ + + +

Programming

+ +

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

+ + + +

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

+ +

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

+ + + + + diff --git a/doc/libs6dns/s6dns-domain.html b/doc/libs6dns/s6dns-domain.html new file mode 100644 index 0000000..b1492c3 --- /dev/null +++ b/doc/libs6dns/s6dns-domain.html @@ -0,0 +1,137 @@ + + + + + s6-dns: the s6dns_domain library interface + + + + + + +

+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, unsigned int 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, unsigned int 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, unsigned int 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. +

+ + + diff --git a/doc/libs6dns/s6dns-engine.html b/doc/libs6dns/s6dns-engine.html new file mode 100644 index 0000000..f0f9573 --- /dev/null +++ b/doc/libs6dns/s6dns-engine.html @@ -0,0 +1,255 @@ + + + + + s6-dns: the s6dns_engine library interface + + + + + + +

+libs6dns
+s6-dns
+Software
+skarnet.org +

+ +

The s6dns_engine library interface

+ +

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

+ +

General information

+ +

+ s6dns_engine is the nitty-gritty of DNS query management. These +are the low-level asynchronous primitives sending DNS queries over the +network, and getting answers. +

+ +

+ s6dns_engine has been inspired by Dan J. Bernstein's +dns_transmit +library, but does not borrow any code from it. Unlike +dns_transmit, s6dns_engine does not assume that +network send operations are instant successes; s6dns_engine +descriptors can be selected for writing as well as for reading. +Also, if the underlying +skalibs has been compiled with IPv6 support, s6dns_engine +supports native IPv6 transport. +

+ +

+ The s6dns_engine functions are used in the implementation of the +s6dns_resolven_loop function - which is nothing more than a +simple event loop around the s6dns_engine primitives - and the +skadnsd daemon. Both pieces of code are +good examples of how to use s6dns_engine. +

+ +

+ However, unless you're implementing a DNS cache, you probably should +not call the +s6dns_engine functions directly: they are very low-level. If you +need synchronous resolution, use the +s6dns_resolve functions. If you need +asynchronous DNS operations, use the +skadns functions, which are +designed to provide a higher level interface to multiple asynchronous +DNS queries. +

+ +

Data structures

+ +

+ A s6dns_engine_t structure holds all the data necessary to +manage a DNS query (and response). It must be initialized to S6DNS_ENGINE_ZERO +when first declared, and recycled with s6dns_engine_recycle() +after each use. It contains a stralloc, so it must be freed with +s6dns_engine_free() before being discarded, to avoid memory leaks. +

+ +

Functions

+ +

s6dns_engine_t life cycle

+ +

+ int s6dns_engine_init (s6dns_engine_t *dt, s6dns_ip46list_t const *servers, uint32 options, char const *q, unsigned int qlen, uint16 qtype, struct taia const *deadline, struct taia const *stamp) +

+ +

+Initializes dt with query q of length qlen +and type qtype. If d is an +encoded s6dns_domain_t, then d.s and d.len +are appropriate candidates for arguments q and qlen +respectively. +

+ +

+options can be 0 or an OR'ed +combination of the following, defined in s6-dns/s6dns-constants.h: +

+ + + +

+servers must point to a list of IP addresses as defined in +s6-dns/s6dns-ip46.h. Such a list can be +obtained from the /etc/resolv.conf file via the +s6dns_rci_fill() call when performing a +recursive query, or it must be constructed from a list of relevant +NS addresses when performing an iterative query. +

+ +

+stamp must be an accurate enough timestamp. deadline +sets up a deadline for the query: if the query hasn't been +satisfactorily answered by deadline - no matter how many +round-trips to network servers the library performs internally - then +it will be considered failed, and a timeout will be reported. +

+ +

+The function returns 1 if all went well, and 0 if an error occurred. +It returns instantly; it does not perform any network operation, +it just prepares dt to send a query. The actual data sending +will take place on the next s6dns_engine_event() call. +

+ +

+ void s6dns_engine_recycle (s6dns_engine_t *dt) +

+ +

+Recycles dt, making it ready for another use. This function +does not deallocate the heap memory used by dt, so it's faster than +s6dns_engine_free() and does not cause heap fragmentation. +

+ +

+ void s6dns_engine_free (s6dns_engine_t *dt) +

+ +

+Frees the heap memory used by dt. Also makes dt +ready for another use. It's advised to only use this function when +certain that dt will not be reused. +

+ +

Before the iopause()

+ +

+ The descriptor to select on is available as the fd field in +the s6dns_engine_t structure. +dt→fd should be read every iteration, because it can +change between iterations even if no event or timeout is reported +for dt. +

+ +

+ void s6dns_engine_nextdeadline (s6dns_engine_t const *dt, struct taia *a) +

+ +

+If dt needs handling before the absolute date *a, +then *a is updated +so it contains the earlier date. This is useful to compute the next +deadline in an iopause() loop. +

+ +

+ int s6dns_engine_isreadable (s6dns_engine_t const *dt) +

+ +

+Returns nonzero iff dt→fd is to be selected for reading. +Should be called in every iteration. +

+ +

+ int s6dns_engine_iswritable (s6dns_engine_t const *dt) +

+ +

+Returns nonzero iff dt→fd is to be selected for writing. +Should be called in every iteration. +

+ +

After the iopause()

+ +

+ int s6dns_engine_timeout (s6dns_engine_t *dt, struct taia const *stamp) +

+ +

+This function should be called if your selecting function returned 0, which +means that an event timed out. +stamp should contain the current time. The function returns -1 if +an error occurred, 1 if dt actually timed out, and 0 if nothing +special happened to dt (and your iopause timeout was caused by +something else). If the return value is not 0, dt is automatically +recycled. +

+ +

+ int s6dns_engine_event (s6dns_engine_t *dt, struct taia const *stamp) +

+ +

+This function should be called if your selecting function returned a positive +number, which means that some event got triggered. +stamp should contain the current time. The function returns +-1 if an error occurred (and dt is automatically recycled). It +returns 0 if no answer has arrived yet, and 1 if an answer is available. +

+ +

+The s6dns_engine_timeout() and s6dns_engine_event() functions, +when returning -1, make use of the following error codes: +

+ + +

+ char *s6dns_engine_packet (s6dns_engine_t const *dt) +

+ +

+Points to the response packet received from the network, +if s6dns_engine_event() returned 1. +

+ +

+ unsigned int s6dns_engine_packetlen (s6dns_engine_t const *dt) +

+ +

+Gives the length of the response packet, +if s6dns_engine_event() returned 1. +

+ +

+ You should recycle or free dt after reading the response packet. +

+ + + diff --git a/doc/libs6dns/s6dns-fmt.html b/doc/libs6dns/s6dns-fmt.html new file mode 100644 index 0000000..a586846 --- /dev/null +++ b/doc/libs6dns/s6dns-fmt.html @@ -0,0 +1,92 @@ + + + + + s6-dns: the s6dns_fmt library interface + + + + + + +

+libs6dns
+s6-dns
+Software
+skarnet.org +

+ +

The s6dns_fmt library interface

+ +

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

+ +

General information

+ +

+ s6dns_fmt provides primitives to format RR contents into +printable strings. +

+ +

Functions

+ +

+ unsigned int s6dns_fmt_domain (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. +To avoid that, S6DNS_FMT_DOMAIN is a suitable number of bytes to preallocate s. +This function is actually an alias to s6dns_domain_tostring. +

+ +

+ unsigned int s6dns_fmt_domainlist (char *s, unsigned int max, s6dns_domain_t const *list, unsigned int n, char const *delin, unsigned int delimlen)
+Writes into string s the list of n domains (in string form) +pointed to by list. Between each domain (and not after the last one), +string delim of length delimlen is appended. +The function 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. +To avoid that, S6DNS_FMT_DOMAINLIST(n) is a suitable number of bytes to preallocate s. +

+ +

+ unsigned int s6dns_fmt_hinfo (char *s, unsigned int max, s6dns_message_rr_hinfo_t const *p)
+Writes into string s the HINFO contained in *p: cpu, then os, +separated by a space. +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. +To avoid that, S6DNS_FMT_HINFO is a suitable number of bytes to preallocate s. +

+ +

+ unsigned int s6dns_fmt_mx (char *s, unsigned int max, s6dns_message_rr_mx_t const *p)
+Writes into string s the MX contained in *p: preference, then +exchanger name, separated by a space. +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. +To avoid that, S6DNS_FMT_MX is a suitable number of bytes to preallocate s. +

+ +

+ unsigned int s6dns_fmt_soa (char *s, unsigned int max, s6dns_message_rr_soa_t const *p)
+Writes into string s the SOA contained in *p: +mname, then rname, then serial number, refresh time, retry time, expiration time +and minimum time, separated by spaces. +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. +To avoid that, S6DNS_FMT_SOA is a suitable number of bytes to preallocate s. +

+ +

+ unsigned int s6dns_fmt_srv (char *s, unsigned int max, s6dns_message_rr_srv_t const *p)
+Writes into string s the SRV contained in *p: priority, +then weight, then port, then target, separated by spaces. +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. +To avoid that, S6DNS_FMT_SRV is a suitable number of bytes to preallocate s. +

+ + + diff --git a/doc/libs6dns/s6dns-ip46.html b/doc/libs6dns/s6dns-ip46.html new file mode 100644 index 0000000..27cbe2c --- /dev/null +++ b/doc/libs6dns/s6dns-ip46.html @@ -0,0 +1,69 @@ + + + + + s6-dns: the s6dns_ip46 library interface + + + + + + +

+libs6dns
+s6-dns
+Software
+skarnet.org +

+ +

The s6dns_ip46 library interface

+ +

+ The following functions are declared in the s6-dns/s6dns-ip46.h header, +and implemented as macros. +

+ +

General information

+ +

+ s6dns_ip46 is the transport abstraction layer. It allows +the functions declared in s6-dns/s6dns-engine.h +and s6-dns/s6dns-rci.h to be transport-agnostic, +i.e. to be able to work with both IPv4 and IPv6. +

+ +

+ If the underlying skalibs +has been compiled with + flag-noipv6, +or if it has detected at build time that the target host does not support +IPv6, then the s6dns-ip46 abstraction will be totally transparent and use +no resources at all. +

+ +

Data structures

+ +

+ A s6dns_ip46list_t structure holds a list of S6DNS_MAX_SERVERS (16) +IPv4 or IPv6 addresses. Such a mixed list can be constructed, for +instance, if the /etc/resolv.conf file contains both v4 and v6 +nameserver lines. +

+ +

Functions

+ +

+ If list is a s6dns_ip46list_t and i an integer +between 0 and DNS_MAX_SERVERS-1, then +

+ + + + + diff --git a/doc/libs6dns/s6dns-message.html b/doc/libs6dns/s6dns-message.html new file mode 100644 index 0000000..e06aa91 --- /dev/null +++ b/doc/libs6dns/s6dns-message.html @@ -0,0 +1,261 @@ + + + + + s6-dns: the s6dns_message library interface + + + + + + +

+libs6dns
+s6-dns
+Software
+skarnet.org +

+ +

The s6dns_message library interface

+ +

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

+ +

General information

+ +

+ s6dns_message provides functions to read and parse DNS messages +sent by servers and caches and containing answers to queries. +

+ +

Data structures

+ +

+ A s6dns_message_header_t is a structure containing the header +of a received DNS packet, broken down for easy access to the bits. +

+ +

+ A s6dns_message_rr_t is a structure containing the information +about a resource record given by an answer packet - all of it, except the +value of the answer itself, which is rtype-specific and has to be decoded +by rtype-specific functions. +

+ +

+ A s6dns_message_rr_func_t is the type of such a function. The +prototype is
+ int f (s6dns_message_rr_t const *rr, char const *packet, unsigned int packetlen, unsigned int pos, unsigned int section, void *data)
+

+ + + +

+ Various structures designed to store specific resource record types are +also provided. The list includes: +

+ + + +

Functions

+ +

Header management

+ +

+ void s6dns_message_header_pack (char *s, s6dns_message_header_t const *h)
+Packs the header *h into the 12 bytes pointed to by s. +

+ +

+ void s6dns_message_header_unpack (char const *s, s6dns_message_header_t *h)
+Unpacks the 12 bytes pointed to by s into the structure *h. +

+ +

Low-level RR decoding

+ +

+ The following primitives are used in the implementation of +s6dns_message_rr_func_t-typed functions, to read and decode information +stored in a DNS packet. Their arguments are: +

+ +
    +
  1. A pointer to the structure where the information is going to be stored
    2. +
  2. A read-only pointer to the beginning of the DNS packet
    3. +
  3. The length of the DNS packet
    4. +
  4. A pointer to an integer containing the current position in the +DNS packet, i.e. where the information is going to be read. If the functions +succeed, they automatically update the position so information can be read +sequentially.
    5. +
+ +

+ int s6dns_message_get_string (s6dns_domain_t *d, char const *packet, unsigned int packetlen, unsigned int *pos)
+Reads a character-string and stores it into *d. Returns 1 on success +and 0 on failure. Note that *d does not contain a domain, but the +s6dns_domain_t structure is adapted to store strings that do not +exceed 255 characters. d→s can be used to access the string, +and d→len its length. +

+ +

+ int s6dns_message_get_strings (char *s, unsigned int rdlength, char const *packet, unsigned int packetlen, unsigned int *pos
+This function takes an additional parameter rdlength. It reads a series of +character-strings and stores their concatenation into the string s, which +must be preallocated; it can never store more than rdlength bytes. It returns +-1 if it fails; on success, it returns the number of bytes written. The +rdlength parameter must be the length of the resource record containing +the series of character-strings. +

+ +

+ unsigned int s6dns_message_get_domain (s6dns_domain_t *d, char const *packet, unsigned int packetlen, unsigned int *pos)
+Reads a domain and stores it, in string form, into *d. +Returns 1 on success and 0 on failure, and sets errno: +

+ + + +

+ int s6dns_message_get_hinfo (s6dns_message_rr_hinfo_t *p, char const *packet, unsigned int packetlen, unsigned int *pos)
+Reads a HINFO RR and stores it into *p. Returns 1 on success or 0 +on failure. +

+ +

+ int s6dns_message_get_mx (s6dns_message_rr_mx_t *p, char const *packet, unsigned int packetlen, unsigned int *pos)
+Reads a MX RR and stores it into *p. Returns 1 on success or 0 on failure. +

+ +

+ int s6dns_message_get_soa (s6dns_message_rr_soa_t *p, char const *packet, unsigned int packetlen, unsigned int *pos)
+Reads a SOA RR and stores it into *p. Returns 1 on success or 0 on failure. +

+ +

+ int s6dns_message_get_srv (s6dns_message_rr_srv_t *p, char const *packet, unsigned int packetlen, unsigned int *pos)
+Reads a SRV RR and stores it into *p. Returns 1 on success or 0 on failure. +

+ +

High-level RR-specific parsing functions

+ +

+ s6dns_message_func_t s6dns_message_parse_answer_strings
+Parses character-strings located in the answer section of the packet. The +data argument is interpreted as a pointer to a s6dns_mpag_t, +which is a structure defined in the s6-dns/s6dns-message.h header +and used to store multiple character-strings. +

+ +

+ s6dns_message_func_t s6dns_message_parse_answer_domain
+Parses domains located in the answer section of the packet. The +data argument is interpreted as a pointer to a s6dns_dpag_t, +which is a structure defined in the s6-dns/s6dns-message.h header +and used to store multiple domains. +

+ +

+ s6dns_message_func_t s6dns_message_parse_answer_a
+Parses A RRs located in the answer section of the packet. The +data argument is interpreted as a pointer to a +stralloc, +and 4 bytes are appended to this stralloc for every IPv4 address found. +

+ + + s6dns_message_func_t s6dns_message_parse_answer_aaaa
+Parses AAAA RRs located in the answer section of the packet. The +data argument is interpreted as a pointer to a +stralloc, +and 16 bytes are appended to this stralloc for every IPv6 address found. +

+ +

+ s6dns_message_func_t s6dns_message_parse_answer_hinfo
+Parses HINFO RRs located in the answer section of the packet. The +data argument is interpreted as a pointer to a +genalloc +containing s6dns_message_rr_hinfo_t structures. +

+ +

+ s6dns_message_func_t s6dns_message_parse_answer_mx
+Parses MX RRs located in the answer section of the packet. The +data argument is interpreted as a pointer to a +genalloc +containing s6dns_message_rr_mx_t structures. +

+ +

+ s6dns_message_func_t s6dns_message_parse_answer_soa
+Parses SOA RRs located in the answer section of the packet. The +data argument is interpreted as a pointer to a +genalloc +containing s6dns_message_rr_soa_t structures. +

+ +

+ s6dns_message_func_t s6dns_message_parse_answer_srv
+Parses SRV RRs located in the answer section of the packet. The +data argument is interpreted as a pointer to a +genalloc +containing s6dns_message_rr_srv_t structures. +

+ +

High-level packet parsing

+ +

+ int s6dns_message_parse (s6dns_message_header_t *h, char const *packet, unsigned int packetlen, s6dns_message_rr_func_t *f, void *data)
+ This function parses the DNS packet packet of length packetlen. +It stores the packet header into *h. Then, for every RR in the answer, +authority or additional section of the packet, it calls f with the +relevant parameters. data is the extra pointer given to f to +store information. The function returns 1 if the parsing succeeds. Otherwise it +returns -1 if there is a local error unrelated to the packet, or 0 if no +appropriate answer can be decoded from the packet. errno then contains one +of the following values: +

+ + + + + diff --git a/doc/libs6dns/s6dns-rci.html b/doc/libs6dns/s6dns-rci.html new file mode 100644 index 0000000..1cf8a0e --- /dev/null +++ b/doc/libs6dns/s6dns-rci.html @@ -0,0 +1,109 @@ + + + + + s6-dns: the s6dns_rci library interface + + + + + + +

+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. +

+ + + +

+ 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. +

+ + + diff --git a/doc/libs6dns/s6dns-resolve.html b/doc/libs6dns/s6dns-resolve.html new file mode 100644 index 0000000..bbb3f57 --- /dev/null +++ b/doc/libs6dns/s6dns-resolve.html @@ -0,0 +1,387 @@ + + + + + s6-dns: the s6dns_resolve library interface + + + + + + +

+libs6dns
+s6-dns
+Software
+skarnet.org +

+ +

The s6dns_resolve library interface

+ +

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

+ +

General information

+ +

+ s6dns_resolve provides functions and macros - mostly macros - +to perform high level synchronous DNS resolution. +

+ +

+ All the functions declared here make synchronous calls to the network, so +they can block for a non-negligible amount of time. To avoid unbounded +waiting times, they always take 2 arguments at the end, deadline +and stamp. deadline is the read-only address of a +struct taia +containing an absolute time which is the deadline for the function, and +stamp is the read-write address of a struct taia being +an accurate enough representation of the current absolute time. If +the function has not returned by *deadline, then it immediately +returns with a failure code and errno set to ETIMEDOUT. In every case, +*stamp is automatically updated so it always represents the +absolute time accurately enough. +

+ +

+ In a single-threaded program, the STAMP global variable can be used to +store the current time. Macros ending with _g use this variable +automatically so you don't have to provide the stamp argument +everytime. Additionally, several resolution functions make implicit use +of global variables such as: +

+ + + +

+ Reentrant, non-global-using functions are also provided, with the _r +suffix. In other words, if foobarfunc is a resolution function, +the following prototypes are generally provided, from the simplest to the +most complex: +

+ + + +

+ For each set of four functions, only one is documented here. +The other prototypes can be found in the s6-dns/s6dns-resolve.h file. +

+ +

+ Some errno codes reported by these functions do not have +exactly the system meaning given by +strerror(). +To get a user-friendly error message, use +s6dns_constants_error_str(errno) instead. The s6dns_constants_error_str +function is declared in the s6dns-constants.h header. +

+ +

Functions

+ +

Single query resolution

+ +

+ These functions are ordered from the lowest level to the highest level. +

+ +

Basic wrapper around s6dns_engine

+ +

+ int s6dns_resolve_loop_r_g (s6dns_engine_t *dt, struct taia const *deadline)
+Resolves the query stored in dt. +Returns 1 on success or 0 on failure. +

+ +

Generic resolution functions

+ +

+ int s6dns_resolve_core_g (s6dns_domain_t const *d, uint16 qtype, struct taia const *deadline)
+Resolves the query on domain *d (in packet form), of type qtype. +Returns 0 on failure, or 1 on success, in which case +s6dns_engine_here contains the answer. +

+ +

+ int s6dns_resolve_parse_g (s6dns_domain_t const *d, uint16 qtype, s6dns_message_rr_func_t *f, void *data, struct taia const *deadline)
+Resolves the query on domain *d (in packet form), of type qtype, +then parses the answer with function f and stores the result into data. +Returns 1 if it succeeds, 0 if no data can be extracted from the answer, or -1 if an +error occurs. Sets errno in the last two cases. +

+ +

+ Note that the function can return 1 without appending anything to data. +This means that the servers confirmed that the domain exists, but f +has not been able to find any data relevant to the query in the answer. +This is very different from NXDOMAIN, which means that +the servers deny the actual existence of the domain, and which is reported +here as a return code of 0 with errno set to ENOENT. +

+ +

+ int s6dns_resolvenoq_g (char const *name, unsigned int len, uint16 qtype, s6dns_message_rr_func_t *f, void *data, struct taia const *deadline)
+Performs a query of type qtype on name name of length len, +without qualifying it. Parses the answer with function f and stores the +result into data. Returns 1 if it succeeds, 0 if no data can be extracted, +or -1 if an error occurs. Sets errno in the last two cases. +

+ +

+ int s6dns_resolveq_g (char const *name, unsigned int len, uint16 qtype, s6dns_message_rr_func_t *f, void *data, struct taia const *deadline)
+Performs a query of type qtype on name name of length len, +qualifying it first. Parses the answer with function f and stores the +result into data. Returns 1 if it succeeds, 0 if none of the FQDNs can +get a positive answer, or -1 if an error occurs. Sets errno in the last two cases. +

+ +

+ int s6dns_resolve_g (char const *name, unsigned int len, uint16 qtype, s6dns_message_rr_func_t *f, void *data, int qualif, struct taia const *deadline)
+Performs a query of type qtype on name name of length len. +Qualifies name first if qualif is nonzero; else, does not +qualify it. Parses the answer with function f and stores the +result into data. Returns 1 if it succeeds, 0 if none of the FQDNs can +get a positive answer, or -1 if an error occurs. Sets errno in the last two cases. +

+ +

High-level type-specific functions

+ +

+ int s6dns_resolve_a_g (stralloc *ips, char const *name, unsigned int len, int qualif, struct taia const *deadline)
+Performs an A query on name name of length len, qualifying it +iff qualif is nonzero. Returns -1 if an error occurs, or 0 if no answer +can be obtained from servers, or 1 if it succeeds, in which case the IPs are +appended to the stralloc *ips, using 4 bytes per answer. +

+ +

+ int s6dns_resolve_aaaa_g (stralloc *ips, char const *name, unsigned int len, int qualif, struct taia const *deadline)
+Performs an AAAA query on name name of length len, qualifying it +iff qualif is nonzero. Returns -1 if an error occurs, or 0 if no answer +can be obtained from servers, or 1 if it succeeds, in which case the IPs are +appended to the stralloc *ips, using 16 bytes per answer. +

+ +

+ int s6dns_resolve_aaaaa_g (genalloc *ips, char const *name, unsigned int len, int qualif, struct taia const *deadline)
+Performs an AAAA query and an A query at the same time on name name +of length len, qualifying it first iff qualif is nonzero. +Returns -1 if an error occurs, or 0 if no answer +can be obtained from servers, or a positive number if it succeeds: 1 if IPv4 addresses +were found, 2 if IPv6 addresses were found, and 3 if both were found. +The IPs are appended to the genalloc *ips, which contains an array of +ip46_t, the skalibs structure used to store IPv4 and IPv6 addresses +indiscriminately. +

+ +

+ int s6dns_resolve_ptr_g (genalloc *ds, char const *name, unsigned int len, int qualif, struct taia const *deadline)
+Performs a PTR query on name name of length len, qualifying it +iff qualif is nonzero. Returns -1 if an error occurs, or 0 if no answer +can be obtained from servers, or 1 if it succeeds, in which case the domains are +appended to the genalloc *ds, which contains an array of s6dns_domain_t. +

+ +

+ int s6dns_resolve_name4_g (genalloc *ds, char const *ip, struct taia const *deadline)
+Performs a PTR query on the in-addr.arpa. name representing the IPv4 +address ip (4 network-order bytes). +Returns -1 if an error occurs, or 0 if no answer +can be obtained from servers, or 1 if it succeeds, in which case the domains are +appended to the genalloc *ds, which contains an array of s6dns_domain_t. +

+ +

+ int s6dns_resolve_name6_g (genalloc *ds, char const *ip, struct taia const *deadline)
+Performs a PTR query on the ip6.arpa. name representing the IPv6 +address ip (16 network-order bytes). +Returns -1 if an error occurs, or 0 if no answer +can be obtained from servers, or 1 if it succeeds, in which case the domains are +appended to the genalloc *ds, which contains an array of s6dns_domain_t. +

+ +

+ int s6dns_resolve_name46_g (genalloc *ds, ip46_t const *ip, struct taia const *deadline)
+Calls s6dns_resolve_name6_g() or s6dns_resolve_name4_g() +depending on which ip is an IPv6 or IPv4 address. +

+ +

+ int s6dns_resolve_ns_g (genalloc *ds, char const *name, unsigned int len, int qualif, struct taia const *deadline)
+Performs a NS query on name name of length len, qualifying it +iff qualif is nonzero. Returns -1 if an error occurs, or 0 if no answer +can be obtained from servers, or 1 if it succeeds, in which case the domains are +appended to the genalloc *ds, which contains an array of s6dns_domain_t. +

+ +

+ int s6dns_resolve_cname_g (genalloc *ds, char const *name, unsigned int len, int qualif, struct taia const *deadline)
+Performs a CNAME query on name name of length len, qualifying it +iff qualif is nonzero. Returns -1 if an error occurs, or 0 if no answer +can be obtained from servers, or 1 if it succeeds, in which case the domains are +appended to the genalloc *ds, which contains an array of s6dns_domain_t. +

+ +

+ int s6dns_resolve_hinfo_g (genalloc *hinfos, char const *name, +unsigned int len, int qualif, struct taia const *deadline)
+ Performs an HINFO query on name name of length len, qualifying it +iff qualif is nonzero. Returns -1 if an error occurs, or 0 if no answer +can be obtained from servers, or 1 if it succeeds, in which case the domains are +appended to the genalloc *hinfos, which contains an array of +s6dns_message_rr_hinfo_t. +

+ +

+ int s6dns_resolve_mx_g (genalloc *mxs, char const *name, +unsigned int len, int qualif, struct taia const *deadline)
+ Performs an MX query on name name of length len, qualifying it +iff qualif is nonzero. Returns -1 if an error occurs, or 0 if no answer +can be obtained from servers, or 1 if it succeeds, in which case the domains are +appended to the genalloc *mxs, which contains an array of +s6dns_message_rr_mx_t. +

+ +

+ int s6dns_resolve_soa_g (genalloc *soas, char const *name, +unsigned int len, int qualif, struct taia const *deadline)
+ Performs an SOA query on name name of length len, qualifying it +iff qualif is nonzero. Returns -1 if an error occurs, or 0 if no answer +can be obtained from servers, or 1 if it succeeds, in which case the domains are +appended to the genalloc *soas, which contains an array of +s6dns_message_rr_soa_t. +

+ +

+ int s6dns_resolve_srv_g (genalloc *srvs, char const *name, +unsigned int len, int qualif, struct taia const *deadline)
+ Performs an SRV query on name name of length len, qualifying it +iff qualif is nonzero. Returns -1 if an error occurs, or 0 if no answer +can be obtained from servers, or 1 if it succeeds, in which case the domains are +appended to the genalloc *srvs, which contains an array of +s6dns_message_rr_srv_t. +

+ +

+ int s6dns_resolve_txt_g (stralloc *sa, genalloc *offsets, char const *name, +unsigned int len, int qualif, struct taia const *deadline)
+ Performs an TXT query on name name of length len, qualifying it +iff qualif is nonzero. Returns -1 if an error occurs, or 0 if no answer +can be obtained from servers, or 1 if it succeeds, in which case: +

+ + + +

Parallel resolution

+ +

+ int s6dns_resolven_loop_g (s6dns_engine_t *dtl, unsigned int n, +unsigned int or, struct taia const *deadline)
+ Resolves the n queries stored in the array pointed to by dtl, +in parallel. If or is zero, it does not return before all answers +have arrived. If or is 1, it returns when an answer arrives, but does +not return if a query generates an error (unless all queries do so). If +or is 2, it returns when an answer arrives or an error occurs. +Other values of or are unspecified yet. + +

+ The return code is as follows: +

+ + + +

+ If or is 1, a return code of -1 with errno set to ENOENT +means that all the queries failed. +

+ +

+ After the function returns, the status field of each +s6dns_engine_t contains the error code relative to the query. +A status of 0 means that an answer has properly arrived; EAGAIN means +that the query is still pending (and the s6dns_engine_t has not been +recycled); ECONNABORTED means that the query has not been properly +initialized. Other codes report various network problems. +

+ +

+ int s6dns_resolven_parse_g (s6dns_resolve_t const *list, unsigned int n, +struct taia const *deadline)
+Performs n complete resolutions in parallel, parsing the results. +Returns 1 in case of success or 0 if a global error occurred. +

+ +

+list is a pointer to an array of n s6dns_resolve_t, +which is a structure containing at least the following fields: +

+ + + +

+ The s6dns_resolven_parse() function is a simple, convenient way to +perform several resolutions in parallel to avoid the waiting time +incurred by serial resolutions. However, it is still a synchronous +function, and cannot replace a real asynchronous DNS library: for +more complex parallel resolution needs, use the +skadns library. +

+ + + -- cgit v1.3.1