|
jpayne@68
|
1 .\"
|
|
jpayne@68
|
2 .\" Copyright 1998 by the Massachusetts Institute of Technology.
|
|
jpayne@68
|
3 .\" SPDX-License-Identifier: MIT
|
|
jpayne@68
|
4 .\"
|
|
jpayne@68
|
5 .TH ARES_SEARCH 3 "24 July 1998"
|
|
jpayne@68
|
6 .SH NAME
|
|
jpayne@68
|
7 ares_search \- Initiate a DNS query with domain search
|
|
jpayne@68
|
8 .SH SYNOPSIS
|
|
jpayne@68
|
9 .nf
|
|
jpayne@68
|
10 #include <ares.h>
|
|
jpayne@68
|
11
|
|
jpayne@68
|
12 typedef void (*ares_callback_dnsrec)(void *\fIarg\fP,
|
|
jpayne@68
|
13 ares_status_t \fIstatus\fP,
|
|
jpayne@68
|
14 size_t \fItimeouts\fP,
|
|
jpayne@68
|
15 const ares_dns_record_t *\fIdnsrec\fP);
|
|
jpayne@68
|
16
|
|
jpayne@68
|
17 void ares_search_dnsrec(ares_channel_t *\fIchannel\fP,
|
|
jpayne@68
|
18 const ares_dns_record_t *\fIdnsrec\fP,
|
|
jpayne@68
|
19 ares_callback_dnsrec \fIcallback\fP, void *\fIarg\fP);
|
|
jpayne@68
|
20
|
|
jpayne@68
|
21 typedef void (*ares_callback)(void *\fIarg\fP, int \fIstatus\fP,
|
|
jpayne@68
|
22 int \fItimeouts\fP, unsigned char *\fIabuf\fP,
|
|
jpayne@68
|
23 int \fIalen\fP);
|
|
jpayne@68
|
24
|
|
jpayne@68
|
25 void ares_search(ares_channel_t *\fIchannel\fP, const char *\fIname\fP,
|
|
jpayne@68
|
26 int \fIdnsclass\fP, int \fItype\fP,
|
|
jpayne@68
|
27 ares_callback \fIcallback\fP, void *\fIarg\fP);
|
|
jpayne@68
|
28
|
|
jpayne@68
|
29 .fi
|
|
jpayne@68
|
30 .SH DESCRIPTION
|
|
jpayne@68
|
31 The
|
|
jpayne@68
|
32 .B ares_search
|
|
jpayne@68
|
33 function initiates a series of single-question DNS queries on the name
|
|
jpayne@68
|
34 service channel identified by
|
|
jpayne@68
|
35 .IR channel ,
|
|
jpayne@68
|
36 using the channel's search domains as well as a host alias file given
|
|
jpayne@68
|
37 by the HOSTALIAS environment variable. The parameter
|
|
jpayne@68
|
38 .I name
|
|
jpayne@68
|
39 gives the alias name or the base of the query name as a NUL-terminated
|
|
jpayne@68
|
40 C string of period-separated labels; if it ends with a period, the
|
|
jpayne@68
|
41 channel's search domains will not be used. Periods and backslashes
|
|
jpayne@68
|
42 within a label must be escaped with a backslash. The parameters
|
|
jpayne@68
|
43 .I dnsclass
|
|
jpayne@68
|
44 and
|
|
jpayne@68
|
45 .I type
|
|
jpayne@68
|
46 give the class and type of the query using the values defined in
|
|
jpayne@68
|
47 .BR <arpa/nameser.h> .
|
|
jpayne@68
|
48 When the query sequence is complete or has failed, the ares library
|
|
jpayne@68
|
49 will invoke
|
|
jpayne@68
|
50 .IR callback .
|
|
jpayne@68
|
51 Completion or failure of the query sequence may happen immediately, or
|
|
jpayne@68
|
52 may happen during a later call to
|
|
jpayne@68
|
53 .BR ares_process (3)
|
|
jpayne@68
|
54 or
|
|
jpayne@68
|
55 .BR ares_destroy (3).
|
|
jpayne@68
|
56 .PP
|
|
jpayne@68
|
57 If this is called from a thread other than which the main program event loop is
|
|
jpayne@68
|
58 running, care needs to be taken to ensure any file descriptor lists are updated
|
|
jpayne@68
|
59 immediately within the eventloop. When the associated callback is called,
|
|
jpayne@68
|
60 it is called with a channel lock so care must be taken to ensure any processing
|
|
jpayne@68
|
61 is minimal to prevent DNS channel stalls.
|
|
jpayne@68
|
62 .PP
|
|
jpayne@68
|
63 The callback argument
|
|
jpayne@68
|
64 .I arg
|
|
jpayne@68
|
65 is copied from the
|
|
jpayne@68
|
66 .B ares_search
|
|
jpayne@68
|
67 argument
|
|
jpayne@68
|
68 .IR arg .
|
|
jpayne@68
|
69 The callback argument
|
|
jpayne@68
|
70 .I status
|
|
jpayne@68
|
71 indicates whether the query sequence ended with a successful query
|
|
jpayne@68
|
72 and, if not, how the query sequence failed. It may have any of the
|
|
jpayne@68
|
73 following values:
|
|
jpayne@68
|
74 .TP 19
|
|
jpayne@68
|
75 .B ARES_SUCCESS
|
|
jpayne@68
|
76 A query completed successfully.
|
|
jpayne@68
|
77 .TP 19
|
|
jpayne@68
|
78 .B ARES_ENODATA
|
|
jpayne@68
|
79 No query completed successfully; when the query was tried without a
|
|
jpayne@68
|
80 search domain appended, a response was returned with no answers.
|
|
jpayne@68
|
81 .TP 19
|
|
jpayne@68
|
82 .B ARES_EFORMERR
|
|
jpayne@68
|
83 A query completed but the server claimed that the query was
|
|
jpayne@68
|
84 malformatted.
|
|
jpayne@68
|
85 .TP 19
|
|
jpayne@68
|
86 .B ARES_ESERVFAIL
|
|
jpayne@68
|
87 No query completed successfully; when the query was tried without a
|
|
jpayne@68
|
88 search domain appended, the server claimed to have experienced a
|
|
jpayne@68
|
89 failure. (This code can only occur if the
|
|
jpayne@68
|
90 .B ARES_FLAG_NOCHECKRESP
|
|
jpayne@68
|
91 flag was specified at channel initialization time; otherwise, such
|
|
jpayne@68
|
92 responses are ignored at the
|
|
jpayne@68
|
93 .BR ares_send (3)
|
|
jpayne@68
|
94 level.)
|
|
jpayne@68
|
95 .TP 19
|
|
jpayne@68
|
96 .B ARES_ENOTFOUND
|
|
jpayne@68
|
97 No query completed successfully; when the query was tried without a
|
|
jpayne@68
|
98 search domain appended, the server reported that the queried-for
|
|
jpayne@68
|
99 domain name was not found.
|
|
jpayne@68
|
100 .TP 19
|
|
jpayne@68
|
101 .B ARES_ENOTIMP
|
|
jpayne@68
|
102 A query completed but the server does not implement the operation
|
|
jpayne@68
|
103 requested by the query. (This code can only occur if the
|
|
jpayne@68
|
104 .B ARES_FLAG_NOCHECKRESP
|
|
jpayne@68
|
105 flag was specified at channel initialization time; otherwise, such
|
|
jpayne@68
|
106 responses are ignored at the
|
|
jpayne@68
|
107 .BR ares_send (3)
|
|
jpayne@68
|
108 level.)
|
|
jpayne@68
|
109 .TP 19
|
|
jpayne@68
|
110 .B ARES_EREFUSED
|
|
jpayne@68
|
111 A query completed but the server refused the query. (This code can
|
|
jpayne@68
|
112 only occur returned if the
|
|
jpayne@68
|
113 .B ARES_FLAG_NOCHECKRESP
|
|
jpayne@68
|
114 flag was specified at channel initialization time; otherwise, such
|
|
jpayne@68
|
115 responses are ignored at the
|
|
jpayne@68
|
116 .BR ares_send (3)
|
|
jpayne@68
|
117 level.)
|
|
jpayne@68
|
118 .TP 19
|
|
jpayne@68
|
119 .B ARES_TIMEOUT
|
|
jpayne@68
|
120 No name servers responded to a query within the timeout period.
|
|
jpayne@68
|
121 .TP 19
|
|
jpayne@68
|
122 .B ARES_ECONNREFUSED
|
|
jpayne@68
|
123 No name servers could be contacted.
|
|
jpayne@68
|
124 .TP 19
|
|
jpayne@68
|
125 .B ARES_ENOMEM
|
|
jpayne@68
|
126 Memory was exhausted.
|
|
jpayne@68
|
127 .TP 19
|
|
jpayne@68
|
128 .B ARES_ECANCELLED
|
|
jpayne@68
|
129 The query was cancelled.
|
|
jpayne@68
|
130 .TP 19
|
|
jpayne@68
|
131 .B ARES_EDESTRUCTION
|
|
jpayne@68
|
132 The name service channel
|
|
jpayne@68
|
133 .I channel
|
|
jpayne@68
|
134 is being destroyed; the query will not be completed.
|
|
jpayne@68
|
135 .TP 19
|
|
jpayne@68
|
136 .B ARES_ENOSERVER
|
|
jpayne@68
|
137 No query completed successfully; no DNS servers were configured on the channel.
|
|
jpayne@68
|
138 .PP
|
|
jpayne@68
|
139 The callback argument
|
|
jpayne@68
|
140 .I timeouts
|
|
jpayne@68
|
141 reports how many times a query timed out during the execution of the
|
|
jpayne@68
|
142 given request.
|
|
jpayne@68
|
143 .PP
|
|
jpayne@68
|
144 If a query completed successfully, the callback argument
|
|
jpayne@68
|
145 .I abuf
|
|
jpayne@68
|
146 points to a result buffer of length
|
|
jpayne@68
|
147 .IR alen .
|
|
jpayne@68
|
148 If the query did not complete successfully,
|
|
jpayne@68
|
149 .I abuf
|
|
jpayne@68
|
150 will usually be NULL and
|
|
jpayne@68
|
151 .I alen
|
|
jpayne@68
|
152 will usually be 0, but in some cases an unsuccessful query result may
|
|
jpayne@68
|
153 be placed in
|
|
jpayne@68
|
154 .IR abuf .
|
|
jpayne@68
|
155
|
|
jpayne@68
|
156 The \fIares_search_dnsrec(3)\fP function behaves identically to
|
|
jpayne@68
|
157 \fIares_search(3)\fP, but takes an initialized and filled DNS record object to
|
|
jpayne@68
|
158 use for queries as the second argument
|
|
jpayne@68
|
159 .I dnsrec
|
|
jpayne@68
|
160 instead of a name, class and type. This object is used as the base for the
|
|
jpayne@68
|
161 queries and must itself represent a valid query for a single name. Note that
|
|
jpayne@68
|
162 the search domains will only be appended to the name in the question section;
|
|
jpayne@68
|
163 RRs on the DNS record object will not be affected. Moreover, the
|
|
jpayne@68
|
164 .I callback
|
|
jpayne@68
|
165 argument is of type \fIares_callback_dnsrec\fP. This callback behaves
|
|
jpayne@68
|
166 identically to \fIares_callback\fP, but is invoked with a parsed DNS record
|
|
jpayne@68
|
167 object
|
|
jpayne@68
|
168 .I dnsrec
|
|
jpayne@68
|
169 rather than a raw buffer with length. Note that this object is read-only.
|
|
jpayne@68
|
170
|
|
jpayne@68
|
171 The \fIares_search_dnsrec(3)\fP function returns an \fIares_status_t\fP response
|
|
jpayne@68
|
172 code. This may be useful to know that the query was enqueued properly. The
|
|
jpayne@68
|
173 response code does not reflect the result of the query, just the result of the
|
|
jpayne@68
|
174 enqueuing of the query.
|
|
jpayne@68
|
175
|
|
jpayne@68
|
176 .SH AVAILABILITY
|
|
jpayne@68
|
177 \fBares_search_dnsrec(3)\fP was introduced in c-ares 1.28.0.
|
|
jpayne@68
|
178
|
|
jpayne@68
|
179 .SH SEE ALSO
|
|
jpayne@68
|
180 .BR ares_process (3),
|
|
jpayne@68
|
181 .BR ares_dns_record (3)
|
