1 24fb1a39 2025-06-02 kirill .\" $OpenBSD: asr_run.3,v 1.5 2022/03/31 17:27:15 naddy Exp $
3 24fb1a39 2025-06-02 kirill .\" Copyright (c) 2012-2014, Eric Faurot <eric@openbsd.org>
5 24fb1a39 2025-06-02 kirill .\" Permission to use, copy, modify, and distribute this software for any
6 24fb1a39 2025-06-02 kirill .\" purpose with or without fee is hereby granted, provided that the above
7 24fb1a39 2025-06-02 kirill .\" copyright notice and this permission notice appear in all copies.
9 24fb1a39 2025-06-02 kirill .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
10 24fb1a39 2025-06-02 kirill .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11 24fb1a39 2025-06-02 kirill .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
12 24fb1a39 2025-06-02 kirill .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13 24fb1a39 2025-06-02 kirill .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
14 24fb1a39 2025-06-02 kirill .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15 24fb1a39 2025-06-02 kirill .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
17 24fb1a39 2025-06-02 kirill .Dd $Mdocdate: March 31 2022 $
18 24fb1a39 2025-06-02 kirill .Dt ASR_RUN 3
21 24fb1a39 2025-06-02 kirill .Nm asr_run ,
22 24fb1a39 2025-06-02 kirill .Nm asr_run_sync ,
23 24fb1a39 2025-06-02 kirill .Nm asr_abort ,
24 24fb1a39 2025-06-02 kirill .Nm asr_resolver_from_string ,
25 24fb1a39 2025-06-02 kirill .Nm asr_resolver_free ,
26 24fb1a39 2025-06-02 kirill .Nm res_send_async ,
27 24fb1a39 2025-06-02 kirill .Nm res_query_async ,
28 24fb1a39 2025-06-02 kirill .Nm res_search_async ,
29 24fb1a39 2025-06-02 kirill .Nm getrrsetbyname_async ,
30 24fb1a39 2025-06-02 kirill .Nm gethostbyname_async ,
31 24fb1a39 2025-06-02 kirill .Nm gethostbyname2_async ,
32 24fb1a39 2025-06-02 kirill .Nm gethostbyaddr_async ,
33 24fb1a39 2025-06-02 kirill .Nm getnetbyname_async ,
34 24fb1a39 2025-06-02 kirill .Nm getnetbyaddr_async ,
35 24fb1a39 2025-06-02 kirill .Nm getaddrinfo_async ,
36 24fb1a39 2025-06-02 kirill .Nm getnameinfo_async
37 24fb1a39 2025-06-02 kirill .Nd asynchronous resolver functions
38 24fb1a39 2025-06-02 kirill .Sh SYNOPSIS
39 24fb1a39 2025-06-02 kirill .In sys/types.h
40 24fb1a39 2025-06-02 kirill .In sys/socket.h
41 24fb1a39 2025-06-02 kirill .In netdb.h
44 24fb1a39 2025-06-02 kirill .Fn asr_run "struct asr_query *aq" "struct asr_result *ar"
46 24fb1a39 2025-06-02 kirill .Fn asr_run_sync "struct asr_query *aq" "struct asr_result *ar"
48 24fb1a39 2025-06-02 kirill .Fn asr_abort "struct asr_query *aq"
49 24fb1a39 2025-06-02 kirill .Ft void *
50 24fb1a39 2025-06-02 kirill .Fn asr_resolver_from_string "const char *str"
52 24fb1a39 2025-06-02 kirill .Fn asr_resolver_free "void *asr"
53 24fb1a39 2025-06-02 kirill .Ft struct asr_query *
54 24fb1a39 2025-06-02 kirill .Fn res_send_async "const unsigned char *pkt" "int pktlen" "void *asr"
55 24fb1a39 2025-06-02 kirill .Ft struct asr_query *
56 24fb1a39 2025-06-02 kirill .Fn res_query_async "const char *name" "int class" "int type" "void *asr"
57 24fb1a39 2025-06-02 kirill .Ft struct asr_query *
58 24fb1a39 2025-06-02 kirill .Fn res_search_async "const char *name" "int class" "int type" "void *asr"
59 24fb1a39 2025-06-02 kirill .Ft struct asr_query *
60 24fb1a39 2025-06-02 kirill .Fn getrrsetbyname_async "const char *hostname" "unsigned int rdclass" "unsigned int rdtype" "unsigned int flags" "void *asr"
61 24fb1a39 2025-06-02 kirill .Ft struct asr_query *
62 24fb1a39 2025-06-02 kirill .Fn gethostbyname_async "const char *name" "void *asr"
63 24fb1a39 2025-06-02 kirill .Ft struct asr_query *
64 24fb1a39 2025-06-02 kirill .Fn gethostbyname2_async "const char *name" "int af" "void *asr"
65 24fb1a39 2025-06-02 kirill .Ft struct asr_query *
66 24fb1a39 2025-06-02 kirill .Fn gethostbyaddr_async "const void *addr" "socklen_t len" "int af" "void *asr"
67 24fb1a39 2025-06-02 kirill .Ft struct asr_query *
68 24fb1a39 2025-06-02 kirill .Fn getnetbyname_async "const char *name" "void *asr"
69 24fb1a39 2025-06-02 kirill .Ft struct asr_query *
70 24fb1a39 2025-06-02 kirill .Fn getnetbyaddr_async "in_addr_t net" "int type" "void *asr"
71 24fb1a39 2025-06-02 kirill .Ft struct asr_query *
72 24fb1a39 2025-06-02 kirill .Fn getaddrinfo_async "const char *hostname" "const char *servname" "const struct addrinfo *hints" "void *asr"
73 24fb1a39 2025-06-02 kirill .Ft struct asr_query *
74 24fb1a39 2025-06-02 kirill .Fn getnameinfo_async "const struct sockaddr *sa" "socklen_t salen" "char *host" "size_t hostlen" "char *serv" "size_t servlen" "int flags" "void *asr"
75 24fb1a39 2025-06-02 kirill .Sh DESCRIPTION
78 24fb1a39 2025-06-02 kirill functions provide a simple interface for asynchronous address
79 24fb1a39 2025-06-02 kirill resolution and nameserver querying.
80 24fb1a39 2025-06-02 kirill They should be used in place of the classical resolver functions
81 24fb1a39 2025-06-02 kirill of libc when blocking is not desirable.
83 24fb1a39 2025-06-02 kirill The principle of operation is as follows:
84 24fb1a39 2025-06-02 kirill All async requests are made against an
86 24fb1a39 2025-06-02 kirill context which basically defines a list of sources to query and a
87 24fb1a39 2025-06-02 kirill strategy to do so.
88 24fb1a39 2025-06-02 kirill The user creates a query through one of the dedicated functions, and
89 24fb1a39 2025-06-02 kirill gets a handle representing the internal query.
90 24fb1a39 2025-06-02 kirill A query is a state-machine that can be run to try to fulfill a
91 24fb1a39 2025-06-02 kirill particular request.
92 24fb1a39 2025-06-02 kirill This is done by calling in a generic API that performs the state
93 24fb1a39 2025-06-02 kirill transitions until it needs to give the control back to the user,
94 24fb1a39 2025-06-02 kirill either because a result is available, or because the next transition
95 24fb1a39 2025-06-02 kirill implies a blocking call (a file descriptor needs to be read from or
96 24fb1a39 2025-06-02 kirill written to).
97 24fb1a39 2025-06-02 kirill The user is responsible for dealing with the situation: either get
98 24fb1a39 2025-06-02 kirill the result, or wait until the fd conditions are met, and then call
99 24fb1a39 2025-06-02 kirill back into the resolving machinery when it is ready to proceed.
102 24fb1a39 2025-06-02 kirill .Fn asr_run
103 24fb1a39 2025-06-02 kirill function drives the resolving process.
104 24fb1a39 2025-06-02 kirill It runs the asynchronous query represented by the
106 24fb1a39 2025-06-02 kirill handle until a result is available, or until it cannot continue
107 24fb1a39 2025-06-02 kirill without blocking.
108 24fb1a39 2025-06-02 kirill The results are returned to the user through the
110 24fb1a39 2025-06-02 kirill parameter, which must be a valid pointer to user allocated memory.
112 24fb1a39 2025-06-02 kirill is defined as:
113 24fb1a39 2025-06-02 kirill .Bd -literal
114 24fb1a39 2025-06-02 kirill struct asr_result {
116 24fb1a39 2025-06-02 kirill /* Fields set if the query is not done yet (asr_run returns 0) */
117 24fb1a39 2025-06-02 kirill int ar_cond; /* ASR_WANT_READ or ASR_WANT_WRITE */
118 24fb1a39 2025-06-02 kirill int ar_fd; /* the fd waiting for io condition */
119 24fb1a39 2025-06-02 kirill int ar_timeout; /* time to wait for in milliseconds */
121 24fb1a39 2025-06-02 kirill /* Error fields. Depends on the query type. */
122 24fb1a39 2025-06-02 kirill int ar_errno;
123 24fb1a39 2025-06-02 kirill int ar_h_errno;
124 24fb1a39 2025-06-02 kirill int ar_gai_errno;
125 24fb1a39 2025-06-02 kirill int ar_rrset_errno;
127 24fb1a39 2025-06-02 kirill /* Result for res_*_async() calls */
128 24fb1a39 2025-06-02 kirill int ar_count; /* number of answers in the dns reply */
129 24fb1a39 2025-06-02 kirill int ar_rcode; /* response code in the dns reply */
130 24fb1a39 2025-06-02 kirill void *ar_data; /* raw reply packet (must be freed) */
131 24fb1a39 2025-06-02 kirill int ar_datalen; /* reply packet length */
132 24fb1a39 2025-06-02 kirill struct sockaddr_storage ar_ns; /* nameserver that responded */
134 24fb1a39 2025-06-02 kirill /* Result for other calls. Must be freed properly. */
135 24fb1a39 2025-06-02 kirill struct addrinfo *ar_addrinfo;
136 24fb1a39 2025-06-02 kirill struct rrsetinfo *ar_rrsetinfo;
137 24fb1a39 2025-06-02 kirill struct hostent *ar_hostent;
138 24fb1a39 2025-06-02 kirill struct netent *ar_netent;
142 24fb1a39 2025-06-02 kirill The function returns one of the following values:
143 24fb1a39 2025-06-02 kirill .Bl -tag -width "0 " -offset indent
145 24fb1a39 2025-06-02 kirill The query cannot be processed further until a specific condition on a
146 24fb1a39 2025-06-02 kirill file descriptor becomes true.
147 24fb1a39 2025-06-02 kirill The following members of the
149 24fb1a39 2025-06-02 kirill structure are filled:
151 24fb1a39 2025-06-02 kirill .Bl -tag -width "ar_timeout " -compact
152 24fb1a39 2025-06-02 kirill .It Fa ar_cond
153 24fb1a39 2025-06-02 kirill one of ASR_WANT_READ or ASR_WANT_WRITE,
154 24fb1a39 2025-06-02 kirill .It Fa ar_fd
155 24fb1a39 2025-06-02 kirill the file descriptor waiting for an IO operation,
156 24fb1a39 2025-06-02 kirill .It Fa ar_timeout
157 24fb1a39 2025-06-02 kirill the amount of time to wait for in milliseconds.
160 24fb1a39 2025-06-02 kirill The caller is expected to call
161 24fb1a39 2025-06-02 kirill .Fn asr_run
162 24fb1a39 2025-06-02 kirill again once the condition holds or the timeout expires.
164 24fb1a39 2025-06-02 kirill The query is completed.
165 24fb1a39 2025-06-02 kirill The members relevant to the actual async query type are set accordingly,
166 24fb1a39 2025-06-02 kirill including error conditions.
167 24fb1a39 2025-06-02 kirill In any case, the query is cleared and its handle is invalidated.
170 24fb1a39 2025-06-02 kirill Note that although the query itself may fail (the error being properly reported
173 24fb1a39 2025-06-02 kirill structure), the
174 24fb1a39 2025-06-02 kirill .Fn asr_run
175 24fb1a39 2025-06-02 kirill function itself cannot fail and it always preserves errno.
178 24fb1a39 2025-06-02 kirill .Fn asr_run_sync
179 24fb1a39 2025-06-02 kirill function is a wrapper around
180 24fb1a39 2025-06-02 kirill .Fn asr_run
181 24fb1a39 2025-06-02 kirill that handles the read/write conditions, thus falling back to a blocking
182 24fb1a39 2025-06-02 kirill interface.
183 24fb1a39 2025-06-02 kirill It only returns 1.
184 24fb1a39 2025-06-02 kirill It also preserves errno.
187 24fb1a39 2025-06-02 kirill .Fn asr_abort
188 24fb1a39 2025-06-02 kirill function clears a running query.
189 24fb1a39 2025-06-02 kirill It can be called when the query is waiting on a file descriptor.
190 24fb1a39 2025-06-02 kirill Note that a completed query is already cleared when
191 24fb1a39 2025-06-02 kirill .Fn asr_run
192 24fb1a39 2025-06-02 kirill returns, so
193 24fb1a39 2025-06-02 kirill .Fn asr_abort
194 24fb1a39 2025-06-02 kirill must not be called in this case.
197 24fb1a39 2025-06-02 kirill .Fn asr_resolver_from_string
198 24fb1a39 2025-06-02 kirill function constructs an asr context from a string that conforms to the
199 24fb1a39 2025-06-02 kirill .Xr resolv.conf 5
200 24fb1a39 2025-06-02 kirill file format.
201 24fb1a39 2025-06-02 kirill .Fn asr_resolver_free
202 24fb1a39 2025-06-02 kirill frees an asr context obtained from
203 24fb1a39 2025-06-02 kirill .Fn asr_resolver_from_string .
205 24fb1a39 2025-06-02 kirill The remaining functions are used to initiate different kinds of query
208 24fb1a39 2025-06-02 kirill resolver context.
209 24fb1a39 2025-06-02 kirill The specific operational details for each of them are described below.
210 24fb1a39 2025-06-02 kirill All functions return a handle to an internal query, or NULL if they could
211 24fb1a39 2025-06-02 kirill not allocate the necessary resources to initiate the query.
212 24fb1a39 2025-06-02 kirill All other errors (especially invalid parameters) are reported when calling
213 24fb1a39 2025-06-02 kirill .Fn asr_run .
214 24fb1a39 2025-06-02 kirill They usually have the same interface as an existing resolver function, with
215 24fb1a39 2025-06-02 kirill an additional
217 24fb1a39 2025-06-02 kirill argument, which specifies the context to use for this request.
220 24fb1a39 2025-06-02 kirill argument of NULL will use the default context for the current thread.
221 24fb1a39 2025-06-02 kirill This is constructed from
222 24fb1a39 2025-06-02 kirill .Pa /etc/resolv.conf
223 24fb1a39 2025-06-02 kirill and takes care of reloading the file when it changes.
226 24fb1a39 2025-06-02 kirill .Fn res_send_async ,
227 24fb1a39 2025-06-02 kirill .Fn res_query_async
229 24fb1a39 2025-06-02 kirill .Fn res_search_async
230 24fb1a39 2025-06-02 kirill functions are asynchronous versions of the standard libc resolver routines.
231 24fb1a39 2025-06-02 kirill Their interface is very similar, except that the response buffer is always
232 24fb1a39 2025-06-02 kirill allocated internally.
233 24fb1a39 2025-06-02 kirill The return value is found upon completion in the
234 24fb1a39 2025-06-02 kirill .Fa ar_datalen
235 24fb1a39 2025-06-02 kirill member of the response structure.
236 24fb1a39 2025-06-02 kirill In addition, the
237 24fb1a39 2025-06-02 kirill .Fa ar_ns
238 24fb1a39 2025-06-02 kirill structure contains the address of the DNS server that sent the response,
239 24fb1a39 2025-06-02 kirill .Fa ar_rcode
240 24fb1a39 2025-06-02 kirill contains the code returned by the server in the DNS response packet, and
241 24fb1a39 2025-06-02 kirill .Fa ar_count
242 24fb1a39 2025-06-02 kirill contains the number of answers in the packet.
243 24fb1a39 2025-06-02 kirill If a response is received, it is placed in a newly allocated buffer
244 24fb1a39 2025-06-02 kirill and returned as
245 24fb1a39 2025-06-02 kirill .Fa ar_data
247 24fb1a39 2025-06-02 kirill This buffer must be freed by the caller.
248 24fb1a39 2025-06-02 kirill On error, the
249 24fb1a39 2025-06-02 kirill .Fa ar_errno
251 24fb1a39 2025-06-02 kirill .Fa ar_h_errno
252 24fb1a39 2025-06-02 kirill members are set accordingly.
255 24fb1a39 2025-06-02 kirill .Fn getrrsetbyname_async
256 24fb1a39 2025-06-02 kirill function is an asynchronous version of
257 24fb1a39 2025-06-02 kirill .Xr getrrsetbyname 3 .
258 24fb1a39 2025-06-02 kirill Upon completion, the return code is found in
259 24fb1a39 2025-06-02 kirill .Fa ar_rrset_errno
260 24fb1a39 2025-06-02 kirill and the address to the newly allocated result set is set in
261 24fb1a39 2025-06-02 kirill .Fa ar_rrsetinfo .
262 24fb1a39 2025-06-02 kirill As for the blocking function, it must be freed by calling
263 24fb1a39 2025-06-02 kirill .Xr freerrset 3 .
266 24fb1a39 2025-06-02 kirill .Fn gethostbyname_async ,
267 24fb1a39 2025-06-02 kirill .Fn gethostbyname2_async
269 24fb1a39 2025-06-02 kirill .Fn gethostbyaddr_async
270 24fb1a39 2025-06-02 kirill functions provide an asynchronous version of the network host entry functions.
271 24fb1a39 2025-06-02 kirill Upon completion,
272 24fb1a39 2025-06-02 kirill .Ar ar_h_errno
273 24fb1a39 2025-06-02 kirill is set and the resulting hostent address, if found, is set
275 24fb1a39 2025-06-02 kirill .Ar ar_hostent
277 24fb1a39 2025-06-02 kirill Note that unlike their blocking counterparts, these functions always return a
278 24fb1a39 2025-06-02 kirill pointer to newly allocated memory, which must be released by the caller using
279 24fb1a39 2025-06-02 kirill .Xr free 3 .
281 24fb1a39 2025-06-02 kirill Similarly, the
282 24fb1a39 2025-06-02 kirill .Fn getnetbyname_async
284 24fb1a39 2025-06-02 kirill .Fn getnetbyaddr_async
285 24fb1a39 2025-06-02 kirill functions provide an asynchronous version of the network entry functions.
286 24fb1a39 2025-06-02 kirill Upon completion,
287 24fb1a39 2025-06-02 kirill .Ar ar_h_errno
288 24fb1a39 2025-06-02 kirill is set and the resulting netent address, if found, is set
290 24fb1a39 2025-06-02 kirill .Ar ar_netent
292 24fb1a39 2025-06-02 kirill The memory there is also allocated for the request, and it must be freed by
293 24fb1a39 2025-06-02 kirill .Xr free 3 .
296 24fb1a39 2025-06-02 kirill .Fn getaddrinfo_async
297 24fb1a39 2025-06-02 kirill function is an asynchronous version of the
298 24fb1a39 2025-06-02 kirill .Xr getaddrinfo 3
300 24fb1a39 2025-06-02 kirill It provides a chain of addrinfo structures with all valid combinations of
301 24fb1a39 2025-06-02 kirill socket address for the given
302 24fb1a39 2025-06-02 kirill .Fa hostname ,
303 24fb1a39 2025-06-02 kirill .Fa servname
305 24fb1a39 2025-06-02 kirill .Fa hints .
306 24fb1a39 2025-06-02 kirill Those three parameters have the same meaning as for the blocking counterpart.
307 24fb1a39 2025-06-02 kirill Upon completion the return code is set in
308 24fb1a39 2025-06-02 kirill .Fa ar_gai_errno .
310 24fb1a39 2025-06-02 kirill .Fa ar_errno
311 24fb1a39 2025-06-02 kirill member may also be set.
312 24fb1a39 2025-06-02 kirill On success, the
313 24fb1a39 2025-06-02 kirill .Fa ar_addrinfo
314 24fb1a39 2025-06-02 kirill member points to a newly allocated list of addrinfo.
315 24fb1a39 2025-06-02 kirill This list must be freed with
316 24fb1a39 2025-06-02 kirill .Xr freeaddrinfo 3 .
317 24fb1a39 2025-06-02 kirill .Sh WORKING WITH THREADS
318 24fb1a39 2025-06-02 kirill This implementation of the asynchronous resolver interface is thread-safe
319 24fb1a39 2025-06-02 kirill and lock-free internally, but the following restriction applies:
320 24fb1a39 2025-06-02 kirill Two different threads must not create queries on the same context or
321 24fb1a39 2025-06-02 kirill run queries originating from the same context at the same time.
322 24fb1a39 2025-06-02 kirill If they want to do that, all calls must be protected by a mutex around
323 24fb1a39 2025-06-02 kirill that context.
325 24fb1a39 2025-06-02 kirill It is generally not a problem since the main point of the asynchronous
326 24fb1a39 2025-06-02 kirill resolver is to multiplex queries within a single thread of control,
327 24fb1a39 2025-06-02 kirill so sharing a resolver among threads is not useful.
328 24fb1a39 2025-06-02 kirill .Sh SEE ALSO
329 24fb1a39 2025-06-02 kirill .Xr getaddrinfo 3 ,
330 24fb1a39 2025-06-02 kirill .Xr gethostbyname 3 ,
331 24fb1a39 2025-06-02 kirill .Xr getnameinfo 3 ,
332 24fb1a39 2025-06-02 kirill .Xr getnetbyname 3 ,
333 24fb1a39 2025-06-02 kirill .Xr getrrsetbyname 3 ,
334 24fb1a39 2025-06-02 kirill .Xr res_send 3 ,
335 24fb1a39 2025-06-02 kirill .Xr resolv.conf 5