ares_send(3)

ARES_SEND(3)           C LIBRARY FUNCTIONS           ARES_SEND(3)

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

     void ares_send(ares_channel channel, const unsigned char
          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  call-
     back.  Completion or failure of the query may happen immedi-
     ately, or may happen during a later call to  ares_process(3)
     or ares_destroy(3).

     The callback argument arg is copied from the ares_send argu-
     ment  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 com-
                        pleted.

     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 com-
     plete, abuf will be NULL and alen will be 0.

                    Last change: 25 July 1998                   1

ARES_SEND(3)           C LIBRARY FUNCTIONS           ARES_SEND(3)

     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)

AUTHOR

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

                    Last change: 25 July 1998                   2