[src/trunk]: src/lib/libc/net getaddrinfo is defined to use the AF_* constant...

[dholland <dholland%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/2278f8b6d62f
branches:  trunk
changeset: 749998:2278f8b6d62f
user:      dholland <dholland%NetBSD.org@localhost>
date:      Mon Dec 14 01:53:31 2009 +0000

description:
getaddrinfo is defined to use the AF_* constants, even though perhaps its
interface ought to have been defined in terms of PF_*. Add a note about
how the distinction has been lost anyway. Fixes PR lib/42384.

diffstat:

 lib/libc/net/getaddrinfo.3 |  33 +++++++++++++++++++++++++--------
 1 files changed, 25 insertions(+), 8 deletions(-)

diffs (79 lines):

diff -r 755a8f6b71e2 -r 2278f8b6d62f lib/libc/net/getaddrinfo.3
--- a/lib/libc/net/getaddrinfo.3        Mon Dec 14 01:48:34 2009 +0000
+++ b/lib/libc/net/getaddrinfo.3        Mon Dec 14 01:53:31 2009 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: getaddrinfo.3,v 1.50 2009/10/02 07:41:08 wiz Exp $
+.\"    $NetBSD: getaddrinfo.3,v 1.51 2009/12/14 01:53:31 dholland Exp $
 .\"    $KAME: getaddrinfo.3,v 1.36 2005/01/05 03:23:05 itojun Exp $
 .\"    $OpenBSD: getaddrinfo.3,v 1.35 2004/12/21 03:40:31 jaredy Exp $
 .\"
@@ -77,7 +77,7 @@
 .Bd -literal
 struct addrinfo {
        int ai_flags;           /* input flags */
-       int ai_family;          /* protocol family for socket */
+       int ai_family;          /* address family for socket */
        int ai_socktype;        /* socket type */
        int ai_protocol;        /* protocol for socket */
        socklen_t ai_addrlen;   /* length of socket-address */
@@ -93,13 +93,30 @@
 .Fa hints :
 .Bl -tag -width "ai_socktypeXX"
 .It Fa ai_family
-The protocol family that should be used.
+The address
+.Pq and protocol
+family that should be used.
 When
 .Fa ai_family
 is set to
-.Dv PF_UNSPEC ,
-it means the caller will accept any protocol family supported by the
+.Dv AF_UNSPEC ,
+it means the caller will accept any address family supported by the
 operating system.
+Note that while address families
+.Pq Dv AF_*
+and protocol families
+.Pq Dv PF_*
+are theoretically distinct, in practice the distinction has been lost.
+.\" (.Dv !? Consistent with usage below though...)
+.Dv "RFC 3493"
+defines
+.Fn getaddrinfo
+in terms of the address family constants
+.Dv AF_*
+even though
+.Fa ai_family
+is to be passed as a protocol family to
+.Xr socket 2 .
 .It Fa ai_socktype
 Denotes the type of socket that is wanted:
 .Dv SOCK_STREAM ,
@@ -200,7 +217,7 @@
 with
 .Fa ai_family
 set to
-.Dv PF_UNSPEC
+.Dv AF_UNSPEC
 and all other elements set to zero or
 .Dv NULL .
 .Pp
@@ -341,7 +358,7 @@
 const char *cause = NULL;
 
 memset(\*[Am]hints, 0, sizeof(hints));
-hints.ai_family = PF_UNSPEC;
+hints.ai_family = AF_UNSPEC;
 hints.ai_socktype = SOCK_STREAM;
 error = getaddrinfo("www.kame.net", "http", \*[Am]hints, \*[Am]res0);
 if (error) {
@@ -384,7 +401,7 @@
 const char *cause = NULL;
 
 memset(\*[Am]hints, 0, sizeof(hints));
-hints.ai_family = PF_UNSPEC;
+hints.ai_family = AF_UNSPEC;
 hints.ai_socktype = SOCK_STREAM;
 hints.ai_flags = AI_PASSIVE;
 error = getaddrinfo(NULL, "http", \*[Am]hints, \*[Am]res0);