Re: Fix netdb.h addrinfo namespace (bug 18529)

[Joseph Myers <joseph at codesourcery dot com>]

On Fri, 12 Jun 2015, Roland McGrath wrote:

> > I've made the existing comment refer to POSIX.1:2001 instead of POSIX.1g 
> > (a reference to POSIX.1:2001 seems the most useful in terms of the 
> > standards supported by glibc).  I don't think the fact that there was once 
> > a bug is particularly useful information to go in comments in the header.
> 
> The "bug" here was an explicit change in the API surface that affects the
> build choices of code that is trying to be portable.  So I think it is
> appropriate to make clear how the API has evolved over time.

There are 113 unsorted conform test XFAILs for header API issues - some 
are bugs in the test expectations, but many are header bugs and there are 
probably many more header bugs hidden by bugs in the test expectations 
that haven't been fully reviewed for most of the relevant standards.  
Only a small proportion of such bugs show up in the linknamespace tests 
rather than the direct tests of header API.  As is often the case with 
bugs, the previous buggy state is not particularly meaningful to describe; 
it's a long series of complicated, nonsensical deviations from the 
standards the headers were meant to be following (and the old API state 
also includes things such as _BSD_SOURCE and _SVID_SOURCE which are no 
longer relevant to glibc and where we've simplified the headers by 
eliminating them).

The high-level description for users is "many headers had bugs where the 
symbols exposed didn't correspond exactly to the standard selected by the 
feature test macros defined, and many such bugs have been fixed over time 
to bring the headers closer to the relevant standards"; something like 
that could go in NEWS for releases with a significant number of such 
fixes.  The place for the detailed information about what each deviation 
from the standards was is Bugzilla and the git history.  I think the 
headers and other sources are better maintained on the basis of describing 
what is, not what was, rather than having large numbers of complicated and 
confusing comments explaining past bugs, save in exceptional cases where 
the history is a basis for current choices (e.g. if something is done in 
an odd way for compatibility with existing binaries).

I think the threshold for calling out such a fix individually in comments 
or NEWS should be quite high, such that the bulk of the many such fixes do 
not reach it.  The threshold for mentioning changes in the documentation 
for individual functions in the manual may be a bit lower - the manual, 
not the headers, should be where the main detailed information for users 
is - but I'd still be inclined to limit it to cases where a program 
written for guarantees about a function in a newer version of glibc could 
quietly fail to work with older versions, not for cases where any failure 
with older glibc would be obvious.

> > I think of these changes (that do not affect _DEFAULT_SOURCE or 
> > _GNU_SOURCE and do not obsolete or remove any API) as much like any other 
> > ordinary bug fix
> 
> I don't know why _GNU_SOURCE and _DEFAULT_SOURCE are special in your mind
> for this subject.  The API for users of a different feature-test macro

Because those are what determine whether the vast bulk of users will 
actually see anything different.

-- 
Joseph S. Myers
joseph@codesourcery.com