Debian Codegraph @

upstream/debian-unstable/man3/getaddrinfo_a.3

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