NAME

       ares_search - Initiate a DNS query with domain search

SYNOPSIS

       #include <ares.h>

       typedef void (*ares_callback)(void *arg, int status,
       int timeouts, 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 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
       <arpa/nameser.h>.  When the query sequence is complete or has  failed,  the  ares  library
       will invoke 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  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_ECANCELLED    The query was cancelled.

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

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

       If a query completed successfully, the callback argument abuf points to a result buffer of
       length  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
       abuf.

SEE ALSO

       ares_process(3)

AUTHOR

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

                                           24 July 1998                            ARES_SEARCH(3)