Date: Thu, 10 Nov 2011 11:28:12 GMT From: Mark Martinec <Mark.Martinec@ijs.si> To: freebsd-gnats-submit@FreeBSD.org Subject: standards/162434: getaddrinfo: addrinfo.ai_family is an address family, not a protocol family Message-ID: <201111101128.pAABSCbo094022@red.freebsd.org> Resent-Message-ID: <201111101130.pAABUAki008111@freefall.freebsd.org>
next in thread | raw e-mail | index | archive | help
>Number: 162434
>Category: standards
>Synopsis: getaddrinfo: addrinfo.ai_family is an address family, not a protocol family
>Confidential: no
>Severity: non-critical
>Priority: low
>Responsible: freebsd-standards
>State: open
>Quarter:
>Keywords:
>Date-Required:
>Class: doc-bug
>Submitter-Id: current-users
>Arrival-Date: Thu Nov 10 11:30:10 UTC 2011
>Closed-Date:
>Last-Modified:
>Originator: Mark Martinec
>Release: 9.0-RC2
>Organization:
Jozef Stefan Institute
>Environment:
FreeBSD xxx.ijs.si 9.0-RC2 FreeBSD 9.0-RC2 ... amd64
>Description:
There is a discrepancy in the documentation of a field "ai_family"
in "struct addrinfo" between FreeBSD (checked 8.*, 9.0) and RFC 3493
("Basic Socket Interface Extensions for IPv6", February 2003).
The RFC 3493 claims the ai_family is an address family and
constants like AF_xxx should be used. Looks like Linux also follows
this. FreeBSD claims this is a protocol family and expects PF_xxx.
Luckily the AF_xxx and corresponding PF_xxx constants have the
same value, so (I hope) that only a documentation change is needed
(in GETADDRINFO(3) man page and in /usr/include/netdb.h, possibly
elsewhere).
Note the comment by the "ai_family" in the following declarations
of struct addrinfo:
RFC 3493:
struct addrinfo {
int ai_flags; /* AI_PASSIVE, AI_CANONNAME,
AI_NUMERICHOST, .. */
int ai_family; /* AF_xxx */
int ai_socktype; /* SOCK_xxx */
int ai_protocol; /* 0 or IPPROTO_xxx for IPv4 and IPv6 */
socklen_t ai_addrlen; /* length of ai_addr */
char *ai_canonname; /* canonical name for nodename */
struct sockaddr *ai_addr; /* binary address */
struct addrinfo *ai_next; /* next structure in linked list */
};
FreeBSD 9.0 /usr/include/netdb.h :
struct addrinfo {
int ai_flags; /* AI_PASSIVE, AI_CANONNAME, AI_NUMERICHOST */
int ai_family; /* PF_xxx */
int ai_socktype; /* SOCK_xxx */
int ai_protocol; /* 0 or IPPROTO_xxx for IPv4 and IPv6 */
socklen_t ai_addrlen; /* length of ai_addr */
char *ai_canonname; /* canonical name for hostname */
struct sockaddr *ai_addr; /* binary address */
struct addrinfo *ai_next; /* next structure in linked list */
};
The netdb.h should be changed:
- int ai_family; /* PF_xxx */
+ int ai_family; /* AF_xxx */
Similarly in the GETADDRINFO(3) man page:
struct addrinfo {
int ai_flags; /* input flags */
int ai_family; /* protocol family for socket */
int ai_socktype; /* socket type */
int ai_protocol; /* protocol for socket */
socklen_t ai_addrlen; /* length of socket-address */
struct sockaddr *ai_addr; /* socket-address for socket */
char *ai_canonname; /* canonical name for service location */
struct addrinfo *ai_next; /* pointer to next in list */
};
- int ai_family; /* protocol family for socket */
+ int ai_family; /* address family for socket */
- ai_family The protocol family that should be used. When ai_family
- is set to PF_UNSPEC, it means the caller will accept any
- protocol family supported by the operating system.
+ ai_family The address family that should be used. When ai_family
+ is set to AF_UNSPEC, it means the caller will accept any
+ address family supported by the operating system.
[...]
If hints is the null pointer, getaddrinfo() behaves as if the caller pro-
- vided a struct addrinfo with ai_family set to PF_UNSPEC and all other
+ vided a struct addrinfo with ai_family set to AF_UNSPEC and all other
elements set to zero or NULL.
[...]
- hints.ai_family = PF_UNSPEC;
+ hints.ai_family = AF_UNSPEC;
[...]
- hints.ai_family = PF_UNSPEC;
+ hints.ai_family = PF_UNSPEC;
>How-To-Repeat:
Inspect the text in:
$ man getaddrinfo
$ more /usr/include/netdb.h
>Fix:
Replace PF_ by AF_ in the documentation (comments and man page) for the
structure addrinfo, and adjust the GETADDRINFO(3) man page, as indicated
above.
Possibly the source code of getaddrinfo may need a similar adjustment.
>Release-Note:
>Audit-Trail:
>Unformatted:
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201111101128.pAABSCbo094022>