1 files changed, 249 insertions, 0 deletions
diff --git a/man/dns.3 b/man/dns.3
new file mode 100644
index 0000000..837450c
--- /dev/null
+++ b/man/dns.3
@@ -0,0 +1,249 @@
+.TH qlibs: dnsresolv
+.SH NAME
+dns \- dns resolver routines
+.SH SYNTAX
+.B #include \(dqdnsresolv.h\(dq
+
+int \fBdns_ip4_packet\fP(stralloc *\fIout\fR,const char *\fIbuf\fR,unsigned int \fIlen\fR);
+.br
+int \fBdns_ip4\fP(stralloc *\fIout\fR,stralloc *\fIfqdn\fR);
+
+int \fBdns_ip6_packet\fP(stralloc *\fIout\fR,const char *\fIbuf\fR,unsigned int \fIlen\fR);
+.br
+int \fBdns_ip6\fP(stralloc *\fIout\fR,stralloc *\fIfqdn\fR);
+
+int \fBdns_mx\fP(stralloc *\fIout\fR,stralloc *\fIfqdn\fR);
+.br
+int \fBdns_mx_packet\fP(stralloc *\fIout\fR,const char *\fIbuf\fR,unsigned int \fIlen\fR);
+
+void \fBdns_name4_domain\fP(char \fIq\fR[DNS_NAME4_DOMAIN],const char *\fIip\fR[4]);
+.br
+int \fBdns_name4\fP(stralloc *\fIout\fR,const char *\fIip\fR[4]);
+
+void \fBdns_name6_domain\fP(char \fIq\fR[DNS_NAME6_DOMAIN],const char *\fIip\fR[16]);
+.br
+int \fBdns_name6\fP(stralloc *\fIout\fR,const char *\fIip\fR[16]);
+
+int \fBdns_name\fP(stralloc *\fIout\fR,const char *\fIip\fR[16]);
+.br
+int \fBdns_name_packet\fP(stralloc *\fIout\fR,const char *\fIbuf\fR,unsigned int \fIlen\fR);
+
+int \fBdns_txt\fP(stralloc *\fIout\fR,stralloc *\fIfqdn\fR);
+.br
+int \fBdns_txt_packet\fP(stralloc *\fIout\fR,const char *\fIbuf\fR,unsigned int \fIlen\fR);
+
+int \fBdns_cname\fP(stralloc *\fIout\fR,stralloc *\fIfqdn\fR);
+.br
+int \fBdns_cname_packet\fP(stralloc *\fIout\fR,const char *\fIbuf\fR,unsigned int \fIlen\fR);
+
+int \fBdns_ip4_qualify\fP(stralloc *\fIout\fR,stralloc *\fIfqdn\fR,const stralloc *\fIudn\fR);
+.br
+int \fBdns_ip6_qualify\fP(stralloc *\fIout\fR,stralloc *\fIfqdn\fR,const stralloc *\fIudn\fR);
+.br
+int \fBdns_ip_qualify\fP(stralloc *\fIout\fR,stralloc *\fIfqdn\fR,const stralloc *\fIudn\fR);
+.SH DESCRIPTION
+.B dns_ip[4|6]_packet 
+is a low-level component of 
+.BR dns_ip[4|6] , 
+designed to support asynchronous DNS lookups. 
+It reads a DNS packet of length \fIlen\fR from
+\fIbuf\fR, extracts the IP(4|6) addresses from the answer section of the packet and
+puts the addresses into \fIout\fR.
+
+.B dns_ip[4|6]
+looks up 4/16-byte IPv6 addresses for the fully qualified domain name of
+\fIfqdn\fR.  It puts the concatenation of the IPv[4|6] addresses into \fIout\fR and
+returns the number of received answers for \fIfqdn\fR or \fI0\fR if none are replied.
+If the domain does not exist in DNS, or has no IP addresses,
+\fIout\fR will be empty.  More generally, if \fIfqdn\fR is considered by
+.B dns_ip4
+to be a dotted-decimal IPv4 address, it is provissioned as \fIout\fR 
+without checking the DNS while returning \fI1\fR. 
+Brackets may enclose the dotted-decimal IP address; they are ignored.
+
+.B dns_name[4|6]_packet 
+is a low-level component of 
+.B dns_name[4|6] 
+designed to support asynchronous DNS lookups. 
+It reads a DNS packet of length \fIlen\fR from \fIbuf\fR,
+
+.B dns_name[4|6]_domain 
+is a low-level component of 
+.BR dns_name[4|6] .  
+It converts an IP address such as 
+.I 1.2.3.4 
+or 
+.I 4321:0:1:2:3:4:567:89ab 
+into a domain name such as
+.I 4.3.2.1.in-addr.arpa 
+or 
+.I b.a.9.8.7.6.5.0.4.0.0.0.3.0.0.0.2.0.0.0.1.0.0.0.0.0.0.0.1.2.3.4.ip6.arpa
+and places the packet-encoded domain name into \fIq\fR.
+.I q 
+is zero terminated.
+.I q 
+must have space for DNS_NAME[4|6]_DOMAIN bytes.
+
+.B dns_mx_packet 
+is a low-level component of 
+.BR dns_mx , 
+designed to support asynchronous DNS lookups. 
+It reads a DNS packet of length \fIlen\fR from \fIbuf\fR,
+extracts the MX records from the answer section of the packet, puts the
+result into \fIout\fR, and returns the number of replies received 
+or \fI-1\fR the same way as 
+.BR dns_mx .
+
+.B dns_mx 
+looks up MX records for the fully-qualified domain name in
+\fIfqdn\fR. It puts the MX records into \fIout\fR and returns the number of 
+received records or \fI0\fR.
+Each MX record is a two-byte MX distance (big endian) followed by a
+\\0-terminated dot-encoded domain name. If the domain does not exist in
+DNS, or has no MX records, \fIout\fR will be empty.
+
+.B dns_txt_packet 
+is a low-level component of 
+.BR dns_txt , 
+designed to support
+asynchronous DNS lookups. It reads a DNS packet of length \fIlen\fR from \fIbuf\fR,
+extracts the TXT records from the answer section of the packet, puts the
+result into \fIout\fR, and returns the number of replies 
+or \fI-1\fR the same way as \fBdns_txt\fR.
+
+.B dns_txt 
+looks up TXT records for the fully-qualified domain name in
+\fIfqdn\fR. It puts the concatenation of the TXT records into \fIout\fR
+and returns the number of replies received.  
+If the domain does not exist in DNS, or has no TXT records, \fIout\fR will be empty.
+
+.B dns_cname_packet 
+is a low-level component of 
+.BR dns_cname ,
+designed to support
+asynchronous DNS lookups. It reads a DNS packet of length \fIlen\fR from \fIbuf\fR,
+extracts the TXT records from the answer section of the packet, puts the
+result into \fIout\fR, and returns the number of replies received  or
+\fI-1\fR the same way as \fBdns_cname\fR.
+
+.B dns_cname
+looks up the canonical name for a given
+.IR fqdn .
+
+.B dns_ip[4|6]_qualify 
+feeds the name \fIudn\fR through qualification and looks up their
+4-byte/16-byte IP addresses. It puts the fully qualified domain name
+into \fIfqdn\fR and the concatenation of the IP addresses into \fIout\fR, 
+while returning the number of encountered IP addresses.
+.B dns_ip[4|6]_qualify
+evaluates the environment variables
+.I $DNSREWRITEFILE
+pointing to
+.I /etc/dnsrewrite
+and
+.I $LOCALDOMAIN
+and finally reading
+.I /etc/resolv.conf
+to build the
+.I Full Qualified Domain Name (FQDN)
+using the
+.I domain suffix
+for
+.IR hostname .
+.B dns_ip_qualify
+returns
+.I out
+as
+.I IP[4|6]
+and
+.IR FQDN .
+If the domain does not exist in DNS, or has no IP addresses,
+\fIout\fR will be empty and the return code is \fI0\fR.
+
+In case
+.B dns_ip[4|6]_qualify
+is fed with an
+.I IP[4|6]
+addresses instead of domain names,
+it recognizes those not to be subject of
+.IR qualification .
+The particular names
+.IR localhost ,
+.I ip4-loopback
+and
+.I ip6-loopback
+are treated locally and mapped to
+the respective
+.I IP[4|6]
+addresses (and vice versa)
+without facilitating a DNS lookup.
+.SH "INPUT"
+For the high-level routines
+.BR dns_ip[4|6] ,
+.BR dns_ip_qualify[4|6] ,
+.BR dns_name[4|6] ,
+.BR dns_mx ,
+.BR dns_name ,
+.BR dns_txt 
+and 
+.BR dns_cname
+the provided input variable
+.I stralloc \*\fqdn
+needs to be un-terminated, thus the given
+string length is identitical to the number of 
+.I fqdn 
+characters.
+.SH "OUTPUT"
+The returned IP addresses are given as character (byte) strings
+with 4 or 16 bytes:
+.B dns_ip4
+and 
+.B dns_ip4_qualifiy
+return 4 byte IPv4 addresses, where as 
+.B dns_ip6
+and 
+.B dns_ip
+as well as
+.B dns_ip6_qualify
+and
+.B dns_ip_qualify
+return sets of 16 byte IPv6 addresses, where
+the potential IPv4 addresses are given in their
+IPv6-mapped-IPv4 representation.
+.SH "RETURN CODES"
+The dns routines 
+.BR dns_cname* ,
+.BR dns_ip* ,
+.BR dns_mx* ,
+.B dns_name*
+and
+.BR dns_txt*
+return the number of answers received, which may be 
+.I 0 
+and potentially
+.I -1
+in case of a memory failure. The full set of return codes:
+
+.EX
+Value |  Macro   | Explaination 
+------+----------+-------------------------------------
+ n>0  |          | n = number of answers reeceived
+   0  | DNS_NXD  | either NXDOMAIN or NODATA
+  -1  | DNS_MEM  | out of memory (fatal)
+  -2  | DNS_ERR  | parsing errors
+  -3  | DNS_COM  | socket communicaton errror; SERVFAIL
+  -4  | DNS_INT  | internal error
+  -5  | DNS_SOFT | DNS_ERR or DNS_COM
+  -6  | DNS_HARD | DNS loop problem (CNAME)
+.EE
+
+.I errno 
+is set appropriately.
+In case of a failure, the respective output variables like
+\fIout\fR and \fIfqdn\fR may or may not change.
+Since a received reply may be empty, always check the length of the
+received output additionally.
+.SH "SEE ALSO"
+ip4(3), 
+ip6(3), 
+dnsstub(3)