ares_search(3)

ARES_SEARCH(3)         C LIBRARY FUNCTIONS         ARES_SEARCH(3)

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

     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

                    Last change: 24 July 1998                   1

ARES_SEARCH(3)         C LIBRARY FUNCTIONS         ARES_SEARCH(3)

                        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;  other-
                        wise,  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 initializa-
                        tion 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 com-
                        pleted.

     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.

                    Last change: 24 July 1998                   2