From 207845f50a8fb54fe8e584928078dc3687399caf Mon Sep 17 00:00:00 2001 From: Laurent Bercot Date: Wed, 12 Jul 2023 16:53:59 +0000 Subject: Pass on all clients, add hosts support wherever applicable Signed-off-by: Laurent Bercot --- doc/libs6dns/hosts.html | 159 +++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 136 insertions(+), 23 deletions(-) (limited to 'doc/libs6dns/hosts.html') diff --git a/doc/libs6dns/hosts.html b/doc/libs6dns/hosts.html index 93bfc10..b9a03bf 100644 --- a/doc/libs6dns/hosts.html +++ b/doc/libs6dns/hosts.html @@ -71,7 +71,7 @@ use the macros without a _r suffix.

Functions

-

Preparation

+

Compilation

int s6dns_hosts_compile (int fdr, int fdw)
@@ -84,45 +84,158 @@ on failure.

- You normally don't need to use this function yourself, because -it's implicitly used by the following one. + You normally don't need to use this function yourself. To +compile the hosts database prior to use, you can call the +s6-dns-hosts-compile +program (which uses this function). Alternatively, +at initialization time, the hosts database will be compiled +automatically if there isn't a more recent compiled version.

+

Initialization

+

- int s6dns_hosts_init (void)
-Initializes the database from the /etc/hosts file. -If there's a pre-compiled /etc/hosts.cdb file that + int s6dns_hosts_init (cdb *c, char const *txtfile, char const *cdbfile, char const *prefix)
+Initializes the compiled hosts database in *c. +If there's a pre-compiled cdbfile file that is more recent than /etc/hosts, then it is used; -else, the /etc/hosts file is compiled into a -temporary file under /tmp, which is used and -immediately unlinked. The function returns 1 on success and -0 (and sets errno) on failure. +else, the txtfile file is compiled into a +temporary file starting with prefix, which is used and +immediately unlinked. The function returns -1 (and sets errno) +on failure, 1 on success, and 0 if it can find neither a +suitable cdbfile nor a suitable txtfile.

- int s6dns_hosts_init_r (cdb *c, char const *txtfile, char const *cdbfile, char const *prefix)
-The generic version of the above function. Initializes the database -in *c from the compiled file cdbfile if it exists and is -more recent than txtfile, else compiles txtfile into -a temporary file with a path starting with prefix, makes it -accessible in *c and immediately unlinks it. + void s6dns_hosts_free (cdb *c)
+Frees the compiled hosts database in c.

- void s6dns_hosts_free (void)
-Frees the compiled hosts database. Only use this if -you're certain you'll have no more use for it. + You probably don't need to use these functions yourself: +instead, the higher-level s6dns_init() and +s6dns_finish() functions perform all the necessary +initialization and cleanup, including the hosts database one.

+ +

IP to name resolution

+

- void s6dns_hosts_free_r (cdb *c)
-The generic version of the above function. + int s6dns_hosts_name (char const *ip, stralloc *storage, genalloc *indices, int is6)
+Gets the list of names for IP address ip from the hosts database. +The names are stored in the stralloc *storage; for each name, +its index in storage→s is appended, as a size_t, +to the genalloc *indices. If is6 is nonzero, ip +is interpreted as an IPv6 address, i.e. a network byte order sequence of +16 bytes; otherwise it is interpreted as an IPv4 address, i.e. a network +byte order sequence of 4 bytes. The function returns -1 (and sets errno) +in case of failure, 0 if no match could be found (which includes no +existing hosts database), or the number of names it found. Names listed +as the first name on a line in /etc/hosts are always given as +fully qualified, i.e. with a terminating dot; other names are given as +they were input in /etc/hosts.

-

IP to name resolution

+

+ int s6dns_hosts_name4 (char const *ip, stralloc *storage, genalloc *indices)
+Same, but ip is assumed to be an IPv4. +

+ +

+ int s6dns_hosts_name6 (char const *ip, stralloc *storage, genalloc *indices)
+Same, but ip is assumed to be an IPv6. +

+ +

Name to IP resolution

+ +

Fully qualified names

+ +

+ extern int s6dns_hosts_a_noq (char const *name, stralloc *ip4s)
+Gets the list of IPv4 addresses for name name from the hosts database. +The addresses are stored in the stralloc *ip4s, in network byte order, +4 bytes per item. name is assumed to be fully qualified: skarnet.org +will yield the same results as skarnet.org., and blah will yield +the same results as blah. with the ending dot. The function returns -1 +(and sets errno) in case of failure, 0 if no match (including no valid hosts +database), or the number of IP addresses appended to *ip4s (i.e. the +length increase divided by 4). +

+ +

+ extern int s6dns_hosts_aaaa_noq (char const *name, stralloc *ip6s)
+Same as above, but gets the list of IPv6 addresses for name; there are +16 bytes per address instead of 4. +

+ +

+ extern int s6dns_hosts_aaaaa_noq (char const *name, genalloc *ips)
+Same as above, but gets the list of all IP addresses for name, v4 or v6 +indiscriminately. Every address is stored in the genalloc *ips as an +ip46full structure. +

+ +

Aliases

+ +

+ extern int s6dns_hosts_a_unq (char const *name, stralloc *ip4s)
+Gets the list of IPv4 addresses for name name from the hosts database. +The addresses are stored in the stralloc *ip4s, in network byte order, +4 bytes per item. name is assumed to be unqualified: blah +is interpreted as a local alias that will only match a blah +entry in /etc/hosts that does not appear as a first +entry. The function returns -1 +(and sets errno) in case of failure, 0 if no match (including no valid hosts +database), or the number of IP addresses appended to *ip4s (i.e. the +length increase divided by 4). +

+ +

+ extern int s6dns_hosts_aaaa_unq (char const *name, stralloc *ip6s)
+Same as above, but gets the list of IPv6 addresses for name; there are +16 bytes per address instead of 4. +

+ +

+ extern int s6dns_hosts_aaaaa_unq (char const *name, genalloc *ips)
+Same as above, but gets the list of all IP addresses for name, v4 or v6 +indiscriminately. Every address is stored in the genalloc *ips as an +ip46full structure. +

+ +

With qualification

+ +

+ extern int s6dns_hosts_a_q (char const *name, stralloc *ip4s)
+Gets the list of IPv4 addresses, from the hosts database, for all possible +qualifications for name name. +The addresses are stored in the stralloc *ip4s, in network byte order, +4 bytes per item. The function returns -1 +(and sets errno) in case of failure, 0 if no match (including no valid hosts +database), or the number of IP addresses appended to *ip4s (i.e. the +length increase divided by 4). +

+ +

+ First, name is looked up in the hosts database as a simple +unqualified names. Then, name is qualified with all the suffixes +read from /etc/resolv.conf, and all of the resulting FQDNs are +looked up in the hosts database. All the results are concatenated and +appended to the *ip4s stralloc. +

+ +

+ extern int s6dns_hosts_aaaa_q (char const *name, stralloc *ip6s)
+Same as above, but gets the list of IPv6 addresses for name; there are +16 bytes per address instead of 4. +

- int s6dns_hosts_name_r (cdb const *c, char const *ip, stralloc *storage, genalloc *indices, int is6)
+ extern int s6dns_hosts_aaaaa_q (char const *name, genalloc *ips)
+Same as above, but gets the list of all IP addresses for name, v4 or v6 +indiscriminately. Every address is stored in the genalloc *ips as an +ip46full structure.

-- cgit v1.2.3