.TH qlibs: dnsstub
.SH NAME
dns \- stub resolver 
.SH SYNTAX
.B #include \(dqdnsresolv.h\(dq

int \fBdns_resolvconfip\fP(char \fIservers\fR[512],uint32 \fIscope\fR[32]);

int \fBdns_transmit_start\fP(struct dns_transmit *\fIq\fR,const char \fIservers\fR[512],
    int \fIflagrecursive\fR,const char *\fIq\fR,const char \fIqtype\fR[2],
    const char \fIlocalip\fR[16]); 
.br
int \fBdns_transmit_start6\fP(struct dns_transmit *\fIq\fR,const char \fIservers\fR[512],
    int \fIflagrecursive\fR,const char *\fIq\fR,const char \fIqtype\fR[2], 
    const char \fIlocalip\fR[16],const uint32 \fIscopes\fR[32]); 

int \fBdns_sortip4\fP(char *\fIservers\fR,unsigned int \fIn\fR);
.br
int \fBdns_sortip6\fP(char *\fIservers\fR,unsigned int \fIn\fR);
.SH DESCRIPTION
.B dns_resolvconfip
reads the name servers defined in
.I /etc/resolv.conf
and uses
.B ip6_ifscan
to fetch their IPv4/IPv6 addresses together with the scope for the LLU address.
Up to 
.I 32
name servers can be specified.

Apart from the system-wide
.I /etc/resolv.conf
the IP addresses of name servers can preferrably be provided by means of the
environment variable
.I $DNSCACHEIP 
for each user application. The variable
.I $DNSCACHEIP
may include up to 32 name server IP addresses separated by white spaces:

.EX
  DNSCACHEIP="10.0.1.53 fe80::1%lo0 ::1"
.EE

.B dns_transmit_start
and 
.B dns_transmit_start6
use the list of name server IP's for a recursive or none-recursive 
query 
.I q
of type
.I qtype
starting from IP address
.I localip
for which the 
.I struct dns_transmit
provides the required  book keeping information.
.B dns_transmit_start6
additionally is able to evaluate the given
.I scope_id
as information for the local interface in order 
to bind to the remote IPv6 LLU addresses. Usually 
.I scope_id
defaults to
.IR 0 .

.B dns_sortip4
and
.B dns_sortip6
randomize the list of name server IPs upon call and as result the first address
is used to facilitate the name lookup.
.IR FQDN .
.SH "RETURN CODES"
Different from the original djb implemtation, the 
following return code scheme is used:
.TP 2
rc > 0
A 'positive' answer is given, thus results returned.
.TP 2
rc = 0
A 'neutral' answer was provided, thus typically the
operation succeeded, but without replies.
.TP 2
rc < 0
An operational error was encountered. 
.TP 0
Potentially, this needs to be treated specifically:
.TP 2
DNS_INT (rc = -4)
Internal DNS operational error; ie. resources were not
available.
.TP 2
DNS_COM (rc = -3)
DNS communication error.
.TP 2
DNS_ERR (rc = -2)
Parsing errors and others.
.TP 2
DNS_MEM (rc = -1)
Memory error occured.
.TP 0
A 'safe' usage of return codes thus checks not only the presence 
of a return code, but rather additionally its sign.
Negative return codes point to errors.
.SH "SEE ALSO"
http://cr.yp.to/djbdns/qualify.html,
dns(3), 
ip4(3), 
ip6(3), 
socket_if(3)