ares_search.txt

RTL-lwIP is the porting of the lwIP TCP/IP stack to RTLinux-GPL.The focus of the RTL-lwIP stack is

ARES_SEARCH(3)                                                  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,
       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_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 alen.  If the query did not complete success-
       fully,  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)