NAME
ares_search - Initiate a DNS query with domain search
SYNOPSIS
typedef void (*ares_callback)(void *arg, int status,
unsigned char *abuf, int alen)
void ares_search(ares_channel channel, const char *name,
int dnsclass, int type, ares_callback callback,
void *arg)
DESCRIPTION
The
ares_search
function initiates a series of single-question DNS queries on the name
service channel identified by
R channel ,
using the channel's search domains as well as a host alias file given
by the HOSTALIAS environment variable. The parameter
name
gives the alias name or the base of the query name as a NUL-terminated
C string of period-separated labels; if it ends with a period, the
channel's search domains will not be used. Periods and backslashes
within a label must be escaped with a backslash. The parameters
dnsclass
and
type
give the class and type of the query using the values defined in
R <arpa/nameser.h> .
When the query sequence is complete or has failed, the ares library
will invoke
R callback .
Completion or failure of the query sequence may happen immediately, or
may happen during a later call to
ares_process(3)
or
ares_destroy(3).
The callback argument
arg
is copied from the
ares_search
argument
R arg .
The callback argument
status
indicates whether the query sequence ended with a successful query
and, if not, how the query sequence failed. It may have any of the
following values:
ARES_SUCCESS
A query completed successfully.
ARES_ENODATA
No query completed successfully; when the query was tried without a
search domain appended, a response was returned with no answers.
ARES_EFORMERR
A query completed but the server claimed that the query was
malformatted.
ARES_ESERVFAIL
No query completed successfully; when the query was tried without a
search domain appended, the server claimed to have experienced a
failure. (This code can only occur if the
ARES_FLAG_NOCHECKRESP
flag was specified at channel initialization time; otherwise, such
responses are ignored at the
ares_send(3)
level.)
ARES_ENOTFOUND
No query completed successfully; when the query was tried without a
search domain appended, the server reported that the queried-for
domain name was not found.
ARES_ENOTIMP
A query completed but the server does not implement the operation
requested by the query. (This code can only occur if the
ARES_FLAG_NOCHECKRESP
flag was specified at channel initialization time; otherwise, such
responses are ignored at the
ares_send(3)
level.)
ARES_EREFUSED
A query completed but the server refused the query. (This code can
only occur returned if the
ARES_FLAG_NOCHECKRESP
flag was specified at channel initialization time; otherwise, such
responses are ignored at the
ares_send(3)
level.)
ARES_TIMEOUT
No name servers responded to a query within the timeout period.
ARES_ECONNREFUSED
No name servers could be contacted.
ARES_ENOMEM
Memory was exhausted.
ARES_EDESTRUCTION
The name service channel
channel
is being destroyed; the query will not be completed.
If a query completed successfully, the callback argument
abuf
points to a result buffer of length
R alen .
If the query did not complete successfully,
abuf
will usually be NULL and
alen
will usually be 0, but in some cases an unsuccessful query result may
be placed in
R abuf .
SEE ALSO
AUTHOR
Greg Hudson, MIT Information Systems
Copyright 1998 by the Massachusetts Institute of Technology.
