Debian Codegraph @

upstream/debian-trixie/man3/getaddrinfo_a.3

raw
1 '\" t
2 .\" Copyright (c) 2009 Petr Baudis <[email protected]>
3 .\" and clean-ups and additions (C) Copyright 2010 Michael Kerrisk
4 .\" <[email protected]>
5 .\"
6 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
7 .\"
8 .\" References: http://people.redhat.com/drepper/asynchnl.pdf,
9 .\" http://www.imperialviolet.org/2005/06/01/asynchronous-dns-lookups-with-glibc.html
10 .\"
11 .TH getaddrinfo_a 3 2024-06-15 "Linux man-pages 6.9.1"
12 .SH NAME
13 getaddrinfo_a, gai_suspend, gai_error, gai_cancel \- asynchronous
14 network address and service translation
15 .SH LIBRARY
16 Asynchronous name lookup library
17 .RI ( libanl ", " \-lanl )
18 .SH SYNOPSIS
19 .nf
20 .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
21 .B #include <netdb.h>
22 .P
23 .BI "int getaddrinfo_a(int " mode ", struct gaicb *" list [restrict],
24 .BI " int " nitems ", struct sigevent *restrict " sevp );
25 .BI "int gai_suspend(const struct gaicb *const " list "[], int " nitems ,
26 .BI " const struct timespec *" timeout );
27 .P
28 .BI "int gai_error(struct gaicb *" req );
29 .BI "int gai_cancel(struct gaicb *" req );
30 .fi
31 .SH DESCRIPTION
32 The
33 .BR getaddrinfo_a ()
34 function performs the same task as
35 .BR getaddrinfo (3),
36 but allows multiple name look-ups to be performed asynchronously,
37 with optional notification on completion of look-up operations.
38 .P
39 The
40 .I mode
41 argument has one of the following values:
42 .TP
43 .B GAI_WAIT
44 Perform the look-ups synchronously.
45 The call blocks until the look-ups have completed.
46 .TP
47 .B GAI_NOWAIT
48 Perform the look-ups asynchronously.
49 The call returns immediately,
50 and the requests are resolved in the background.
51 See the discussion of the
52 .I sevp
53 argument below.
54 .P
55 The array
56 .I list
57 specifies the look-up requests to process.
58 The
59 .I nitems
60 argument specifies the number of elements in
61 .IR list .
62 The requested look-up operations are started in parallel.
63 NULL elements in
64 .I list
65 are ignored.
66 Each request is described by a
67 .I gaicb
68 structure, defined as follows:
69 .P
70 .in +4n
71 .EX
72 struct gaicb {
73 const char *ar_name;
74 const char *ar_service;
75 const struct addrinfo *ar_request;
76 struct addrinfo *ar_result;
77 };
78 .EE
79 .in
80 .P
81 The elements of this structure correspond to the arguments of
82 .BR getaddrinfo (3).
83 Thus,
84 .I ar_name
85 corresponds to the
86 .I node
87 argument and
88 .I ar_service
89 to the
90 .I service
91 argument, identifying an Internet host and a service.
92 The
93 .I ar_request
94 element corresponds to the
95 .I hints
96 argument, specifying the criteria for selecting
97 the returned socket address structures.
98 Finally,
99 .I ar_result
100 corresponds to the
101 .I res
102 argument; you do not need to initialize this element,
103 it will be automatically set when the request
104 is resolved.
105 The
106 .I addrinfo
107 structure referenced by the last two elements is described in
108 .BR getaddrinfo (3).
109 .P
110 When
111 .I mode
112 is specified as
113 .BR GAI_NOWAIT ,
114 notifications about resolved requests
115 can be obtained by employing the
116 .I sigevent
117 structure pointed to by the
118 .I sevp
119 argument.
120 For the definition and general details of this structure, see
121 .BR sigevent (3type).
122 The
123 .I sevp\->sigev_notify
124 field can have the following values:
125 .TP
126 .B SIGEV_NONE
127 Don't provide any notification.
128 .TP
129 .B SIGEV_SIGNAL
130 When a look-up completes, generate the signal
131 .I sigev_signo
132 for the process.
133 See
134 .BR sigevent (3type)
135 for general details.
136 The
137 .I si_code
138 field of the
139 .I siginfo_t
140 structure will be set to
141 .BR SI_ASYNCNL .
142 .\" si_pid and si_uid are also set, to the values of the calling process,
143 .\" which doesn't provide useful information, so we'll skip mentioning it.
144 .TP
145 .B SIGEV_THREAD
146 When a look-up completes, invoke
147 .I sigev_notify_function
148 as if it were the start function of a new thread.
149 See
150 .BR sigevent (3type)
151 for details.
152 .P
153 For
154 .B SIGEV_SIGNAL
155 and
156 .BR SIGEV_THREAD ,
157 it may be useful to point
158 .I sevp\->sigev_value.sival_ptr
159 to
160 .IR list .
161 .P
162 The
163 .BR gai_suspend ()
164 function suspends execution of the calling thread,
165 waiting for the completion of one or more requests in the array
166 .IR list .
167 The
168 .I nitems
169 argument specifies the size of the array
170 .IR list .
171 The call blocks until one of the following occurs:
172 .IP \[bu] 3
173 One or more of the operations in
174 .I list
175 completes.
176 .IP \[bu]
177 The call is interrupted by a signal that is caught.
178 .IP \[bu]
179 The time interval specified in
180 .I timeout
181 elapses.
182 This argument specifies a timeout in seconds plus nanoseconds (see
183 .BR nanosleep (2)
184 for details of the
185 .I timespec
186 structure).
187 If
188 .I timeout
189 is NULL, then the call blocks indefinitely
190 (until one of the events above occurs).
191 .P
192 No explicit indication of which request was completed is given;
193 you must determine which request(s) have completed by iterating with
194 .BR gai_error ()
195 over the list of requests.
196 .P
197 The
198 .BR gai_error ()
199 function returns the status of the request
200 .IR req :
201 either
202 .B EAI_INPROGRESS
203 if the request was not completed yet,
204 0 if it was handled successfully,
205 or an error code if the request could not be resolved.
206 .P
207 The
208 .BR gai_cancel ()
209 function cancels the request
210 .IR req .
211 If the request has been canceled successfully,
212 the error status of the request will be set to
213 .B EAI_CANCELED
214 and normal asynchronous notification will be performed.
215 The request cannot be canceled if it is currently being processed;
216 in that case, it will be handled as if
217 .BR gai_cancel ()
218 has never been called.
219 If
220 .I req
221 is NULL, an attempt is made to cancel all outstanding requests
222 that the process has made.
223 .SH RETURN VALUE
224 The
225 .BR getaddrinfo_a ()
226 function returns 0 if all of the requests have been enqueued successfully,
227 or one of the following nonzero error codes:
228 .TP
229 .B EAI_AGAIN
230 The resources necessary to enqueue the look-up requests were not available.
231 The application may check the error status of each
232 request to determine which ones failed.
233 .TP
234 .B EAI_MEMORY
235 Out of memory.
236 .TP
237 .B EAI_SYSTEM
238 .I mode
239 is invalid.
240 .P
241 The
242 .BR gai_suspend ()
243 function returns 0 if at least one of the listed requests has been completed.
244 Otherwise, it returns one of the following nonzero error codes:
245 .TP
246 .B EAI_AGAIN
247 The given timeout expired before any of the requests could be completed.
248 .TP
249 .B EAI_ALLDONE
250 There were no actual requests given to the function.
251 .TP
252 .B EAI_INTR
253 A signal has interrupted the function.
254 Note that this interruption might have been
255 caused by signal notification of some completed look-up request.
256 .P
257 The
258 .BR gai_error ()
259 function can return
260 .B EAI_INPROGRESS
261 for an unfinished look-up request,
262 0 for a successfully completed look-up
263 (as described above), one of the error codes that could be returned by
264 .BR getaddrinfo (3),
265 or the error code
266 .B EAI_CANCELED
267 if the request has been canceled explicitly before it could be finished.
268 .P
269 The
270 .BR gai_cancel ()
271 function can return one of these values:
272 .TP
273 .B EAI_CANCELED
274 The request has been canceled successfully.
275 .TP
276 .B EAI_NOTCANCELED
277 The request has not been canceled.
278 .TP
279 .B EAI_ALLDONE
280 The request has already completed.
281 .P
282 The
283 .BR gai_strerror (3)
284 function translates these error codes to a human readable string,
285 suitable for error reporting.
286 .SH ATTRIBUTES
287 For an explanation of the terms used in this section, see
288 .BR attributes (7).
289 .TS
290 allbox;
291 lbx lb lb
292 l l l.
293 Interface Attribute Value
294 T{
295 .na
296 .nh
297 .BR getaddrinfo_a (),
298 .BR gai_suspend (),
299 .BR gai_error (),
300 .BR gai_cancel ()
301 T} Thread safety MT-Safe
302 .TE
303 .SH STANDARDS
304 GNU.
305 .SH HISTORY
306 glibc 2.2.3.
307 .P
308 The interface of
309 .BR getaddrinfo_a ()
310 was modeled after the
311 .BR lio_listio (3)
312 interface.
313 .SH EXAMPLES
314 Two examples are provided: a simple example that resolves
315 several requests in parallel synchronously, and a complex example
316 showing some of the asynchronous capabilities.
317 .SS Synchronous example
318 The program below simply resolves several hostnames in parallel,
319 giving a speed-up compared to resolving the hostnames sequentially using
320 .BR getaddrinfo (3).
321 The program might be used like this:
322 .P
323 .in +4n
324 .EX
325 $ \fB./a.out mirrors.kernel.org enoent.linuxfoundation.org gnu.org\fP
326 mirrors.kernel.org: 139.178.88.99
327 enoent.linuxfoundation.org: Name or service not known
328 gnu.org: 209.51.188.116
329 .EE
330 .in
331 .P
332 Here is the program source code
333 .P
334 .\" SRC BEGIN (sync.c)
335 .EX
336 #define _GNU_SOURCE
337 #include <err.h>
338 #include <netdb.h>
339 #include <stdio.h>
340 #include <stdlib.h>
341 #include <string.h>
342 \&
343 #define MALLOC(n, type) ((type *) reallocarray(NULL, n, sizeof(type)))
344 \&
345 int
346 main(int argc, char *argv[])
347 {
348 int ret;
349 struct gaicb *reqs[argc \- 1];
350 char host[NI_MAXHOST];
351 struct addrinfo *res;
352 \&
353 if (argc < 2) {
354 fprintf(stderr, "Usage: %s HOST...\[rs]n", argv[0]);
355 exit(EXIT_FAILURE);
356 }
357 \&
358 for (size_t i = 0; i < argc \- 1; i++) {
359 reqs[i] = MALLOC(1, struct gaicb);
360 if (reqs[i] == NULL)
361 err(EXIT_FAILURE, "malloc");
362 \&
363 memset(reqs[i], 0, sizeof(*reqs[0]));
364 reqs[i]\->ar_name = argv[i + 1];
365 }
366 \&
367 ret = getaddrinfo_a(GAI_WAIT, reqs, argc \- 1, NULL);
368 if (ret != 0) {
369 fprintf(stderr, "getaddrinfo_a() failed: %s\[rs]n",
370 gai_strerror(ret));
371 exit(EXIT_FAILURE);
372 }
373 \&
374 for (size_t i = 0; i < argc \- 1; i++) {
375 printf("%s: ", reqs[i]\->ar_name);
376 ret = gai_error(reqs[i]);
377 if (ret == 0) {
378 res = reqs[i]\->ar_result;
379 \&
380 ret = getnameinfo(res\->ai_addr, res\->ai_addrlen,
381 host, sizeof(host),
382 NULL, 0, NI_NUMERICHOST);
383 if (ret != 0) {
384 fprintf(stderr, "getnameinfo() failed: %s\[rs]n",
385 gai_strerror(ret));
386 exit(EXIT_FAILURE);
387 }
388 puts(host);
389 \&
390 } else {
391 puts(gai_strerror(ret));
392 }
393 }
394 exit(EXIT_SUCCESS);
395 }
396 .EE
397 .\" SRC END
398 .SS Asynchronous example
399 This example shows a simple interactive
400 .BR getaddrinfo_a ()
401 front-end.
402 The notification facility is not demonstrated.
403 .P
404 An example session might look like this:
405 .P
406 .in +4n
407 .EX
408 $ \fB./a.out\fP
409 > a mirrors.kernel.org enoent.linuxfoundation.org gnu.org
410 > c 2
411 [2] gnu.org: Request not canceled
412 > w 0 1
413 [00] mirrors.kernel.org: Finished
414 > l
415 [00] mirrors.kernel.org: 139.178.88.99
416 [01] enoent.linuxfoundation.org: Processing request in progress
417 [02] gnu.org: 209.51.188.116
418 > l
419 [00] mirrors.kernel.org: 139.178.88.99
420 [01] enoent.linuxfoundation.org: Name or service not known
421 [02] gnu.org: 209.51.188.116
422 .EE
423 .in
424 .P
425 The program source is as follows:
426 .P
427 .\" SRC BEGIN (async.c)
428 .EX
429 #define _GNU_SOURCE
430 #include <assert.h>
431 #include <err.h>
432 #include <netdb.h>
433 #include <stdio.h>
434 #include <stdlib.h>
435 #include <string.h>
436 \&
437 #define CALLOC(n, type) ((type *) calloc(n, sizeof(type)))
438 \&
439 #define REALLOCF(ptr, n, type) \[rs]
440 ({ \[rs]
441 static_assert(__builtin_types_compatible_p(typeof(ptr), type *)); \[rs]
442 \[rs]
443 (type *) reallocarrayf(ptr, n, sizeof(type)); \[rs]
444 })
445 \&
446 static struct gaicb **reqs = NULL;
447 static size_t nreqs = 0;
448 \&
449 static inline void *
450 reallocarrayf(void *p, size_t nmemb, size_t size)
451 {
452 void *q;
453 \&
454 q = reallocarray(p, nmemb, size);
455 if (q == NULL && nmemb != 0 && size != 0)
456 free(p);
457 return q;
458 }
459 \&
460 static char *
461 getcmd(void)
462 {
463 static char buf[256];
464 \&
465 fputs("> ", stdout); fflush(stdout);
466 if (fgets(buf, sizeof(buf), stdin) == NULL)
467 return NULL;
468 \&
469 if (buf[strlen(buf) \- 1] == \[aq]\[rs]n\[aq])
470 buf[strlen(buf) \- 1] = 0;
471 \&
472 return buf;
473 }
474 \&
475 /* Add requests for specified hostnames. */
476 static void
477 add_requests(void)
478 {
479 size_t nreqs_base = nreqs;
480 char *host;
481 int ret;
482 \&
483 while ((host = strtok(NULL, " "))) {
484 nreqs++;
485 reqs = REALLOCF(reqs, nreqs, struct gaicb *);
486 if (reqs == NULL)
487 err(EXIT_FAILURE, "reallocf");
488 \&
489 reqs[nreqs \- 1] = CALLOC(1, struct gaicb);
490 if (reqs[nreqs \- 1] == NULL)
491 err(EXIT_FAILURE, "calloc");
492 \&
493 reqs[nreqs \- 1]\->ar_name = strdup(host);
494 }
495 \&
496 /* Queue nreqs_base..nreqs requests. */
497 \&
498 ret = getaddrinfo_a(GAI_NOWAIT, &reqs[nreqs_base],
499 nreqs \- nreqs_base, NULL);
500 if (ret) {
501 fprintf(stderr, "getaddrinfo_a() failed: %s\[rs]n",
502 gai_strerror(ret));
503 exit(EXIT_FAILURE);
504 }
505 }
506 \&
507 /* Wait until at least one of specified requests completes. */
508 static void
509 wait_requests(void)
510 {
511 char *id;
512 int ret;
513 size_t n;
514 struct gaicb const **wait_reqs;
515 \&
516 wait_reqs = CALLOC(nreqs, const struct gaicb *);
517 if (wait_reqs == NULL)
518 err(EXIT_FAILURE, "calloc");
519 \&
520 /* NULL elements are ignored by gai_suspend(). */
521 \&
522 while ((id = strtok(NULL, " ")) != NULL) {
523 n = atoi(id);
524 \&
525 if (n >= nreqs) {
526 printf("Bad request number: %s\[rs]n", id);
527 return;
528 }
529 \&
530 wait_reqs[n] = reqs[n];
531 }
532 \&
533 ret = gai_suspend(wait_reqs, nreqs, NULL);
534 if (ret) {
535 printf("gai_suspend(): %s\[rs]n", gai_strerror(ret));
536 return;
537 }
538 \&
539 for (size_t i = 0; i < nreqs; i++) {
540 if (wait_reqs[i] == NULL)
541 continue;
542 \&
543 ret = gai_error(reqs[i]);
544 if (ret == EAI_INPROGRESS)
545 continue;
546 \&
547 printf("[%02zu] %s: %s\[rs]n", i, reqs[i]\->ar_name,
548 ret == 0 ? "Finished" : gai_strerror(ret));
549 }
550 }
551 \&
552 /* Cancel specified requests. */
553 static void
554 cancel_requests(void)
555 {
556 char *id;
557 int ret;
558 size_t n;
559 \&
560 while ((id = strtok(NULL, " ")) != NULL) {
561 n = atoi(id);
562 \&
563 if (n >= nreqs) {
564 printf("Bad request number: %s\[rs]n", id);
565 return;
566 }
567 \&
568 ret = gai_cancel(reqs[n]);
569 printf("[%s] %s: %s\[rs]n", id, reqs[atoi(id)]\->ar_name,
570 gai_strerror(ret));
571 }
572 }
573 \&
574 /* List all requests. */
575 static void
576 list_requests(void)
577 {
578 int ret;
579 char host[NI_MAXHOST];
580 struct addrinfo *res;
581 \&
582 for (size_t i = 0; i < nreqs; i++) {
583 printf("[%02zu] %s: ", i, reqs[i]\->ar_name);
584 ret = gai_error(reqs[i]);
585 \&
586 if (!ret) {
587 res = reqs[i]\->ar_result;
588 \&
589 ret = getnameinfo(res\->ai_addr, res\->ai_addrlen,
590 host, sizeof(host),
591 NULL, 0, NI_NUMERICHOST);
592 if (ret) {
593 fprintf(stderr, "getnameinfo() failed: %s\[rs]n",
594 gai_strerror(ret));
595 exit(EXIT_FAILURE);
596 }
597 puts(host);
598 } else {
599 puts(gai_strerror(ret));
600 }
601 }
602 }
603 \&
604 int
605 main(void)
606 {
607 char *cmdline;
608 char *cmd;
609 \&
610 while ((cmdline = getcmd()) != NULL) {
611 cmd = strtok(cmdline, " ");
612 \&
613 if (cmd == NULL) {
614 list_requests();
615 } else {
616 switch (cmd[0]) {
617 case \[aq]a\[aq]:
618 add_requests();
619 break;
620 case \[aq]w\[aq]:
621 wait_requests();
622 break;
623 case \[aq]c\[aq]:
624 cancel_requests();
625 break;
626 case \[aq]l\[aq]:
627 list_requests();
628 break;
629 default:
630 fprintf(stderr, "Bad command: %c\[rs]n", cmd[0]);
631 break;
632 }
633 }
634 }
635 exit(EXIT_SUCCESS);
636 }
637 .EE
638 .\" SRC END
639 .SH SEE ALSO
640 .BR getaddrinfo (3),
641 .BR inet (3),
642 .BR lio_listio (3),
643 .BR hostname (7),
644 .BR ip (7),
645 .BR sigevent (3type)