.TH ASR_RUN 3 "$Mdocdate: March 26 2014 $" ""
.SH NAME
.ad l
\fB\%asr_run\fP,
\fB\%asr_run_sync\fP,
\fB\%asr_abort\fP,
\fB\%res_send_async\fP,
\fB\%res_query_async\fP,
\fB\%res_search_async\fP,
\fB\%getrrsetbyname_async\fP,
\fB\%gethostbyname_async\fP,
\fB\%gethostbyname2_async\fP,
\fB\%gethostbyaddr_async\fP,
\fB\%getnetbyname_async\fP,
\fB\%getnetbyaddr_async\fP,
\fB\%getaddrinfo_async\fP,
\fB\%getnameinfo_async\fP
\- asynchronous resolver functions
.SH SYNOPSIS
.ad l
\fB#include <sys/types.h>\fP
\fB#include <sys/socket.h>\fP
\fB#include <netdb.h>\fP
\fB#include <asr.h>\fP
.br
\fIint\fP
.br
\fB\%asr_run\fP(\fI\%struct\ asr_query\ *aq\fP, \fI\%struct\ asr_result\ *ar\fP);
.br
\fIint\fP
.br
\fB\%asr_run_sync\fP(\fI\%struct\ asr_query\ *aq\fP, \fI\%struct\ asr_result\ *ar\fP);
.br
\fIvoid\fP
.br
\fB\%asr_abort\fP(\fI\%struct\ asr_query\ *aq\fP);
.br
\fIstruct asr_query *\fP
.br
\fB\%res_send_async\fP(\fI\%const\ unsigned\ char\ *pkt\fP, \fI\%int\ pktlen\fP, \fI\%void\ *asr\fP);
.br
\fIstruct asr_query *\fP
.br
\fB\%res_query_async\fP(\fI\%const\ char\ *name\fP, \fI\%int\ class\fP, \fI\%int\ type\fP, \fI\%void\ *asr\fP);
.br
\fIstruct asr_query *\fP
.br
\fB\%res_search_async\fP(\fI\%const\ char\ *name\fP, \fI\%int\ class\fP, \fI\%int\ type\fP, \fI\%void\ *asr\fP);
.br
\fIstruct asr_query *\fP
.br
\fB\%getrrsetbyname_async\fP(\fI\%const\ char\ *hostname\fP, \fI\%unsigned\ int\ rdclass\fP, \fI\%unsigned\ int\ rdtype\fP, \fI\%unsigned\ int\ flags\fP, \fI\%void\ *asr\fP);
.br
\fIstruct asr_query *\fP
.br
\fB\%gethostbyname_async\fP(\fI\%const\ char\ *name\fP, \fI\%void\ *asr\fP);
.br
\fIstruct asr_query *\fP
.br
\fB\%gethostbyname2_async\fP(\fI\%const\ char\ *name\fP, \fI\%int\ af\fP, \fI\%void\ *asr\fP);
.br
\fIstruct asr_query *\fP
.br
\fB\%gethostbyaddr_async\fP(\fI\%const\ void\ *addr\fP, \fI\%socklen_t\ len\fP, \fI\%int\ af\fP, \fI\%void\ *asr\fP);
.br
\fIstruct asr_query *\fP
.br
\fB\%getnetbyname_async\fP(\fI\%const\ char\ *name\fP, \fI\%void\ *asr\fP);
.br
\fIstruct asr_query *\fP
.br
\fB\%getnetbyaddr_async\fP(\fI\%in_addr_t\ net\fP, \fI\%int\ type\fP, \fI\%void\ *asr\fP);
.br
\fIstruct asr_query *\fP
.br
\fB\%getaddrinfo_async\fP(\fI\%const\ char\ *hostname\fP, \fI\%const\ char\ *servname\fP, \fI\%const\ struct\ addrinfo\ *hints\fP, \fI\%void\ *asr\fP);
.br
\fIstruct asr_query *\fP
.br
\fB\%getnameinfo_async\fP(\fI\%const\ struct\ sockaddr\ *sa\fP, \fI\%socklen_t\ salen\fP, \fI\%char\ *host\fP, \fI\%size_t\ hostlen\fP, \fI\%char\ *serv\fP, \fI\%size_t\ servlen\fP, \fI\%int\ flags\fP, \fI\%void\ *asr\fP);
.SH DESCRIPTION
.ad l
The
\fB\%asr\fP
functions provide a simple interface for asynchronous address
resolution and nameserver querying.
They should be used in place of the classical resolver functions
of libc when blocking is not desirable.
.PP
The principle of operation is as follows:
All async requests are made against an
\fB\%asr\fP
context which basically defines a list of sources to query and a
strategy to do so.
The user creates a query through one of the dedicated functions, and
gets a handle representing the internal query.
A query is a state-machine that can be run to try to fulfill a
particular request.
This is done by calling in a generic API that performs the state
transitions until it needs to give the control back to the user,
either because a result is available, or because the next transition
implies a blocking call (a file descriptor needs to be read from or
written to).
The user is responsible for dealing with the situation: either get
the result, or wait until the fd conditions are met, and then call
back into the resolving machinery when it is ready to proceed.
.PP
The
\fB\%asr_run\fP()
function drives the resolving process.
It runs the asynchronous query represented by the
handle until a result is available, or until it cannot continue
without blocking.
The results are returned to the user through the
parameter, which must be a valid pointer to user allocated memory.
is defined as:
.RS 4
.nf
struct asr_result {
	/* Fields set if the query is not done yet (asr_run returns 0) */
	int	 ar_cond;	/* ASR_WANT_READ or ASR_WANT_WRITE */
	int	 ar_fd;		/* the fd waiting for io condition */
	int	 ar_timeout;	/* time to wait for in milliseconds */
	/* Error fields.  Depends on the query type. */
	int	 ar_errno;
	int	 ar_h_errno;
	int	 ar_gai_errno;
	int	 ar_rrset_errno;
	/* Result for res_*_async() calls */
	int	 ar_count;	/* number of answers in the dns reply */
	int	 ar_rcode;	/* response code in the dns reply */
	void	*ar_data;	/* raw reply packet (must be freed) */
	int	 ar_datalen;	/* reply packet length */
	struct sockaddr_storage ar_ns; /* nameserver that responded */
	/* Result for other calls. Must be freed properly. */
	struct addrinfo	 *ar_addrinfo;
	struct rrsetinfo *ar_rrsetinfo;
	struct hostent	 *ar_hostent;
	struct netent	 *ar_netent;
};
.RE
.PP
The function returns one of the following values:
.RS 5
.TP
0
The query cannot be processed further until a specific condition on a
file descriptor becomes true.
The following members of the
structure are filled:
.PP
.RS 5
.TP
one of ASR_WANT_READ or ASR_WANT_WRITE,
.TP
the file descriptor waiting for an IO operation,
.TP
the amount of time to wait for in milliseconds.
.RE
.PP
The caller is expected to call
\fB\%asr_run\fP()
again once the condition holds or the timeout expires.
.TP
1
The query is completed.
The members relevant to the actual async query type are set accordingly,
including error conditions.
In any case, the query is cleared and its handle is invalidated.
.RE
.PP
Note that although the query itself may fail (the error being properly reported
in the
structure), the
\fB\%asr_run\fP()
function itself cannot fail and it always preserves errno.
.PP
The
\fB\%asr_run_sync\fP()
function is a wrapper around
\fB\%asr_run\fP()
that handles the read/write conditions, thus falling back to a blocking
interface.
It only returns 1.
It also preserves errno.
.PP
The
\fB\%asr_abort\fP()
function clears a running query.
It can be called when the query is waiting on a file descriptor.
Note that a completed query is already cleared when
\fB\%asr_run\fP()
returns, so
\fB\%asr_abort\fP()
must not be called in this case.
.PP
The remaining functions are used to initiate different kinds of query
on the
resolver context.
The specific operational details for each of them are described below.
All functions return a handle to an internal query, or NULL if they could
not allocate the necessary resources to initiate the query.
All other errors (especially invalid parameters) are reported when calling
\fB\%asr_run\fP().
They usually have the same interface as an existing resolver function, with
an additional
\fIasr\fP
argument, which specifies the context to use for this request.
For now, the argument must always be NULL, which will use the default
context for the current thread.
.PP
The
\fB\%res_send_async\fP(),
\fB\%res_query_async\fP()
and
\fB\%res_search_async\fP()
functions are asynchronous versions of the standard libc resolver routines.
Their interface is very similar, except that the response buffer is always
allocated internally.
The return value is found upon completion in the
member of the response structure.
In addition, the
structure contains the address of the DNS server that sent the response,
contains the code returned by the server in the DNS response packet, and
contains the number of answers in the packet.
If a response is received it is placed in a newly allocated buffer
and returned as
member.
This buffer must be freed by the caller.
On error, the
and
members are set accordingly.
.PP
The
\fB\%getrrsetbyname_async\fP()
function is an asynchronous version of
\fBgetrrsetbyname\fP(3).
Upon completion, the return code is found in
and the address to the newly allocated result set is set in
.
As for the blocking function, it must be freed by calling
\fBfreerrset\fP(3).
.PP
The
\fB\%gethostbyname_async\fP(),
\fB\%gethostbyname2_async\fP()
and
\fB\%gethostbyaddr_async\fP()
functions provide an asynchronous version of the network host entry functions.
Upon completion,
\fIar_h_errno\fP
is set and the resulting hostent address, if found, is set
in the
\fIar_hostent\fP
field.
Note that unlike their blocking counterparts, these functions always return a
pointer to newly allocated memory, which must be released by the caller using
\fBfree\fP(3).
.PP
Similarly, the
\fB\%getnetbyname_async\fP()
and
\fB\%getnetbyaddr_async\fP()
functions provide an asynchronous version of the network entry functions.
Upon completion,
\fIar_h_errno\fP
is set and the resulting netent address, if found, is set
in the
\fIar_netent\fP
field.
The memory there is also allocated for the request, and it must be freed by
\fBfree\fP(3).
.PP
The
\fB\%getaddrinfo_async\fP()
function is an asynchronous version of the
\fBgetaddrinfo\fP(3)
call.
It provides a chain of addrinfo structures with all valid combinations of
socket address for the given
,
and
.
Those three parameters have the same meaning as for the blocking counterpart.
Upon completion the return code is set in
.
The
member may also be set.
On success, the
member points to a newly allocated list of addrinfo.
This list must be freed with
\fBfreeaddrinfo\fP(3).
.SH WORKING WITH THREADS
.ad l
This implementation of the asynchronous resolver interface is thread-safe
and lock-free internally, but the following restriction applies:
Two different threads must not create queries on the same context or
run queries originating from the same context at the same time.
If they want to do that, all calls must be protected by a mutex around
that context.
.PP
It is generally not a problem since the main point of the asynchronous
resolver is to multiplex queries within a single thread of control,
so sharing a resolver among threads is not useful.
.SH SEE ALSO
.ad l
\fBgetaddrinfo\fP(3),
\fBgethostbyname\fP(3),
\fBgetnameinfo\fP(3),
\fBgetnetbyname\fP(3),
\fBgetrrsetbyname\fP(3),
\fBres_send\fP(3),
\fBresolv.conf\fP(5)
.SH CAVEATS
.ad l
This DNS resolver implementation doesn't support
the EDNS0 protocol extension yet.