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