NAME

       ares_send - Initiate a DNS query

SYNOPSIS

       #include <ares.h>

       typedef void (*ares_callback)(void *arg, int status,
                                     int timeouts, unsigned char *abuf,
                                     int alen)

       void ares_send(ares_channel_t *channel, const unsigned char *qbuf,
                      int qlen, ares_callback callback, void *arg)

DESCRIPTION

       The  ares_send  function  initiates  a DNS query on the name service channel identified by
       channel.  The parameters qbuf and qlen give the DNS query, which should already have  been
       formatted  according  to  the DNS protocol.  When the query is complete or has failed, the
       ares library will invoke  callback.   Completion  or  failure  of  the  query  may  happen
       immediately, or may happen later as network events are processed.

       When  the  associated callback is called, it is called with a channel lock so care must be
       taken to ensure any processing is minimal to prevent DNS channel stalls.

       The callback may  be  triggered  from  a  different  thread  than  the  one  which  called
       ares_send(3).

       For  integrators  running  their own event loops and not using ARES_OPT_EVENT_THREAD, care
       needs to be taken to ensure any file descriptor lists are updated immediately  within  the
       eventloop when notified.

       The  callback  argument  arg  is  copied  from  the  ares_send argument arg.  The callback
       argument status indicates whether the query succeeded and, if not, how it failed.  It  may
       have any of the following values:

       ARES_SUCCESS       The query completed.

       ARES_EBADQUERY     The  query  buffer  was  poorly  formed  (was not long enough for a DNS
                          header or was too long for TCP transmission).

       ARES_ETIMEOUT      No name servers responded within the timeout period.

       ARES_ECONNREFUSED  No name servers could be contacted.

       ARES_ENOMEM        Memory was exhausted.

       ARES_ECANCELLED    The query was cancelled.

       ARES_EDESTRUCTION  The name service channel channel is being destroyed; the query will not
                          be completed.

       ARES_ENOSERVER     The  query will not be completed because no DNS servers were configured
                          on the channel.

       The callback argument timeouts reports how  many  times  a  query  timed  out  during  the
       execution of the given request.

       If  the  query  completed,  the callback argument abuf points to a result buffer of length
       alen.  If the query did not complete, abuf will be NULL and alen will be 0.

       Unless the flag ARES_FLAG_NOCHECKRESP was set at channel  initialization  time,  ares_send
       will normally ignore responses whose questions do not match the questions in qbuf, as well
       as responses with reply codes of  SERVFAIL,  NOTIMP,  and  REFUSED.   Unlike  other  query
       functions in the ares library, however, ares_send does not inspect the header of the reply
       packet to determine the error status, so  a  callback  status  of  ARES_SUCCESS  does  not
       reflect as much about the response as for other query functions.

SEE ALSO

       ares_process(3), ares_dns_record(3)

AUTHOR

       Greg Hudson, MIT Information Systems
       Copyright 1998 by the Massachusetts Institute of Technology.

                                           25 July 1998                              ARES_SEND(3)