Good version of hosts.h

Signed-off-by: Laurent Bercot <ska@appnovation.com>
author: Laurent Bercot <ska-skaware@skarnet.org> 2023-07-11 12:26:21 +0000
committer: Laurent Bercot <ska@appnovation.com> 2023-07-11 12:26:21 +0000
commit: 8cf671e973a4ea2ef7c9ca1321531a7ceeaa5073 (patch)
tree: a84faead6505a91ce91f2a86f07768e3aa318dda
parent: bce22be61a55a29084c8c0416be942622d2d8f87 (diff)
download: s6-dns-8cf671e973a4ea2ef7c9ca1321531a7ceeaa5073.tar.xz
3 files changed, 160 insertions, 21 deletions
diff --git a/doc/libs6dns/hosts.html b/doc/libs6dns/hosts.html
new file mode 100644
index 0000000..93bfc10
--- /dev/null
+++ b/doc/libs6dns/hosts.html
@@ -0,0 +1,129 @@
+<html>
+  <head>
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+    <meta http-equiv="Content-Language" content="en" />
+    <title>s6-dns: the s6dns_hosts library interface</title>
+    <meta name="Description" content="s6-dns: the s6dns_hosts library interface" />
+    <meta name="Keywords" content="s6-dns dns s6dns_hosts library libs6dns /etc/hosts" />
+    <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> -->
+  </head>
+<body>
+
+<p>
+<a href="index.html">libs6dns</a><br />
+<a href="../">s6-dns</a><br />
+<a href="//skarnet.org/software/">Software</a><br />
+<a href="//skarnet.org/">skarnet.org</a>
+</p>
+
+<h1> The <tt>s6dns_hosts</tt> library interface </h1>
+
+<p>
+ The following functions are declared in the <tt>s6-dns/hosts.h</tt> header,
+and implemented in the <tt>libs6dns.a</tt> or <tt>libs6dns.so</tt> library.
+</p>
+
+<h2> General information </h2>
+
+<p>
+ <tt>s6dns_hosts</tt> provides functions and macros - mostly macros -
+to perform name-to-IP or IP-to-name resolution according to the
+local <tt>/etc/hosts</tt> file.
+</p>
+
+<p>
+ Most of the functions declared here are variations of another, more
+generic function. Typically, a <em>foobar_r</em> function is the
+generic one, and will take additional arguments such as: a pointer to
+a local hosts database (compiled to an efficient format), and/or a
+list and number of rules for qualification. The corresponding <em>foobar</em>
+function is the same, except that it uses global variables to fill
+these additional arguments: for instance, the hosts database made from
+<tt>/etc/hosts</tt>, or the qualification rules computed from
+<tt>/etc/resolv.conf</tt>. We document the simpler functions &mdash; even
+though they're macros, we pretend they're functions; please refer to
+the <a href="https://git.skarnet.org/cgi-bin/cgit.cgi/s6-dns/tree/src/include/s6-dns/hosts.h">s6-dns/hosts.h</a>
+file for the exact prototypes or if you want to use the generic functions.
+</p>
+
+<ul>
+ <li> <tt>s6dns_engine_here</tt>: a global
+<a href="s6dns-engine.html">s6dns_engine_t</a> storing the current
+query, for sequential queries. </li>
+ <li> <tt>s6dns_debughook_zero</tt>: a global <tt>s6dns_debughook_t</tt>
+meaning no debugging is needed. </li>
+ <li> <tt>s6dns_rci_here</tt>: a global
+<a href="s6dns-rci.html">s6dns_rci_t</a> containing the current
+resolv.conf information. </li>
+</ul>
+
+<h2> Global variables </h2>
+
+<p>
+<code> cdb s6dns_hosts_here </code> <br />
+<tt>s6dns_hosts_here</tt> is the global <tt>cdb</tt> database containing
+the compiled data from <tt>/etc/hosts</tt>. You normally do not need to
+use it manually because it is implicitly supplied to functions when you
+use the macros without a <tt>_r</tt> suffix.
+</p>
+
+
+<h2> Functions </h2>
+
+<h3> Preparation </h3>
+
+<p>
+<code> int s6dns_hosts_compile (int fdr, int fdw) </code> <br />
+Compiles the text file data from file descriptor <tt>fdr</tt>,
+which should be in <tt>/etc/hosts</tt> format, into a cdb file
+written to file descriptor <tt>fdw</tt>. <tt>fdr</tt> must be
+open for reading, and <tt>fdw</tt> must be open for writing and
+seekable. The function returns 1 on success and 0 (and sets errno)
+on failure.
+</p>
+
+<p>
+ You normally don't need to use this function yourself, because
+it's implicitly used by the following one.
+</p>
+
+<p>
+<code> int s6dns_hosts_init (void) </code> <br />
+Initializes the database from the <tt>/etc/hosts</tt> file.
+If there's a pre-compiled <tt>/etc/hosts.cdb</tt> file that
+is more recent than <tt>/etc/hosts</tt>, then it is used;
+else, the <tt>/etc/hosts</tt> file is compiled into a
+temporary file under <tt>/tmp</tt>, which is used and
+immediately unlinked. The function returns 1 on success and
+0 (and sets errno) on failure.
+</p>
+
+<p>
+<code> int s6dns_hosts_init_r (cdb *c, char const *txtfile, char const *cdbfile, char const *prefix) </code> <br />
+The generic version of the above function. Initializes the database
+in <em>*c</em> from the compiled file <em>cdbfile</em> if it exists and is
+more recent than <em>txtfile</em>, else compiles <em>txtfile</em> into
+a temporary file with a path starting with <em>prefix</em>, makes it
+accessible in <em>*c</em> and immediately unlinks it.
+</p>
+
+<p>
+<code> void s6dns_hosts_free (void) </code> <br />
+Frees the compiled hosts database. Only use this if
+you're certain you'll have no more use for it.
+</p>
+
+<p>
+<code> void s6dns_hosts_free_r (cdb *c) </code> <br />
+The generic version of the above function.
+</p>
+
+<h3> IP to name resolution </h3>
+
+<p>
+<code> int s6dns_hosts_name_r (cdb const *c, char const *ip, stralloc *storage, genalloc *indices, int is6) </code> <br />
+</p>
+
+</body>
+</html>
diff --git a/src/include/s6-dns/hosts.h b/src/include/s6-dns/hosts.h
index 7c11af0..0f85d0b 100644
--- a/src/include/s6-dns/hosts.h
+++ b/src/include/s6-dns/hosts.h
@@ -13,8 +13,10 @@ extern cdb s6dns_hosts_here ;
 
 extern int s6dns_hosts_compile (int, int) ;
 
-extern int s6dns_hosts_init (cdb *) ;
-#define s6dns_hosts_free(c) cdb_free(c)
+extern int s6dns_hosts_init_r (cdb *, char const *, char const *, char const *) ;
+#define s6dns_hosts_init() s6dns_hosts_init_r(&s6dns_hosts_here, "/etc/hosts", "/etc/hosts.cdb", "/tmp/hosts.cdb")
+#define s6dns_hosts_free_r(c) cdb_free(c)
+#define s6dns_hosts_free() s6dns_hosts_free_r(&s6dns_hosts_here)
 
 
 
diff --git a/src/libs6dns/s6dns_hosts_init.c b/src/libs6dns/s6dns_hosts_init.c
index d3cd863..762d738 100644
--- a/src/libs6dns/s6dns_hosts_init.c
+++ b/src/libs6dns/s6dns_hosts_init.c
@@ -1,5 +1,6 @@
 /* ISC license. */
 
+#include <string.h>
 #include <unistd.h>
 #include <errno.h>
 #include <stdlib.h>
@@ -11,16 +12,15 @@
 
 #include <s6-dns/hosts.h>
 
-int s6dns_hosts_init (void)
+int s6dns_hosts_init_r (cdb *c, char const *txtfile, char const *cdbfile, char const *tmpprefix)
 {
-  int fdr, fdw ;
-  char tmp[24] = "/tmp/hosts.cdb:XXXXXX" ;
-  int fdc = openc_read("/etc/hosts.cdb") ;
+  int fdr ;
+  int fdc = openc_read(cdbfile) ;
   if (fdc >= 0)
   {
     struct stat stc, str ;
     if (fstat(fdc, &stc) == -1) goto errc ;
-    if (stat("/etc/hosts", &str) == -1)
+    if (stat(txtfile, &str) == -1)
     {
       if (errno == ENOENT) goto useit ;
       else goto errc ;
@@ -28,21 +28,29 @@ int s6dns_hosts_init (void)
     if (stc.st_mtim > str.st_mtim) goto useit ;
     fd_close(fdc) ;
   }
-  fdr = openc_read("/etc/hosts") ;
+
+  fdr = openc_read(txtfile) ;
   if (fdr == -1) return errno == ENOENT ? (errno = 0, 0) : -1 ;
-  fdw = mkstemp(tmp) ;
-  if (fdw == -1) goto errr ;
-  if (!s6dns_hosts_compile(fdr, fdw)) goto errw ;
-  if (lseek(fdw, 0, SEEK_SET) == -1) goto errw ;
-  if (!cdb_init_fromfd(&s6dns_hosts_here, fdw)) goto errw ;
-  fd_close(fdw) ;
-  unlink_void(tmp) ;
-  fd_close(fdr) ;
-  return 1 ;
+  {
+    int fdw ;
+    size_t len = strlen(tmpprefix) ;
+    char tmp[len + 8] ;
+    memcpy(tmp, tmpprefix, len) ;
+    memcpy(tmp + len, ":XXXXXX", 8) ;
+    fdw = mkstemp(tmp) ;
+    if (fdw == -1) goto errr ;
+    if (!s6dns_hosts_compile(fdr, fdw)) goto errw ;
+    if (lseek(fdw, 0, SEEK_SET) == -1) goto errw ;
+    if (!cdb_init_fromfd(c, fdw)) goto errw ;
+    fd_close(fdw) ;
+    unlink_void(tmp) ;
+    fd_close(fdr) ;
+    return 1 ;
 
- errw:
-  fd_close(fdw) ;
-  unlink_void(tmp) ;
+   errw:
+    fd_close(fdw) ;
+    unlink_void(tmp) ;
+  }
  errr:
   fd_close(fdr) ;
   return -1 ;
@@ -52,7 +60,7 @@ int s6dns_hosts_init (void)
   return -1 ;
 
  useit:
-  if (!cdb_init_fromfd(&s6dns_hosts_here, fdc))
+  if (!cdb_init_fromfd(c, fdc))
   {
     fd_close(fdc) ;
     return 0 ;
author	Laurent Bercot <ska-skaware@skarnet.org>	2023-07-11 12:26:21 +0000
committer	Laurent Bercot <ska@appnovation.com>	2023-07-11 12:26:21 +0000
commit	8cf671e973a4ea2ef7c9ca1321531a7ceeaa5073 (patch)
tree	a84faead6505a91ce91f2a86f07768e3aa318dda
parent	bce22be61a55a29084c8c0416be942622d2d8f87 (diff)
download	s6-dns-8cf671e973a4ea2ef7c9ca1321531a7ceeaa5073.tar.xz