1ASR_RUN(3) Library Functions Manual ASR_RUN(3)
2
6 asr_run, asr_run_sync, asr_abort, res_send_async, res_query_async,
7 res_search_async, getrrsetbyname_async, gethostbyname_async,
8 gethostbyname2_async, gethostbyaddr_async, getnetbyname_async,
9 getnetbyaddr_async, getaddrinfo_async, getnameinfo_async - asynchronous
10 resolver functions
11
13 #include <sys/types.h> #include <sys/socket.h> #include <netdb.h>
14 #include <asr.h>
15 int
16 asr_run(struct asr_query *aq, struct asr_result *ar);
17 int
18 asr_run_sync(struct asr_query *aq, struct asr_result *ar);
19 void
20 asr_abort(struct asr_query *aq);
21 struct asr_query *
22 res_send_async(const unsigned char *pkt, int pktlen, void *asr);
23 struct asr_query *
24 res_query_async(const char *name, int class, int type, void *asr);
25 struct asr_query *
26 res_search_async(const char *name, int class, int type, void *asr);
27 struct asr_query *
28 getrrsetbyname_async(const char *hostname, unsigned int rdclass,
29 unsigned int rdtype, unsigned int flags, void *asr);
30 struct asr_query *
31 gethostbyname_async(const char *name, void *asr);
32 struct asr_query *
33 gethostbyname2_async(const char *name, int af, void *asr);
34 struct asr_query *
35 gethostbyaddr_async(const void *addr, socklen_t len, int af,
36 void *asr);
37 struct asr_query *
38 getnetbyname_async(const char *name, void *asr);
39 struct asr_query *
40 getnetbyaddr_async(in_addr_t net, int type, void *asr);
41 struct asr_query *
42 getaddrinfo_async(const char *hostname, const char *servname,
43 const struct addrinfo *hints, void *asr);
44 struct asr_query *
45 getnameinfo_async(const struct sockaddr *sa, socklen_t salen,
46 char *host, size_t hostlen, char *serv, size_t servlen, int flags,
47 void *asr);
48
50 The asr functions provide a simple interface for asynchronous address
51 resolution and nameserver querying. They should be used in place of
52 the classical resolver functions of libc when blocking is not desir‐
53 able.
54 The principle of operation is as follows: All async requests are made
56 against an asr context which basically defines a list of sources to
57 query and a strategy to do so. The user creates a query through one of
58 the dedicated functions, and gets a handle representing the internal
59 query. A query is a state-machine that can be run to try to fulfill a
60 particular request. This is done by calling in a generic API that per‐
61 forms the state transitions until it needs to give the control back to
62 the user, either because a result is available, or because the next
63 transition implies a blocking call (a file descriptor needs to be read
64 from or written to). The user is responsible for dealing with the sit‐
65 uation: either get the result, or wait until the fd conditions are met,
66 and then call back into the resolving machinery when it is ready to
67 proceed.
68 The asr_run() function drives the resolving process. It runs the asyn‐
70 chronous query represented by the handle until a result is available,
71 or until it cannot continue without blocking. The results are returned
72 to the user through the parameter, which must be a valid pointer to
73 user allocated memory. is defined as:
74 struct asr_result {
75 /* Fields set if the query is not done yet (asr_run returns 0) */
76 int ar_cond; /* ASR_WANT_READ or ASR_WANT_WRITE */
77 int ar_fd; /* the fd waiting for io condition */
78 int ar_timeout; /* time to wait for in milliseconds */
79 /* Error fields. Depends on the query type. */
80 int ar_errno;
81 int ar_h_errno;
82 int ar_gai_errno;
83 int ar_rrset_errno;
84 /* Result for res_*_async() calls */
85 int ar_count; /* number of answers in the dns reply */
86 int ar_rcode; /* response code in the dns reply */
87 void *ar_data; /* raw reply packet (must be freed) */
88 int ar_datalen; /* reply packet length */
89 struct sockaddr_storage ar_ns; /* nameserver that responded */
90 /* Result for other calls. Must be freed properly. */
91 struct addrinfo *ar_addrinfo;
92 struct rrsetinfo *ar_rrsetinfo;
93 struct hostent *ar_hostent;
94 struct netent *ar_netent;
95 };
96 The function returns one of the following values:
98 0 The query cannot be processed further until a specific condition on a
100 file descriptor becomes true.
101 The following members of the
102 structure are filled:
103 one of ASR_WANT_READ or ASR_WANT_WRITE,
105 the file descriptor waiting for an IO operation,
107 the amount of time to wait for in milliseconds.
109 The caller is expected to call
111 asr_run()
112 again once the condition holds or the timeout expires.
113 1 The query is completed.
115 The members relevant to the actual async query type are set accordingly,
116 including error conditions.
117 In any case, the query is cleared and its handle is invalidated.
118 Note that although the query itself may fail (the error being properly reported
120 in the
121 structure), the
122 asr_run()
123 function itself cannot fail and it always preserves errno.
124 The
126 asr_run_sync()
127 function is a wrapper around
128 asr_run()
129 that handles the read/write conditions, thus falling back to a blocking
130 interface.
131 It only returns 1.
132 It also preserves errno.
133 The
135 asr_abort()
136 function clears a running query.
137 It can be called when the query is waiting on a file descriptor.
138 Note that a completed query is already cleared when
139 asr_run()
140 returns, so
141 asr_abort()
142 must not be called in this case.
143 The remaining functions are used to initiate different kinds of query
145 on the
146 resolver context.
147 The specific operational details for each of them are described below.
148 All functions return a handle to an internal query, or NULL if they could
149 not allocate the necessary resources to initiate the query.
150 All other errors (especially invalid parameters) are reported when calling
151 asr_run().
152 They usually have the same interface as an existing resolver function, with
153 an additional
154 asr
155 argument, which specifies the context to use for this request.
156 For now, the argument must always be NULL, which will use the default
157 context for the current thread.
158 The
160 res_send_async(),
161 res_query_async()
162 and
163 res_search_async()
164 functions are asynchronous versions of the standard libc resolver routines.
165 Their interface is very similar, except that the response buffer is always
166 allocated internally.
167 The return value is found upon completion in the
168 member of the response structure.
169 In addition, the
170 structure contains the address of the DNS server that sent the response,
171 contains the code returned by the server in the DNS response packet, and
172 contains the number of answers in the packet.
173 If a response is received it is placed in a newly allocated buffer
174 and returned as
175 member.
176 This buffer must be freed by the caller.
177 On error, the
178 and
179 members are set accordingly.
180 The
182 getrrsetbyname_async()
183 function is an asynchronous version of
184 getrrsetbyname(3).
185 Upon completion, the return code is found in
186 and the address to the newly allocated result set is set in
187 As for the blocking function, it must be freed by calling
188 freerrset(3).
189 The
191 gethostbyname_async(),
192 gethostbyname2_async()
193 and
194 gethostbyaddr_async()
195 functions provide an asynchronous version of the network host entry functions.
196 Upon completion,
197 ar_h_errno
198 is set and the resulting hostent address, if found, is set
199 in the
200 ar_hostent
201 field.
202 Note that unlike their blocking counterparts, these functions always return a
203 pointer to newly allocated memory, which must be released by the caller using
204 free(3).
205 Similarly, the
207 getnetbyname_async()
208 and
209 getnetbyaddr_async()
210 functions provide an asynchronous version of the network entry functions.
211 Upon completion,
212 ar_h_errno
213 is set and the resulting netent address, if found, is set
214 in the
215 ar_netent
216 field.
217 The memory there is also allocated for the request, and it must be freed by
218 free(3).
219 The
221 getaddrinfo_async()
222 function is an asynchronous version of the
223 getaddrinfo(3)
224 call.
225 It provides a chain of addrinfo structures with all valid combinations of
226 socket address for the given
227 ,
228 and
229 Those three parameters have the same meaning as for the blocking counterpart.
230 Upon completion the return code is set in
231 The
232 member may also be set.
233 On success, the
234 member points to a newly allocated list of addrinfo.
235 This list must be freed with
236 freeaddrinfo(3).
237
239 This implementation of the asynchronous resolver interface is thread-
240 safe and lock-free internally, but the following restriction applies:
241 Two different threads must not create queries on the same context or
242 run queries originating from the same context at the same time. If
243 they want to do that, all calls must be protected by a mutex around
244 that context.
245 It is generally not a problem since the main point of the asynchronous
247 resolver is to multiplex queries within a single thread of control, so
248 sharing a resolver among threads is not useful.
249
251 getaddrinfo(3), gethostbyname(3), getnameinfo(3), getnetbyname(3),
252 getrrsetbyname(3), res_send(3), resolv.conf(5)
253
255 This DNS resolver implementation doesn't support the EDNS0 protocol
256 extension yet.
257 $Mdocdate: March 26 2014 $ ASR_RUN(3)