lib/54047: man page about struct addrinfo is different from its implementation

[SODA Noriyuki <soda%NetBSD.org@localhost>]

>Number:         54047
>Category:       lib
>Synopsis:       man page about struct addrinfo is different from its implementation
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    lib-bug-people
>State:          open
>Class:          doc-bug
>Submitter-Id:   net
>Arrival-Date:   Thu Mar 07 10:30:00 +0000 2019
>Originator:     SODA Noriyuki
>Release:        NetBSD 7.1
>Organization:
the NetBSD project
>Environment:
System: NetBSD srapc2586.sra.co.jp 7.1 NetBSD 7.1 (GENERIC.201703111743Z) amd64
Architecture: x86_64
Machine: amd64
>Description:

The order of ai_canonname and ai_next is different as follows:

getaddrinfo(3) man page:
	struct addrinfo {
	 ... SNIP ...
		struct sockaddr *ai_addr;
		char *ai_canonname;
		struct addrinfo *ai_next;
	};

<netdb.h>:
	struct addrinfo {
	 ... SNIP ...
		char            *ai_canonname;
		struct sockaddr *ai_addr;
		struct addrinfo *ai_next;
	};

this problem was introduced in lib/libc/net/getaddrinfo.3 revision 1.39.

the order of the man page is same with Single UNIX Specification,
OpenBSD and Linux.
our implementation in <netdb.h> is same with FreeBSD, Solaris
and RFC2133/2553/3493

FreeBSD had similar problem and fixed it on Feb 10 2019 as part of follows:
https://svnweb.freebsd.org/base?view=revision&revision=343967

I've heard this problem from hrs@NetBSD.

>How-To-Repeat:

compare "man 3 getaddrinfo" and /usr/include/netdb.h

>Fix:

the following patch also updates the comment fields to make them
match with <netdb.h> just like as FreeBSD did in revision 343967.

the ai_protocol line below exeeds 80 columns though.
perhaps it is better to replace TABs by some spaces?

Index: lib/libc/net/getaddrinfo.3
===================================================================
RCS file: /cvsroot/src/lib/libc/net/getaddrinfo.3,v
retrieving revision 1.59
diff -u -r1.59 getaddrinfo.3
--- lib/libc/net/getaddrinfo.3	3 Jul 2017 21:32:49 -0000	1.59
+++ lib/libc/net/getaddrinfo.3	7 Mar 2019 09:03:41 -0000
@@ -76,14 +76,14 @@
 .In netdb.h :
 .Bd -literal
 struct addrinfo {
-	int ai_flags;		/* input flags */
-	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 */
-	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_flags;	/* AI_PASSIVE, AI_CANONNAME */
+	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 */
 };
 .Ed
 .Pp