getaddrinfo manpage doesn't match glibc implementation when hints is NULL

Bug #153571 reported by Paul Fee on 2007-10-17
4
Affects Status Importance Assigned to Milestone
GLibC
Won't Fix
Medium
manpages
In Progress
Undecided
Michael Kerrisk
glibc (Ubuntu)
Undecided
Paul Fee
manpages-posix (Ubuntu)
Undecided
Paul Fee

Bug Description

Binary package hint: manpages-posix-dev

Writing an application that looks up IPv6 addresses, I noticed use of NULL for the hints field of getaddrinfo() as decribed in the manpage does not correspond with implementation.

Extracted the source as follows:
$ apt-get source libc6-dev
$ cd glibc-2.5
$ tar xjf glibc-2.5.tar.bz2
$ vi glibc-2.5/sysdeps/posix/getaddrinfo.c

The default_hints structure on line 132 has ai_flags = AI_DEFAULT.

AI_DEFAULTS expands to: (AI_V4MAPPED | AI_ADDRCONFIG)

This is used within getaddrinfo() line 1874 when hints is NULL.

However the manpage states:
"If hints is a null pointer, the behavior shall be as if it referred to a structure containing the value zero for the ai_flags, ai_socktype, and ai_protocol fields, and AF_UNSPEC for the ai_family field."

The problem is that behaviour is not that of a zero ai_flags, but instead that of:
ai_flags = AI_V4MAPPED | AI_ADDRCONFIG

The quick solution is to adjust the manpage to reflect the existing implementation. Perhaps report it in the manpage's bugs section and suggest the user always populate hints with a non-NULL value so your application is more portable.

However the more important question would be what is the correct implementation?

The Solaris 10 manpage states:
"If the third argument to getaddrinfo() is a null pointer, it is as if the caller had filled in an addrinfo structure initialized to 0 with ai_family set to PF_UNSPEC."

Since both manpages suggest a NULL hints is the same as a hints with all fields zero, the implementation in glibc may have a bug.

Matthias Klose (doko) wrote :

please could you recheck with hardy and/or intrepid?

Changed in glibc:
status: New → Incomplete
Paul Fee (pfee) wrote :

Hello Matthias,

I downloaded Hardy's libc6-dev source package (2.7-10ubuntu3), same extraction steps as above (except 2.7 instead of 2.5).

Also checked getaddrinfo manpage (in manpages-posix-dev, 2.16-1).

In the glibc source code:
./include/netdb.h:#define AI_DEFAULT (AI_V4MAPPED | AI_ADDRCONFIG

The manpage has the text:
""If hints is a null pointer, the behavior shall be as if it referred to a structure containing the value zero for the ai_flags, ai_socktype, and ai_protocol fields, and AF_UNSPEC for the ai_family field."

Since neither glibc nor the manpage has changed, the bug remains unresolved.

Thanks,
Paul

Michael Kerrisk (mtk-manpages) wrote :

Note that the reporter is marking a bug against the POSIX man page which is taken straight from the standard. By definition, this page won't describe glibc specifics.

I confirm that the reporter is correct in pointing out that glibc deviates from the standard. (I don't know the reasons) The Linux man page documents the deviation:

http://www.kernel.org/doc/man-pages/online/pages/man3/getaddrinfo.3.html

POSIX.1-2001 and 2008 say that if the hints argument of getaddrinfo() is NULL, then

       the behavior shall be as if it referred to a structure
       containing the value zero for the ai_flags, ai_socktype,
       and ai_protocol fields, and AF_UNSPEC for the ai_family
       field.

However, glibc defines ai_flags as AI_V4MAPPED | AI_ADDRCONFIG for this case. Is
this deviation from POSIX.1 intentional? Should it be fixed?

Michael Kerrisk (mtk-manpages) wrote :

For what it's worth, I filed this glibc bug:
http://sourceware.org/bugzilla/show_bug.cgi?id=10567

Paul Fee (pfee) wrote :

Thanks for the update.

The getaddrinfo manpage on Ubuntu 9.04 has text.

"Specifying hints as NULL is equivalent to setting ai_socktype and ai_protocol to 0; ai_family to AF_UNSPEC; and ai_flags to (AI_V4MAPPED | AI_ADDRCONFIG)."

I notice there are two getaddrinfo manpages, section 3 and 3posix. I didn't spotted that before.

The section 3 manpage correctly documents the glibc implementation. So I the manpage part of this bug is fixed (or wasn't a bug to start with).

Thanks for raising the glibc bug, it'll be interesting to see the reasoning behind the deviation from the POSIX standard.

Paul Fee (pfee) wrote :

Posix manpage describes the standard, not the glibc implementation.

Changed in manpages-posix (Ubuntu):
assignee: nobody → Paul Fee (pfee)
status: New → Invalid
Paul Fee (pfee) wrote :
Changed in glibc (Ubuntu):
status: Incomplete → In Progress

(In reply to comment #0)
> Should it be fixed?

No. Like several other things in the getaddrinfo spec this is non-optimal at
best. The defaults used in glibc are much better.

Subject: Re: getaddrinfo() hints==NULL (ai_flags) deviates
 from POSIX.1

On Mon, Aug 31, 2009 at 2:14 PM, drepper at redhat dot
com<email address hidden> wrote:
>
> ------- Additional Comments From drepper at redhat dot com  2009-08-31 12:14 -------
> (In reply to comment #0)
>> Should it be fixed?
>
> No.  Like several other things in the getaddrinfo spec this is non-optimal at
> best.  The defaults used in glibc are much better.

Thanks. I'll update the man page to make it clear that this choice is
deliberate.

Can some details be added as to why the glibc defaults are better than the POSIX standard.

The default only applies if hints==NULL. If the POSIX defaults are non-optimal, then users of
other systems (e.g. Solaris) would find it useful to know that different settings are preferred.
On Solaris 10, setting hints to NULL results in POSIX defined behaviour.

Are the reasons behind glibc's defaults unique to glibc or are they related to network effects
which would apply to any OS or C resolver library. If the settings are valid everywhere then
getaddrinfo() users would benefit from using them on non-glibc platforms.

Thanks.

Paul Fee (pfee) wrote :

Ulrich Drepper has responded to say that choice of defaults is deliberate. Therefore the behaviour in glibc won't be changing. Next task is to get the getaddrinfo manpage updated to state why there's a discrepancy between the glibc implementation and the POSIX standard.

Changed in glibc (Ubuntu):
status: In Progress → Invalid
Paul Fee (pfee) wrote :

Michael Kerrisk has indicated the manpages will be updated.

Please add detail about the rational for the difference between glibc and POSIX, if you have this information.

Changed in manpages:
assignee: nobody → Michael Kerrisk (mtk-manpages)
status: New → In Progress
Changed in glibc (Ubuntu):
assignee: nobody → Paul Fee (pfee)
Changed in glibc:
status: Unknown → Won't Fix
Changed in glibc:
importance: Unknown → Medium
Pavel Šimerda (pavlix-a) wrote :

In upstream GLIBC there are two flags in the defaults:

AI_ADDRCONFIG: It is most probably *not* a good default, as it's only useful for applications that have to set the hints anyway so that they only recieve TCP or UDP addrinfo structures, not both.

http://sourceware.org/bugzilla/show_bug.cgi?id=14965

AI_V4MAPPED: This is not used, as it only applies to AF_INET6 but the default is AF_UNSPEC.

http://sourceware.org/bugzilla/show_bug.cgi?id=14415

Therefore the only sane default is probably no flags at all (hints.ai_flags = 0).

To post a comment you must log in.
This report contains Public information  Edit
Everyone can see this information.

Other bug subscribers

Remote bug watches

Bug watches keep track of this bug in other bug trackers.