NAME
getaddrinfoa, gaisuspend, gaierror, gaicancel - asynchronous net‐ work address and service translation SYNOPSIS
#define GNUSOURCE /* See featuretestmacros(7) */
#include
int getaddrinfoa(int mode, struct gaicb *list[], int nitems, struct sigevent *sevp); int gaisuspend(struct gaicb *list[], int nitems, struct timespec *timeout); int gaierror(struct gaicb *req); int gaicancel(struct gaicb *req); Link with -lanl. DESCRIPTION The getaddrinfoa() function performs the same task as getaddrinfo(3),
but allows multiple name look-ups to be performed asynchronously, with
optional notification on completion of look-up operations. The mode argument has one of the following values: GAIWAIT
Perform the look-ups synchronously. The call blocks until the
look-ups have completed. GAINOWAIT
Perform the look-ups asynchronously. The call returns immedi‐ ately, and the requests are resolved in the background. See the discussion of the sevp argument below.
The array list specifies the look-up requests to process. The nitems
argument specifies the number of elements in list. The requested look- up operations are started in parallel. NULL elements in list are ignored. Each request is described by a gaicb structure, defined as follows: struct gaicb { const char *arname; const char *arservice; const struct addrinfo *arrequest; struct addrinfo *arresult; }; The elements of this structure correspond to the arguments of getad‐ drinfo(3). Thus, arname corresponds to the node argument and arser‐ vice to the service argument, identifying an Internet host and a ser‐ vice. The arrequest element corresponds to the hints argument, speci‐ fying the criteria for selecting the returned socket address struc‐ tures. Finally, arresult corresponds to the res argument; you do not need to initialize this element, it will be automatically set when the request is resolved. The addrinfo structure referenced by the last two elements is described in getaddrinfo(3). When mode is specified as GAINOWAIT, notifications about resolved requests can be obtained by employing the sigevent structure pointed to by the sevp argument. For the definition and general details of this
structure, see sigevent(7). The sevp->sigevnotify field can have the following values: SIGEVNONE Don't provide any notification. SIGEVSIGNAL
When a look-up completes, generate the signal sigevsigno for the process. See sigevent(7) for general details. The sicode field of the siginfot structure will be set to SIASYNCNL. SIGEVTHREAD
When a look-up completes, invoke sigevnotifyfunction as if it were the start function of a new thread. See sigevent(7) for details. For SIGEVSIGNAL and SIGEVTHREAD, it may be useful to point
sevp->sigevvalue.sivalptr to list. The gaisuspend() function suspends execution of the calling thread, waiting for the completion of one or more requests in the array list. The nitems argument specifies the size of the array list. The call blocks until one of the following occurs: * One or more of the operations in list completes. * The call is interrupted by a signal that is caught. * The time interval specified in timeout elapses. This argument spec‐ ifies a timeout in seconds plus nanoseconds (see nanosleep(2) for details of the timespec structure). If timeout is NULL, then the call blocks indefinitely (until one of the events above occurs). No explicit indication of which request was completed is given; you must determine which request(s) have completed by iterating with gaierror() over the list of requests. The gaierror() function returns the status of the request req: either EAIINPROGRESS if the request was not completed yet, 0 if it was han‐ dled successfully, or an error code if the request could not be resolved. The gaicancel() function cancels the request req. If the request has been canceled successfully, the error status of the request will be set to EAICANCELLED and normal asynchronous notification will be per‐ formed. The request cannot be canceled if it is currently being pro‐ cessed; in that case, it will be handled as if gaicancel() has never been called. If req is NULL, an attempt is made to cancel all out‐ standing requests that the process has made. RETURN VALUE The getaddrinfoa() function returns 0 if all of the requests have been enqueued successfully, or one of the following nonzero error codes: EAIAGAIN
The resources necessary to enqueue the look-up requests were not available. The application may check the error status of each request to determine which ones failed. EAIMEMORY Out of memory. EAISYSTEM mode is invalid. The gaisuspend() function returns 0 if at least one of the listed requests has been completed. Otherwise, it returns one of the follow‐ ing nonzero error codes: EAIAGAIN The given timeout expired before any of the requests could be completed. EAIALLDONE There were no actual requests given to the function. EAIINTR A signal has interrupted the function. Note that this interrup‐ tion might have been caused by signal notification of some com‐
pleted look-up request. The gaierror() function can return EAIINPROGRESS for an unfinished
look-up request, 0 for a successfully completed look-up (as described above), one of the error codes that could be returned by getad‐ drinfo(3), or the error code EAICANCELLED if the request has been can‐ celed explicitly before it could be finished. The gaicancel() function can return one of these values: EAICANCELLED The request has been canceled successfully. EAINOTCANCELLED The request has not been canceled. EAIALLDONE The request has already completed. The gaistrerror(3) function translates these error codes to a human readable string, suitable for error reporting. CONFORMING TO These functions are GNU extensions; they first appeared in glibc in version 2.2.3. NOTES The interface of getaddrinfoa() was modeled after the liolistio(3) interface. EXAMPLE Two examples are provided: a simple example that resolves several requests in parallel synchronously, and a complex example showing some of the asynchronous capabilities. Synchronous example The program below simply resolves several hostnames in parallel, giving
a speed-up compared to resolving the hostnames sequentially using getaddrinfo(3). The program might be used like this:
$ ./a.out ftp.us.kernel.org enoent.linuxfoundation.org gnu.cz ftp.us.kernel.org: 128.30.2.36 enoent.linuxfoundation.org: Name or service not known gnu.cz: 87.236.197.13 Here is the program source code
#define GNUSOURCE
#include
#include
#include
#include
int main(int argc, char *argv[]) { int i, ret; struct gaicb *reqs[argc - 1]; char host[NIMAXHOST]; struct addrinfo *res; if (argc < 2) {
fprintf(stderr, "Usage: %s HOST...\n", argv[0]); exit(EXITFAILURE); }
for (i = 0; i < argc - 1; i++) { reqs[i] = malloc(sizeof(*reqs[0])); if (reqs[i] == NULL) { perror("malloc"); exit(EXITFAILURE); } memset(reqs[i], 0, sizeof(*reqs[0]));
reqs[i]->arname = argv[i + 1]; }
ret = getaddrinfoa(GAIWAIT, reqs, argc - 1, NULL); if (ret != 0) {
fprintf(stderr, "getaddrinfoa() failed: %s\n", gaistrerror(ret)); exit(EXITFAILURE); }
for (i = 0; i < argc - 1; i++) {
printf("%s: ", reqs[i]->arname); ret = gaierror(reqs[i]); if (ret == 0) {
res = reqs[i]->arresult;
ret = getnameinfo(res->aiaddr, res->aiaddrlen, host, sizeof(host), NULL, 0, NINUMERICHOST); if (ret != 0) {
fprintf(stderr, "getnameinfo() failed: %s\n", gaistrerror(ret)); exit(EXITFAILURE); } puts(host); } else { puts(gaistrerror(ret)); } } exit(EXITSUCCESS); } Asynchronous example
This example shows a simple interactive getaddrinfoa() front-end. The notification facility is not demonstrated. An example session might look like this:
$ ./a.out > a ftp.us.kernel.org enoent.linuxfoundation.org gnu.cz > c 2 [2] gnu.cz: Request not canceled > w 0 1 [00] ftp.us.kernel.org: Finished > l [00] ftp.us.kernel.org: 216.165.129.139 [01] enoent.linuxfoundation.org: Processing request in progress [02] gnu.cz: 87.236.197.13 > l [00] ftp.us.kernel.org: 216.165.129.139 [01] enoent.linuxfoundation.org: Name or service not known [02] gnu.cz: 87.236.197.13 The program source is as follows:
#define GNUSOURCE
#include
#include
#include
#include
static struct gaicb **reqs = NULL; static int nreqs = 0; static char * getcmd(void) { static char buf[256]; fputs("> ", stdout); fflush(stdout); if (fgets(buf, sizeof(buf), stdin) == NULL) return NULL; if (buf[strlen(buf) - 1] == '\n')
buf[strlen(buf) - 1] = 0; return buf; } /* Add requests for specified hostnames */ static void addrequests(void) { int nreqsbase = nreqs; char *host; int ret; while ((host = strtok(NULL, " "))) { nreqs++; reqs = realloc(reqs, nreqs * sizeof(reqs[0]));
reqs[nreqs - 1] = calloc(1, sizeof(*reqs[0]));
reqs[nreqs - 1]->arname = strdup(host); } /* Queue nreqsbase..nreqs requests. */ ret = getaddrinfoa(GAINOWAIT, &reqs[nreqsbase],
nreqs - nreqsbase, NULL); if (ret) {
fprintf(stderr, "getaddrinfoa() failed: %s\n", gaistrerror(ret)); exit(EXITFAILURE); } } /* Wait until at least one of specified requests completes */ static void waitrequests(void) { char *id; int i, ret, n; struct gaicb const **waitreqs = calloc(nreqs, sizeof(*waitreqs)); /* NULL elements are ignored by gaisuspend(). */ while ((id = strtok(NULL, " ")) != NULL) { n = atoi(id); if (n >= nreqs) {
printf("Bad request number: %s\n", id); return; } waitreqs[n] = reqs[n]; } ret = gaisuspend(waitreqs, nreqs, NULL); if (ret) {
printf("gaisuspend(): %s\n", gaistrerror(ret)); return; } for (i = 0; i < nreqs; i++) { if (waitreqs[i] == NULL) continue; ret = gaierror(reqs[i]); if (ret == EAIINPROGRESS) continue;
printf("[%02d] %s: %s\n", i, reqs[i]->arname, ret == 0 ? "Finished" : gaistrerror(ret)); } } /* Cancel specified requests */ static void cancelrequests(void) { char *id; int ret, n; while ((id = strtok(NULL, " ")) != NULL) { n = atoi(id); if (n >= nreqs) {
printf("Bad request number: %s\n", id); return; } ret = gaicancel(reqs[n]);
printf("[%s] %s: %s\n", id, reqs[atoi(id)]->arname, gaistrerror(ret)); } } /* List all requests */ static void listrequests(void) { int i, ret; char host[NIMAXHOST]; struct addrinfo *res; for (i = 0; i < nreqs; i++) {
printf("[%02d] %s: ", i, reqs[i]->arname); ret = gaierror(reqs[i]); if (!ret) {
res = reqs[i]->arresult;
ret = getnameinfo(res->aiaddr, res->aiaddrlen, host, sizeof(host), NULL, 0, NINUMERICHOST); if (ret) {
fprintf(stderr, "getnameinfo() failed: %s\n", gaistrerror(ret)); exit(EXITFAILURE); } puts(host); } else { puts(gaistrerror(ret)); } } } int main(int argc, char *argv[]) { char *cmdline; char *cmd; while ((cmdline = getcmd()) != NULL) { cmd = strtok(cmdline, " "); if (cmd == NULL) { listrequests(); } else { switch (cmd[0]) { case 'a': addrequests(); break; case 'w': waitrequests(); break; case 'c': cancelrequests(); break; case 'l': listrequests(); break; default:
fprintf(stderr, "Bad command: %c\n", cmd[0]); break; } } } exit(EXITSUCCESS); } SEE ALSO getaddrinfo(3), inet(3), liolistio(3), hostname(7), ip(7), sigevent(7) COLOPHON
This page is part of release 3.53 of the Linux man-pages project. A description of the project, and information about reporting bugs, can
be found at http://www.kernel.org/doc/man-pages/.
GNU 2010-09-27 GETADDRINFOA(3)