.\" Copyright (c) 2009 Petr Baudis <pasky@suse.cz>
-.\" and clean-ups and additions (C) 2010 Michael Kerrisk <mtk.manpages@gmail.com>
+.\" and clean-ups and additions (C) Copyright 2010 Michael Kerrisk
+.\" <mtk.manpages@gmail.com>
.\"
+.\" %%%LICENSE_START(VERBATIM)
.\" Permission is granted to make and distribute verbatim copies of this
.\" manual provided the copyright notice and this permission notice are
.\" preserved on all copies.
.\"
.\" Formatted or processed versions of this manual, if unaccompanied by
.\" the source, must acknowledge the copyright and authors of this work.
+.\" %%%LICENSE_END
.\"
.\" References: http://people.redhat.com/drepper/asynchnl.pdf,
.\" http://www.imperialviolet.org/2005/06/01/asynchronous-dns-lookups-with-glibc.html
.\"
-.TH GETADDRINFO_A 3 2010-09-27 "GNU" "Linux Programmer's Manual"
+.TH GETADDRINFO_A 3 2017-09-15 "GNU" "Linux Programmer's Manual"
.SH NAME
getaddrinfo_a, gai_suspend, gai_error, gai_cancel \- asynchronous
network address and service translation
.SH SYNOPSIS
.nf
-.B #define _GNU_SOURCE
+.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
.B #include <netdb.h>
-.sp
+.PP
.BI "int getaddrinfo_a(int " "mode" ", struct gaicb *" "list[]" ,
.BI " int " "nitems" ", struct sigevent *" "sevp" );
-.sp
-.BI "int gai_suspend(struct gaicb *" "list[]" ", int " "nitems" ,
-.BI " struct timespec *" "timeout" );
-.sp
+.PP
+.BI "int gai_suspend(const struct gaicb * const " "list[]" ", int " "nitems" ,
+.BI " const struct timespec *" "timeout" );
+.PP
.BI "int gai_error(struct gaicb *" "req" );
-.sp
+.PP
.BI "int gai_cancel(struct gaicb *" "req" );
-.sp
+.PP
Link with \fI\-lanl\fP.
.fi
.SH DESCRIPTION
.BR getaddrinfo (3),
but allows multiple name look-ups to be performed asynchronously,
with optional notification on completion of look-up operations.
-
+.PP
The
.I mode
argument has one of the following values:
.TP
.B GAI_WAIT
-Perform the look-ups synchronously;
-the call blocks until the look-ups have completed.
+Perform the look-ups synchronously.
+The call blocks until the look-ups have completed.
.TP
.B GAI_NOWAIT
Perform the look-ups asynchronously.
Each request is described by a
.I gaicb
structure, defined as follows:
-.sp
+.PP
.in +4n
-.nf
+.EX
struct gaicb {
const char *ar_name;
const char *ar_service;
const struct addrinfo *ar_request;
struct addrinfo *ar_result;
};
-.fi
+.EE
.in
-
+.PP
The elements of this structure correspond to the arguments of
.BR getaddrinfo (3).
Thus,
.I addrinfo
structure referenced by the last two elements is described in
.BR getaddrinfo (3).
-
+.PP
When
.I mode
is specified as
-.BR GAI_NOWAIT,
+.BR GAI_NOWAIT ,
notifications about resolved requests
can be obtained by employing the
.I sigevent
.IR sevp\->sigev_value.sival_ptr
to
.IR list .
-
+.PP
The
.BR gai_suspend ()
function suspends execution of the calling thread,
you must determine which request(s) have completed by iterating with
.BR gai_error ()
over the list of requests.
-
+.PP
The
.BR gai_error ()
function returns the status of the request
if the request was not completed yet,
0 if it was handled successfully,
or an error code if the request could not be resolved.
-
+.PP
The
.BR gai_cancel ()
function cancels the request
.IR req .
If the request has been canceled successfully,
the error status of the request will be set to
-.B EAI_CANCELLED
+.B EAI_CANCELED
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
.I req
is NULL, an attempt is made to cancel all outstanding requests
that the process has made.
-.SH "RETURN VALUE"
+.SH RETURN VALUE
The
.BR getaddrinfo_a ()
function returns 0 if all of the requests have been enqueued successfully,
(as described above), one of the error codes that could be returned by
.BR getaddrinfo (3),
or the error code
-.B EAI_CANCELLED
+.B EAI_CANCELED
if the request has been canceled explicitly before it could be finished.
-
+.PP
The
.BR gai_cancel ()
function can return one of these values:
.TP
-.B EAI_CANCELLED
+.B EAI_CANCELED
The request has been canceled successfully.
.TP
-.B EAI_NOTCANCELLED
+.B EAI_NOTCANCELED
The request has not been canceled.
.TP
.B EAI_ALLDONE
.BR gai_strerror (3)
function translates these error codes to a human readable string,
suitable for error reporting.
-.SH "CONFORMING TO"
+.SH ATTRIBUTES
+For an explanation of the terms used in this section, see
+.BR attributes (7).
+.TS
+allbox;
+lbw31 lb lb
+l l l.
+Interface Attribute Value
+T{
+.BR getaddrinfo_a (),
+.BR gai_suspend (),
+.BR gai_error (),
+.BR gai_cancel ()
+T} Thread safety MT-Safe
+.TE
+.sp 1
+.SH CONFORMING TO
These functions are GNU extensions;
they first appeared in glibc in version 2.2.3.
.SH NOTES
Two examples are provided: a simple example that resolves
several requests in parallel synchronously, and a complex example
showing some of the asynchronous capabilities.
-.SS Synchronous Example
+.SS Synchronous example
The program below simply resolves several hostnames in parallel,
giving a speed-up compared to resolving the hostnames sequentially using
.BR getaddrinfo (3).
The program might be used like this:
+.PP
.in +4n
-.nf
-
+.EX
$ \fB./a.out ftp.us.kernel.org enoent.linuxfoundation.org gnu.cz\fP
ftp.us.kernel.org: 128.30.2.36
enoent.linuxfoundation.org: Name or service not known
gnu.cz: 87.236.197.13
-.fi
+.EE
.in
.PP
Here is the program source code
-.nf
-
+.PP
+.EX
#define _GNU_SOURCE
#include <netdb.h>
#include <stdio.h>
}
exit(EXIT_SUCCESS);
}
-.fi
-
-.SS Asynchronous Example
+.EE
+.SS Asynchronous example
This example shows a simple interactive
.BR getaddrinfo_a ()
front-end.
The notification facility is not demonstrated.
.PP
-An example session might look like like this:
+An example session might look like this:
+.PP
.in +4n
-.nf
-
+.EX
$ \fB./a.out\fP
> a ftp.us.kernel.org enoent.linuxfoundation.org gnu.cz
> c 2
[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
-.fi
+.EE
.in
.PP
-The program source goes as follows:
-
-\&
-.nf
+The program source is as follows:
+.PP
+.EX
#define _GNU_SOURCE
#include <netdb.h>
#include <stdio.h>
}
exit(EXIT_SUCCESS);
}
-.fi
-.SH "SEE ALSO"
+.EE
+.SH SEE ALSO
.BR getaddrinfo (3),
.BR inet (3),
.BR lio_listio (3),
projects / thirdparty / man-pages.git / blobdiff