.TH libar 3
.SH NAME
.B ar_init(), ar_addquery(), ar_waitreply(), ar_cancelquery(), ar_resend(),
.B ar_recycle(), ar_shutdown()
-- asynchronous DNS resolver facility
.SH SYNOPSIS
#include
.I <ar.h>

typedef void *
.B ar_malloc_t
(void *, size_t);

typedef void
.B ar_free_t
(void *, void *);

AR_LIB
.B ar_init
(ar_malloc_t
.B mallocf,
ar_free_t
.B freef,
void *
.B memclosure,
int
.B flags
);

int
.B ar_shutdown
(AR_LIB
.B lib
);

void
.B ar_setretry
(AR_LIB
.B lib,
struct timeval *
.B new,
struct timeval *
.B old
);

void
.B ar_setmaxretry
(AR_LIB
.B lib,
int
.B new,
int *
.B old);

AR_QUERY
.B ar_addquery
(AR_LIB
.B lib,
const char *
.B query,
int
.B class,
int
.B type,
int
.B depth,
unsigned char *
.B buf,
size_t
.B buflen,
int *
.B err,
struct timeval *
.B timeout
);

int
.B ar_waitreply
(AR_LIB
.B lib,
AR_QUERY
.B query,
int *
.B len,
struct timeval *
.B timeout
);

int
.B ar_cancelquery
(AR_LIB
.B lib,
AR_QUERY
.B query
);

void
.B ar_recycle
(AR_LIB
.B lib,
AR_QUERY
.B query
);

int
.B ar_resend
(AR_LIB
.B lib,
AR_QUERY
.B query
);

char *
.B ar_strerror
(int
.B err
);
.SH DESCRIPTION
These functions are an interface to an asynchronous resolver facility.
The functions provided by
.B resolver(3)
and the
.B gethostbyxxx(3)
functions are not thread-safe since they use static storage, don't multiplex
efficiently, and don't have timeouts associated with them.  This library
of functions was drafted to provide those facilities.

An application first initializes the package by calling
.B ar_init().
The optional
.I mallocf
parameter is a caller-provided memory allocation function taking a pointer
to a caller-provided opaque data structure (the
.I memclosure
parameter) and a number of bytes to allocate.  If
.I mallocf
is not provided, the default system memory allocator function
.B malloc(3)
is used.  The optional
.I freef
parameter specifies a matching caller-provided memory deallocator function,
taking a pointer to a caller-provided opaque data structure (the
.I memclosure
parameter) and a pointer to the memory to be released.  If
.I freef
is not provided, the default system memory release function
.B free(3)
is used.  The
.I flags
parameter is a bitwise OR of a set of available flags to tailor the operation
of the package.  Currently the only flag is AR_FLAG_USETCP, which instructs
the package to submit its queries via a TCP connection rather than the
default, UDP.  The handle returned by
.B ar_init()
is passed to later functions in order to share resources among transactions.

By default the package will not retransmit queries for which no reply
has arrived until requested to do so with
.B ar_resend().
Moreover, that function re-uses the same nameserver as the previous
attempt.  Instead, the caller can use
.B ar_setretry()
to define (or retrieve) a time interval after which, if no reply has been
received, the query will be re-sent to the next nameserver in the list
of nameservers.  In the TCP case, this will disconnect from the nameserver,
reconnect, and re-send all pending queries.  A time of {0, 0} disables this
feature.  The default is the same as whatever the local resolver uses.
To leave the current value unchanged, specify a value of NULL for
.I new.
If the current value is not of interest, specify a value of NULL for
.I old.

The
.B ar_setmaxretry()
function gets and/or sets the maximum number of times a query can be
attempted before the package will give up trying.  The default is
the same as whatever the local resolver uses.  To retrieve the current
value but leave it unchanged, specify a value of -1 for
.I new.
If the current value is not of interest, specify a value of NULL for
.I old.

To submit a new query to the nameserver, the application calls
.B ar_addquery().
The
.I lib
parameter is the handle returned from
.B ar_init().
The
.I query,
.I class
and
.I type
parameters specify the query that is to be performed.
.I buf
specifies where the result should be written when a reply is received, and
.I buflen
indicates how many bytes are available there.
.I err
is an optional pointer to an integer which will receive the value of
.I errno
if there is a transmission error between this package and the nameserver.
.I depth
indicates how many CNAME references will be re-queried before the package
gives up and returns whatever result is current.
Finally,
.I timeout
is an optional pointer to a timeval structure that indicates the total time
allowed for this query to resolve.  If NULL, this query never times out.

To wait for a query result, the application calls
.B ar_waitreply().
.I lib
is again the library handle as returned by
.B ar_init().
.I query
is the query handle returned by
.B ar_addquery().
.I len
is a pointer to an integer which will receive the number of bytes that were
contained in the reply.  It can be NULL if that information is not of
interest to the caller.  This number may be larger than the value of
.I buflen
in the call to
.B ar_addquery(),
in which case there was not enough space in the provided buffer to receive
the reply and the application should resubmit with a bigger buffer.
.I timeout
specifies how long this particular call should wait for a reply before
returning.  If the reply has already arrived (even if it's an NXDOMAIN
reply), this function will return immediately, otherwise it will wait until
either the requested timeout expires, or the timeout set on the
.B ar_addquery()
call expires.

When a reply has been retrieved, the query handle needs to be recycled
via a call to
.B ar_recycle().

To abort a query, use
.B ar_cancelquery().
This implicitly recycles the
.I query
handle passed to it.

To arrange to re-send a query for which a reply has not yet arrived, use
.B ar_resend().

When all queries are done and the facility is no longer desired,
a call to
.B ar_shutdown()
will close down the service and release related resources.

The function
.B ar_strerror()
is provided to handle error codes returned by the library.  Positive error
codes are standard POSIX error codes and will be passed to
.I strerror(3)
while negative error codes are internal to the library and will be translated
to a human-readable form by this function.
.SH RETURN VALUES
.B ar_lib()
returns a handle to a newly-initialized instantiation of the library.
If operating in TCP mode, a TCP connection now exists to a nameserver.
NULL is returned if any of this initialization fails, with
.I errno
set to indicate the error.

.B ar_shutdown()
returns 0 on success, or an
.I errno
value on failure.

.B ar_addquery()
returns a newly-initialized
.I AR_QUERY
handle on success, or NULL on failure with
.I errno
set to indicate the error.  EINVAL will be used if the query submitted
was malformed (i.e. contained invalid characters or character sequences).

.B ar_cancelquery()
returns 0 on success or 1 on error (i.e. invalid query handle specified).

.B ar_waitreply()
returns AR_STAT_SUCCESS (0) on success, indicating a reply is available for
processing; AR_STAT_NOREPLY (1) if a timeout is specified on the call but
expired, indicating no reply is available yet but there might be one later;
AR_STAT_EXPIRED (2) if the timeout specified on the call to
.B ar_addquery()
has expired; or AR_STAT_ERROR (-1) on error with
.I errno
set to indicate the error.

.B ar_resend()
returns 0 on success or -1 on error with
.I errno
set to indicate the error.
.SH NOTES
This system uses
.B pthreads
for synchronization and signalling.  Applications that use another threading
mechanism may not work with this library.

If operating in TCP mode and the remote nameserver disconnects, the library
will attempt to connect to each of the nameservers published in
.I resolv.conf(4)
before giving up.  Once it gives up, all pending and future calls to
.B ar_waitreply()
or
.B ar_addquery()
will fail.  The only option after that is to shut down the library
and start again.

CNAME recursion is done at most
.I depth
times while evaluating the result of a query.  The time specified in the
call to
.B ar_addquery()
should allow for recursion time, since that defines the total amount of 
time the entire query, including recursion, is allowed to take.

The buffer provided in the call to
.B ar_addquery()
is sometimes used for temporary storage, specifically when chasing CNAME
references.  If a particular CNAME recursion is too large for the buffer,
the search will be interrupted and returned as-is, and the
.I len
value returned will indicate that a lack of buffer space caused the
recursion to terminate (see above).

.B ar_strerror()
returns a pointer to a character string representing the supplied error
code.
.SH COPYRIGHT
Copyright (c) 2004, 2005, Sendmail, Inc. and its suppliers.
All rights reserved.
.SH SEE ALSO
gethostbyaddr(3),
gethostbyname(3),
resolv.conf(4),
resolver(3)