1ARES_SEARCH(3)             Library Functions Manual             ARES_SEARCH(3)
2
3
4

NAME

6       ares_search - Initiate a DNS query with domain search
7

SYNOPSIS

9       #include <ares.h>
10
11       typedef void (*ares_callback)(void *arg, int status,
12       int timeouts, unsigned char *abuf, int alen)
13
14       void ares_search(ares_channel channel, const char *name,
15            int dnsclass, int type, ares_callback callback,
16       void *arg)
17

DESCRIPTION

19       The  ares_search  function  initiates  a  series of single-question DNS
20       queries on the name service channel identified by  channel,  using  the
21       channel's  search  domains  as  well  as a host alias file given by the
22       HOSTALIAS environment variable.  The parameter  name  gives  the  alias
23       name  or  the  base  of  the query name as a NUL-terminated C string of
24       period-separated labels; if it ends with a period, the channel's search
25       domains  will not be used.  Periods and backslashes within a label must
26       be escaped with a backslash.  The parameters dnsclass and type give the
27       class   and   type   of   the   query   using  the  values  defined  in
28       <arpa/nameser.h>.  When the query sequence is complete or  has  failed,
29       the  ares  library  will invoke callback.  Completion or failure of the
30       query sequence may happen immediately, or may  happen  during  a  later
31       call to ares_process(3) or ares_destroy(3).
32
33       The  callback argument arg is copied from the ares_search argument arg.
34       The callback argument status indicates whether the query sequence ended
35       with a successful query and, if not, how the query sequence failed.  It
36       may have any of the following values:
37
38       ARES_SUCCESS       A query completed successfully.
39
40       ARES_ENODATA       No query completed successfully; when the query  was
41                          tried  without  a search domain appended, a response
42                          was returned with no answers.
43
44       ARES_EFORMERR      A query completed but the server  claimed  that  the
45                          query was malformatted.
46
47       ARES_ESERVFAIL     No  query completed successfully; when the query was
48                          tried without a search domain appended,  the  server
49                          claimed  to  have experienced a failure.  (This code
50                          can only occur if the ARES_FLAG_NOCHECKRESP flag was
51                          specified at channel initialization time; otherwise,
52                          such  responses  are  ignored  at  the  ares_send(3)
53                          level.)
54
55       ARES_ENOTFOUND     No  query completed successfully; when the query was
56                          tried without a search domain appended,  the  server
57                          reported  that  the  queried-for domain name was not
58                          found.
59
60       ARES_ENOTIMP       A query completed but the server does not  implement
61                          the  operation  requested  by the query.  (This code
62                          can only occur if the ARES_FLAG_NOCHECKRESP flag was
63                          specified at channel initialization time; otherwise,
64                          such  responses  are  ignored  at  the  ares_send(3)
65                          level.)
66
67       ARES_EREFUSED      A  query completed but the server refused the query.
68                          (This  code  can  only   occur   returned   if   the
69                          ARES_FLAG_NOCHECKRESP  flag was specified at channel
70                          initialization time; otherwise, such  responses  are
71                          ignored at the ares_send(3) level.)
72
73       ARES_TIMEOUT       No  name  servers  responded  to  a query within the
74                          timeout period.
75
76       ARES_ECONNREFUSED  No name servers could be contacted.
77
78       ARES_ENOMEM        Memory was exhausted.
79
80       ARES_EDESTRUCTION  The name service channel channel is being destroyed;
81                          the query will not be completed.
82
83       The callback argument timeouts reports how many times a query timed out
84       during the execution of the given request.
85
86       If a query completed successfully, the callback argument abuf points to
87       a result buffer of length alen.  If the query did not complete success‐
88       fully, abuf will usually be NULL and alen will usually  be  0,  but  in
89       some cases an unsuccessful query result may be placed in abuf.
90

SEE ALSO

92       ares_process(3)
93

AUTHOR

95       Greg Hudson, MIT Information Systems
96       Copyright 1998 by the Massachusetts Institute of Technology.
97
98
99
100                                 24 July 1998                   ARES_SEARCH(3)
Impressum