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

PATCH In review Petr Baudis 2 participants 4 messages Dec 4, 2008 – Dec 5, 2008 3 messages not in the archive Man-pages: manual pages for Linux -- Sections 2, 3, 4, 5, and 7

lore

Share & tools

lore

Petr Baudis

author

2008-12-04 23:22 UTC #0 lore raw

PATCH 1/1 man3/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.

Signed-off-by Petr Baudis <[email protected]>

man3/getaddrinfo.3 +19 -4

index b3b0cce..e1f1f9c 100644
@@ -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 <[email protected]>
+.\"	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,26 @@ 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.
+.PP
 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).
+address, for example).  Normally, the application should try
+using the addresses in the order they are returned in.
+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 .
 .PP
 If
 .I hints.ai_flags

@@ -558,6 +571,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

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html

A message that is not in the archive (sent off-list or not yet received): [email protected]

Michael Kerrisk

2008-12-05 17:09 UTC #2 lore raw

Hi Petr,

Quoted 4 lines · Petr Baudis

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.

Thanks for this! I've applied this for 3.15, but with tweaks as noted below.

man3/getaddrinfo.3 line 37

Quoted 12 lines

Signed-off-by Petr Baudis <[email protected]>

man3/getaddrinfo.3 +2 -0

index b3b0cce..e1f1f9c 100644
@@ -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 <[email protected]>
+.\"    Describe results ordering and reference /etc/gai.conf.

Yep. This is a case where in-source changelog makes sense.

man3/getaddrinfo.3 and returns a pointer to the start of the list in · line 298

Quoted 13 lines

man3/getaddrinfo.3 +2 -1

 .\" 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,26 @@ 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.
+.PP

This change is not relevant to the subject of the patch, and unneeded. Dropped.

Quoted 6 lines

man3/getaddrinfo.3 +1 -2

 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

man3/getaddrinfo.3 and returns a pointer to the start of the list in · line 311

Quoted 10 lines

man3/getaddrinfo.3 +6 -1

+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).
+address, for example).  Normally, the application should try

My preference (see man-pages(7) is to start new sentences on new line.
This is because (later) diffs at least sometimes operate at the
sentence level.

man3/getaddrinfo.3 and returns a pointer to the start of the list in · line 317

Quoted 6 lines

man3/getaddrinfo.3 +6 -0

+using the addresses in the order they are returned in.
+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 .

Here, it is good to mention the glibc version that first started supporting gai.conf. It looks like it was 2.5, and I've added that information.

man3/getaddrinfo.3 The · line 578

Quoted 12 lines

man3/getaddrinfo.3 +2 -0

 .PP
 If
 .I hints.ai_flags

@@ -558,6 +571,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

Thanks!

Michael

Signature · 9 lines

Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
git://git.kernel.org/pub/scm/docs/man-pages/man-pages.git
man-pages online: http://www.kernel.org/doc/man-pages/online_pages.html
Found a bug? http://www.kernel.org/doc/man-pages/reporting_bugs.html
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to [email protected]
More majordomo info at  http://vger.kernel.org/majordomo-info.html

A message that is not in the archive (sent off-list or not yet received): cfd18e0f0812050909o3556a118p25138870a3745ad8-JsoAwUIsXosN+BqQ9rBEUg@public.gmane.org

Petr Baudis

author

2008-12-05 17:15 UTC #4 lore raw

Hi,

Quoted 9 lines · Michael Kerrisk

Hi Petr,
Quoted 4 lines · Petr Baudis
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.
Thanks for this! I've applied this for 3.15, but with tweaks as noted below.

thanks! (Purely out of curiosity, how often do you push out your git
tree? Only on releases?)

Quoted 7 lines

man3/getaddrinfo.3 and returns a pointer to the start of the list in · line 298
Quoted 5 lines
man3/getaddrinfo.3 +1 -0
@@ -293,15 +295,26 @@ 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.
+.PP
This change is not relevant to the subject of the patch, and unneeded. Dropped.

I simply think that with the addition, the whole paragraph is too big
and hard to read. But this is of course matter of personal preference.

Quoted 12 lines

man3/getaddrinfo.3 +6 -2

 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

Quoted 8 lines

man3/getaddrinfo.3 and returns a pointer to the start of the list in · line 311
Quoted 4 lines
man3/getaddrinfo.3 +1 -1
 address and another
 .B SOCK_DGRAM
-address, for example).
+address, for example).  Normally, the application should try
My preference (see man-pages(7) is to start new sentences on new line.
This is because (later) diffs at least sometimes operate at the
sentence level.

Thanks, I did not actually read man-pages(7) yet, I will do that.

Quoted 10 lines

man3/getaddrinfo.3 and returns a pointer to the start of the list in · line 317
Quoted 6 lines
man3/getaddrinfo.3 +6 -0
+using the addresses in the order they are returned in.
+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 .
Here, it is good to mention the glibc version that first started supporting gai.conf. It looks like it was 2.5, and I've added that information.

Yes, glibc-2.5 introduced this.

Signature · 7 lines

				Petr "Pasky" Baudis
People who take cold baths never have rheumatism, but they have
cold baths.
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to [email protected]
More majordomo info at  http://vger.kernel.org/majordomo-info.html

A message that is not in the archive (sent off-list or not yet received): [email protected]

Michael Kerrisk

2008-12-05 17:23 UTC #6 lore raw

Hi Petr,

Quoted 11 lines · Petr Baudis

Hi,
Quoted 8 lines · Michael Kerrisk
Hi Petr,
Quoted 4 lines · Petr Baudis
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.

Quoted 4 lines

Quoted 1 line
Thanks for this! I've applied this for 3.15, but with tweaks as noted below.
thanks! (Purely out of curiosity, how often do you push out your git
tree? Only on releases?)

It varies. (Maybe I don't push it out quite as often as I should. I'm open to input on that point.) It does get pushed out at least on every release, and I try to do it mor often if there's a lot of stuff since the last push.

Quoted 9 lines

Quoted 7 lines
man3/getaddrinfo.3 and returns a pointer to the start of the list in · line 298
Quoted 5 lines
man3/getaddrinfo.3 +1 -0
@@ -293,15 +295,26 @@ 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.
+.PP
This change is not relevant to the subject of the patch, and unneeded. Dropped.
I simply think that with the addition, the whole paragraph is too big
and hard to read. But this is of course matter of personal preference.

D'oh! I agree. Changed now.

Quoted 21 lines

Quoted 12 lines
Quoted 12 lines
man3/getaddrinfo.3 +6 -2
 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
Quoted 8 lines
man3/getaddrinfo.3 and returns a pointer to the start of the list in · line 311
Quoted 4 lines
man3/getaddrinfo.3 +1 -1
 address and another
 .B SOCK_DGRAM
-address, for example).
+address, for example).  Normally, the application should try
My preference (see man-pages(7) is to start new sentences on new line.
This is because (later) diffs at least sometimes operate at the
sentence level.

Quoted 1 line

Thanks, I did not actually read man-pages(7) yet, I will do that.

Thanks.

Quoted 11 lines

Quoted 10 lines
man3/getaddrinfo.3 and returns a pointer to the start of the list in · line 317
Quoted 6 lines
man3/getaddrinfo.3 +6 -0
+using the addresses in the order they are returned in.
+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 .
Here, it is good to mention the glibc version that first started supporting gai.conf. It looks like it was 2.5, and I've added that information.

Quoted 1 line

Yes, glibc-2.5 introduced this.

Thanks for the ACK.

Cheers,

Michael

Signature · 9 lines

Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
git://git.kernel.org/pub/scm/docs/man-pages/man-pages.git
man-pages online: http://www.kernel.org/doc/man-pages/online_pages.html
Found a bug? http://www.kernel.org/doc/man-pages/reporting_bugs.html
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to [email protected]
More majordomo info at  http://vger.kernel.org/majordomo-info.html