{"id":6834,"date":"2022-12-20T19:33:42","date_gmt":"2022-12-20T22:33:42","guid":{"rendered":"http:\/\/lode.uno\/linux-man\/index.php\/2022\/12\/20\/getaddrinfo_a-man3\/"},"modified":"2022-12-20T19:33:42","modified_gmt":"2022-12-20T22:33:42","slug":"getaddrinfo_a-man3","status":"publish","type":"post","link":"https:\/\/lode.uno\/linux-man\/2022\/12\/20\/getaddrinfo_a-man3\/","title":{"rendered":"GETADDRINFO_A (man3)"},"content":{"rendered":"

GETADDRINFO_A<\/h1>\n

NAME<\/a>
SYNOPSIS<\/a>
DESCRIPTION<\/a>
RETURN VALUE<\/a>
ATTRIBUTES<\/a>
CONFORMING TO<\/a>
NOTES<\/a>
EXAMPLES<\/a>
SEE ALSO<\/a>
COLOPHON<\/a> <\/p>\n

\n

NAME <\/a> <\/h2>\n

getaddrinfo_a, gai_suspend, gai_error, gai_cancel \u2212 asynchronous network address and service translation<\/p>\n

SYNOPSIS <\/a> <\/h2>\n

#define _GNU_SOURCE<\/b> \/bin \/boot \/dead.letter \/dev \/etc \/home \/initrd \/lib \/lib64 \/lost+found \/media \/mnt \/opt \/proc \/release-notes.html \/release-notes.txt \/root \/run \/sbin \/srv \/sys \/tmp \/usr \/var See feature_test_macros(7) bodies\/ usr\/
#include <\/b><\/p>\n

int getaddrinfo_a(int<\/b> mode<\/i>, struct gaicb *<\/b>list[]<\/i>,
int<\/b> nitems<\/i>, struct sigevent *<\/b>sevp<\/i>);<\/b><\/p>\n

int gai_suspend(const struct gaicb bodies manpages.csv script_extrae_body.sh script.sh usr const<\/b> list[]<\/i>, int<\/b> nitems<\/i>,
const struct timespec *<\/b>timeout<\/i>);<\/b><\/p>\n

int gai_error(struct gaicb *<\/b>req<\/i>);<\/b><\/p>\n

int gai_cancel(struct gaicb *<\/b>req<\/i>);<\/b><\/p>\n

Link with \u2212lanl<\/i>.<\/p>\n

DESCRIPTION <\/a> <\/h2>\n

The getaddrinfo_a<\/b>() function performs the same task as getaddrinfo<\/b>(3), but allows multiple name look-ups to be performed asynchronously, with optional notification on completion of look-up operations.<\/p>\n

The mode<\/i> argument has one of the following values:
GAI_WAIT<\/b><\/p>\n

Perform the look-ups synchronously. The call blocks until the look-ups have completed.<\/p>\n

GAI_NOWAIT<\/b><\/p>\n

Perform the look-ups asynchronously. The call returns immediately, and the requests are resolved in the background. See the discussion of the sevp<\/i> argument below.<\/p>\n

The array list<\/i> specifies the look-up requests to process. The nitems<\/i> argument specifies the number of elements in list<\/i>. The requested look-up operations are started in parallel. NULL elements in list<\/i> are ignored. Each request is described by a gaicb<\/i> structure, defined as follows:<\/p>\n

struct gaicb {
const char *ar_name;
const char *ar_service;
const struct addrinfo *ar_request;
struct addrinfo *ar_result;
};<\/p>\n

The elements of this structure correspond to the arguments of getaddrinfo<\/b>(3). Thus, ar_name<\/i> corresponds to the node<\/i> argument and ar_service<\/i> to the service<\/i> argument, identifying an Internet host and a service. The ar_request<\/i> element corresponds to the hints<\/i> argument, specifying the criteria for selecting the returned socket address structures. Finally, ar_result<\/i> corresponds to the res<\/i> argument; you do not need to initialize this element, it will be automatically set when the request is resolved. The addrinfo<\/i> structure referenced by the last two elements is described in getaddrinfo<\/b>(3).<\/p>\n

When mode<\/i> is specified as GAI_NOWAIT<\/b>, notifications about resolved requests can be obtained by employing the sigevent<\/i> structure pointed to by the sevp<\/i> argument. For the definition and general details of this structure, see sigevent<\/b>(7). The sevp\u2212>sigev_notify<\/i> field can have the following values:
SIGEV_NONE<\/b><\/p>\n

Don\u2019t provide any notification.<\/p>\n

SIGEV_SIGNAL<\/b><\/p>\n

When a look-up completes, generate the signal sigev_signo<\/i> for the process. See sigevent<\/b>(7) for general details. The si_code<\/i> field of the siginfo_t<\/i> structure will be set to SI_ASYNCNL<\/b>.<\/p>\n

SIGEV_THREAD<\/b><\/p>\n

When a look-up completes, invoke sigev_notify_function<\/i> as if it were the start function of a new thread. See sigevent<\/b>(7) for details.<\/p>\n

For SIGEV_SIGNAL<\/b> and SIGEV_THREAD<\/b>, it may be useful to point sevp\u2212>sigev_value.sival_ptr<\/i> to list<\/i>.<\/p>\n

The gai_suspend<\/b>() function suspends execution of the calling thread, waiting for the completion of one or more requests in the array list<\/i>. The nitems<\/i> argument specifies the size of the array list<\/i>. The call blocks until one of the following occurs:<\/p>\n\n\n\n\n
<\/td>\n\n

*<\/p>\n<\/td>\n

<\/td>\n\n

One or more of the operations in list<\/i> completes.<\/p>\n<\/td>\n<\/tr>\n

<\/td>\n\n

*<\/p>\n<\/td>\n

<\/td>\n\n

The call is interrupted by a signal that is caught.<\/p>\n<\/td>\n<\/tr>\n

<\/td>\n\n

*<\/p>\n<\/td>\n

<\/td>\n\n

The time interval specified in timeout<\/i> elapses. This argument specifies a timeout in seconds plus nanoseconds (see nanosleep<\/b>(2) for details of the timespec<\/i> structure). If timeout<\/i> is NULL, then the call blocks indefinitely (until one of the events above occurs).<\/p>\n<\/td>\n<\/tr>\n<\/table>\n

No explicit indication of which request was completed is given; you must determine which request(s) have completed by iterating with gai_error<\/b>() over the list of requests.<\/p>\n

The gai_error<\/b>() function returns the status of the request req<\/i>: either EAI_INPROGRESS<\/b> if the request was not completed yet, 0 if it was handled successfully, or an error code if the request could not be resolved.<\/p>\n

The gai_cancel<\/b>() function cancels the request req<\/i>. If the request has been canceled successfully, the error status of the request will be set to EAI_CANCELED<\/b> and normal asynchronous notification will be performed. The request cannot be canceled if it is currently being processed; in that case, it will be handled as if gai_cancel<\/b>() has never been called. If req<\/i> is NULL, an attempt is made to cancel all outstanding requests that the process has made.<\/p>\n

RETURN VALUE <\/a> <\/h2>\n

The getaddrinfo_a<\/b>() function returns 0 if all of the requests have been enqueued successfully, or one of the following nonzero error codes:
EAI_AGAIN<\/b><\/p>\n

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.<\/p>\n

EAI_MEMORY<\/b><\/p>\n

Out of memory.<\/p>\n

EAI_SYSTEM<\/b><\/p>\n

mode<\/i> is invalid.<\/p>\n

The gai_suspend<\/b>() function returns 0 if at least one of the listed requests has been completed. Otherwise, it returns one of the following nonzero error codes:
EAI_AGAIN<\/b><\/p>\n

The given timeout expired before any of the requests could be completed.<\/p>\n

EAI_ALLDONE<\/b><\/p>\n

There were no actual requests given to the function.<\/p>\n

EAI_INTR<\/b><\/p>\n

A signal has interrupted the function. Note that this interruption might have been caused by signal notification of some completed look-up request.<\/p>\n

The gai_error<\/b>() function can return EAI_INPROGRESS<\/b> 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 getaddrinfo<\/b>(3), or the error code EAI_CANCELED<\/b> if the request has been canceled explicitly before it could be finished.<\/p>\n

The gai_cancel<\/b>() function can return one of these values:
EAI_CANCELED<\/b><\/p>\n

The request has been canceled successfully.<\/p>\n

EAI_NOTCANCELED<\/b><\/p>\n

The request has not been canceled.<\/p>\n

EAI_ALLDONE<\/b><\/p>\n

The request has already completed.<\/p>\n

The gai_strerror<\/b>(3) function translates these error codes to a human readable string, suitable for error reporting.<\/p>\n

ATTRIBUTES <\/a> <\/h2>\n

For an explanation of the terms used in this section, see attributes<\/b>(7).<\/p>\n

\"Image<\/p>\n

CONFORMING TO <\/a> <\/h2>\n

These functions are GNU extensions; they first appeared in glibc in version 2.2.3.<\/p>\n

NOTES <\/a> <\/h2>\n

The interface of getaddrinfo_a<\/b>() was modeled after the lio_listio<\/b>(3) interface.<\/p>\n

EXAMPLES <\/a> <\/h2>\n

Two examples are provided: a simple example that resolves several requests in parallel synchronously, and a complex example showing some of the asynchronous capabilities.<\/p>\n

Synchronous example<\/b>
The program below simply resolves several hostnames in parallel, giving a speed-up compared to resolving the hostnames sequentially using getaddrinfo<\/b>(3). The program might be used like this:<\/p>\n

$ .\/a.out ftp.us.kernel.org enoent.linuxfoundation.org gnu.cz<\/b>
ftp.us.kernel.org: 128.30.2.36
enoent.linuxfoundation.org: Name or service not known
gnu.cz: 87.236.197.13<\/p>\n

Here is the program source code<\/p>\n

#define _GNU_SOURCE
#include
#include
#include
#include <\/p>\n

int
main(int argc, char *argv[])
{
int ret;
struct gaicb *reqs[argc \u2212 1];
char host[NI_MAXHOST];
struct addrinfo *res;<\/p>\n

if (argc < 2) {
fprintf(stderr, “Usage: %s HOST…n”, argv[0]);
exit(EXIT_FAILURE);
}<\/p>\n

for (int i = 0; i < argc \u2212 1; i++) {
reqs[i] = malloc(sizeof(*reqs[0]));
if (reqs[i] == NULL) {
perror(“malloc”);
exit(EXIT_FAILURE);
}
memset(reqs[i], 0, sizeof(*reqs[0]));
reqs[i]\u2212>ar_name = argv[i + 1];
}<\/p>\n

ret = getaddrinfo_a(GAI_WAIT, reqs, argc \u2212 1, NULL);
if (ret != 0) {
fprintf(stderr, “getaddrinfo_a() failed: %sn”,
gai_strerror(ret));
exit(EXIT_FAILURE);
}<\/p>\n

for (int i = 0; i < argc \u2212 1; i++) {
printf(“%s: “, reqs[i]\u2212>ar_name);
ret = gai_error(reqs[i]);
if (ret == 0) {
res = reqs[i]\u2212>ar_result;<\/p>\n

ret = getnameinfo(res\u2212>ai_addr, res\u2212>ai_addrlen,
host, sizeof(host),
NULL, 0, NI_NUMERICHOST);
if (ret != 0) {
fprintf(stderr, “getnameinfo() failed: %sn”,
gai_strerror(ret));
exit(EXIT_FAILURE);
}
puts(host);<\/p>\n

} else {
puts(gai_strerror(ret));
}
}
exit(EXIT_SUCCESS);
}<\/p>\n

Asynchronous example<\/b>
This example shows a simple interactive getaddrinfo_a<\/b>() front-end. The notification facility is not demonstrated.<\/p>\n

An example session might look like this:<\/p>\n

$ .\/a.out<\/b>
> 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<\/p>\n

The program source is as follows:<\/p>\n

#define _GNU_SOURCE
#include
#include
#include
#include <\/p>\n

static struct gaicb **reqs = NULL;
static int nreqs = 0;<\/p>\n

static char bodies manpages.csv script_extrae_body.sh script.sh usr
getcmd(void)
{
static char buf[256];<\/p>\n

fputs(“> “, stdout); fflush(stdout);
if (fgets(buf, sizeof(buf), stdin) == NULL)
return NULL;<\/p>\n

if (buf[strlen(buf) \u2212 1] == ‘n’)
buf[strlen(buf) \u2212 1] = 0;<\/p>\n

return buf;
}<\/p>\n

\/* Add requests for specified hostnames bodies\/ usr\/
static void
add_requests(void)
{
int nreqs_base = nreqs;
char *host;
int ret;<\/p>\n

while ((host = strtok(NULL, ” “))) {
nreqs++;
reqs = realloc(reqs, sizeof(reqs[0]) bodies manpages.csv script_extrae_body.sh script.sh usr nreqs);<\/p>\n

reqs[nreqs \u2212 1] = calloc(1, sizeof(*reqs[0]));
reqs[nreqs \u2212 1]\u2212>ar_name = strdup(host);
}<\/p>\n

\/* Queue nreqs_base..nreqs requests. *\/<\/p>\n

ret = getaddrinfo_a(GAI_NOWAIT, &reqs[nreqs_base],
nreqs \u2212 nreqs_base, NULL);
if (ret) {
fprintf(stderr, “getaddrinfo_a() failed: %sn”,
gai_strerror(ret));
exit(EXIT_FAILURE);
}
}<\/p>\n

\/* Wait until at least one of specified requests completes bodies\/ usr\/
static void
wait_requests(void)
{
char *id;
int ret, n;
struct gaicb const **wait_reqs = calloc(nreqs, sizeof(*wait_reqs));
\/bin \/boot \/dead.letter \/dev \/etc \/home \/initrd \/lib \/lib64 \/lost+found \/media \/mnt \/opt \/proc \/release-notes.html \/release-notes.txt \/root \/run \/sbin \/srv \/sys \/tmp \/usr \/var NULL elements are ignored by gai_suspend(). *\/<\/p>\n

while ((id = strtok(NULL, ” “)) != NULL) {
n = atoi(id);<\/p>\n

if (n >= nreqs) {
printf(“Bad request number: %sn”, id);
return;
}<\/p>\n

wait_reqs[n] = reqs[n];
}<\/p>\n

ret = gai_suspend(wait_reqs, nreqs, NULL);
if (ret) {
printf(“gai_suspend(): %sn”, gai_strerror(ret));
return;
}<\/p>\n

for (int i = 0; i < nreqs; i++) {
if (wait_reqs[i] == NULL)
continue;<\/p>\n

ret = gai_error(reqs[i]);
if (ret == EAI_INPROGRESS)
continue;<\/p>\n

printf(“[%02d] %s: %sn”, i, reqs[i]\u2212>ar_name,
ret == 0 ? “Finished” : gai_strerror(ret));
}
}<\/p>\n

\/* Cancel specified requests bodies\/ usr\/
static void
cancel_requests(void)
{
char *id;
int ret, n;<\/p>\n

while ((id = strtok(NULL, ” “)) != NULL) {
n = atoi(id);<\/p>\n

if (n >= nreqs) {
printf(“Bad request number: %sn”, id);
return;
}<\/p>\n

ret = gai_cancel(reqs[n]);
printf(“[%s] %s: %sn”, id, reqs[atoi(id)]\u2212>ar_name,
gai_strerror(ret));
}
}<\/p>\n

\/* List all requests bodies\/ usr\/
static void
list_requests(void)
{
int ret;
char host[NI_MAXHOST];
struct addrinfo *res;<\/p>\n

for (int i = 0; i < nreqs; i++) {
printf(“[%02d] %s: “, i, reqs[i]\u2212>ar_name);
ret = gai_error(reqs[i]);<\/p>\n

if (!ret) {
res = reqs[i]\u2212>ar_result;<\/p>\n

ret = getnameinfo(res\u2212>ai_addr, res\u2212>ai_addrlen,
host, sizeof(host),
NULL, 0, NI_NUMERICHOST);
if (ret) {
fprintf(stderr, “getnameinfo() failed: %sn”,
gai_strerror(ret));
exit(EXIT_FAILURE);
}
puts(host);
} else {
puts(gai_strerror(ret));
}
}
}<\/p>\n

int
main(int argc, char *argv[])
{
char *cmdline;
char *cmd;<\/p>\n

while ((cmdline = getcmd()) != NULL) {
cmd = strtok(cmdline, ” “);<\/p>\n

if (cmd == NULL) {
list_requests();
} else {
switch (cmd[0]) {
case ‘a’:
add_requests();
break;
case ‘w’:
wait_requests();
break;
case ‘c’:
cancel_requests();
break;
case ‘l’:
list_requests();
break;
default:
fprintf(stderr, “Bad command: %cn”, cmd[0]);
break;
}
}
}
exit(EXIT_SUCCESS);
}<\/p>\n

SEE ALSO <\/a> <\/h2>\n

getaddrinfo<\/b>(3), inet<\/b>(3), lio_listio<\/b>(3), hostname<\/b>(7), ip<\/b>(7), sigevent<\/b>(7)<\/p>\n

COLOPHON <\/a> <\/h2>\n

This page is part of release 5.10 of the Linux man-pages<\/i> project. A description of the project, information about reporting bugs, and the latest version of this page, can be found at https:\/\/www.kernel.org\/doc\/man\u2212pages\/.<\/p>\n

\n","protected":false},"excerpt":{"rendered":"

getaddrinfo_a, gai_suspend, gai_error, gai_cancel \u2212 asynchronous network address and service translation <\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[2536],"tags":[2538,3199,3007],"class_list":["post-6834","post","type-post","status-publish","format-standard","hentry","category-3-llamadas-de-bibliotecas","tag-2538","tag-getaddrinfo_a","tag-man3"],"gutentor_comment":0,"_links":{"self":[{"href":"https:\/\/lode.uno\/linux-man\/wp-json\/wp\/v2\/posts\/6834","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/lode.uno\/linux-man\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/lode.uno\/linux-man\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/lode.uno\/linux-man\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/lode.uno\/linux-man\/wp-json\/wp\/v2\/comments?post=6834"}],"version-history":[{"count":0,"href":"https:\/\/lode.uno\/linux-man\/wp-json\/wp\/v2\/posts\/6834\/revisions"}],"wp:attachment":[{"href":"https:\/\/lode.uno\/linux-man\/wp-json\/wp\/v2\/media?parent=6834"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/lode.uno\/linux-man\/wp-json\/wp\/v2\/categories?post=6834"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/lode.uno\/linux-man\/wp-json\/wp\/v2\/tags?post=6834"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}