Michael,

I'm one of the instructors for the Linux Foundation.  Jerry Cooperstein 
posted a note to the instructor's mailing list that he's going to update 
the network programming chapters of LFD312.  A couple of us suggested 
that he retire the exercises that use the obsolete library calls 
gethostbyname(3) and friends, replacing with with code using getaddrinfo(3).

I noted that a lot of example code out there, including (sigh) early 
editions of the Richard Stevens book "UNIX  Network Programming, Vol. 1" 
fail to accomplish what Stevens says is a goal of network programming:  
"protocol independence."

A "protocol independent" server exposes the server's socket at ALL of 
the server's IP addresses:  IPv4 and IPv6, local and remote.

The current getaddrinfo(3) man page gets PART of the way to instructing 
how to do this.

The missing part is that after setting the "hints" struct to ai_family = 
AF_UNSPEC and ai_flags = AI_PASSIVE, the code needs to CHECK the 
"ai_family" of each candidate address in the list returned by 
getaddrinfo(3) to preferentially choose AF_INET6 over AF_INET.

If the server (preferentially) binds to an IPv6 address, qualified as 
"AF_UNSPEC" and "AI_PASSIVE" in the hints, then the resulting socket 
will be visible at ANY and ALL of the server's IP addresses. If the 
server binds to an IPv4 address candidate (because the address 
candidates in the list aren't checked before trying to bind), then the 
socket is unavailable to clients trying any of the server's IPv6 
addresses.  This is arguably an inferior result.

I attach a patch file against the top of  the man-pages tree (version 
4.05) with modifications to two parts of man3/getaddrinfo.3:

   -> the section describing AF_UNSPEC is expanded with a "programming 
note" describing how to write a "protocol independent" server.

   -> the "server" example code has about 6 lines of code added, PLUS an 
expansion of the block comment before the loop that walks the list 
returned by getaddrinfo(3).

Thanks for considering this patch.  Please let me know what I've done 
horribly wrong, and I'll try to fix it.  I think this is somewhat 
important, as writing "protocol independent" servers is fairly 
important, and MOST of the code examples out on the Web and elsewhere 
don't CHECK the address candidates when walking the list returned by 
getaddrinfo(3).   That's all that needs to be done to make network 
servers better.

  == Bill Kerr
         bilker-7Y6McbBI5zQ@public.gmane.org
         503 781-7946