LDP
/
man-pages
mirror of https://github.com/mkerrisk/man-pages
0
1
Fork 0
Code Releases Activity

getaddrinfo.3: Document results ordering and /etc/gai.conf 

This patch documents the order of the getaddrinfo(3) results
(RFC 3484), how should the application deal with that,
mentions the extremely common cause of having multiple
results per query (both IPv4 and IPv6 addresses available)
and mentions /etc/gai.conf.

(mtk: Minor tweaks, and note glibc version for /etc/gai.conf)

Signed-off-by: Petr Baudis <pasky@suse.cz>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
This commit is contained in:
Petr Baudis 2008-12-05 12:07:00 -05:00 committed by Michael Kerrisk
parent a2f86747f1
commit 00269a5a24
1 changed files with 20 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

23
man3/getaddrinfo.3
View File

@ -33,10 +33,12 @@
.\" 2008-02-26, mtk; clarify discussion of NULL 'hints' argument; other
.\" minor rewrites.
.\" 2008-06-18, mtk: many parts rewritten
.\" 2008-12-04, Petr Baudis <pasky@suse.cz>
.\" Describe results ordering and reference /etc/gai.conf.
.\" FIXME . glibc's 2.9 NEWS file documents DCCP and UDP-lite support
.\" and is SCTP support now also there?
.\"
.TH GETADDRINFO 3 2008-10-28 "GNU" "Linux Programmer's Manual"
.TH GETADDRINFO 3 2008-12-04 "GNU" "Linux Programmer's Manual"
.SH NAME
getaddrinfo, freeaddrinfo, gai_strerror \- network address and
service translation
@ -293,15 +295,28 @@ and returns a pointer to the start of the list in
The items in the linked list are linked by the
.I ai_next
field.
There are several reasons why
the linked list may have more than one
.I addrinfo
structure, including: the network host is multi-homed; or the same service
is available from multiple socket protocols (one
structure, including: the network host is multi-homed, accessible
over multiple protocols (e.g. both
.BR AF_INET
and
.BR AF_INET6 );
or the same service is available from multiple socket types (one
.B SOCK_STREAM
address and another
.B SOCK_DGRAM
address, for example).
Normally, the application should try
using the addresses in the order in which they are returned.
The sorting function used within
.BR getaddrinfo ()
is defined in RFC\ 3484; the order can be tweaked for a particular
system by editing
.IR /etc/gai.conf
(available since glibc 2.5).
.PP
If
.I hints.ai_flags
@ -558,6 +573,8 @@ The
.BR gai_strerror ()
function translates these error codes to a human readable string,
suitable for error reporting.
.SH "FILES"
.I /etc/gai.conf
.SH "CONFORMING TO"
POSIX.1-2001.
The