misc/39372: errors in man pages concerning socket ancillary data

[Taylor R Campbell <campbell%mumble.net@localhost>]

>Number:         39372
>Category:       misc
>Synopsis:       errors in man pages concerning socket ancillary data
>Confidential:   no
>Severity:       serious
>Priority:       medium
>Responsible:    misc-bug-people
>State:          open
>Class:          doc-bug
>Submitter-Id:   net
>Arrival-Date:   Sun Aug 17 22:35:00 +0000 2008
>Originator:     Taylor R Campbell <campbell%mumble.net@localhost>
>Release:        NetBSD 4.0_STABLE
>Organization:
>Environment:
System: NetBSD smalltalk.localdomain 4.0_STABLE NetBSD 4.0_STABLE 
(RIAXEN3_DOM0) #2: Fri Jul 18 23:32:56 UTC 2008 
riastradh@smalltalk:/home/riastradh/netbsd/4/obj/sys/arch/i386/compile/RIAXEN3_DOM0
 i386
Architecture: i386
Machine: i386
>Description:

        The unix(4) man page says of Unix-domain sockets that when the
        LOCAL_CREDS socket option is set, recvmsg(2) can be used to
        obtain the credentials of the process at the other end-point
        in ancillary data with a control message header having the
        following field values:

                cmsg_len = sizeof(struct cmsghdr) + SOCKCREDSIZE(ngroups)
                cmsg_level = SOL_SOCKET
                cmsg_type = SCM_CREDS

        The expression for cmsg_len is incorrect; it should be

                cmsg_len = CMSG_LEN(SOCKCREDSIZE(ngroups))

        There is a similar error in the ip(4) man page concerning
        ancillary data when the IP_RECVDSTADDR or IP_RECVIF options are
        enabled; the expressions for the lengths in these cases are
        even further from the correct ones, since they omit the size of
        a struct cmsghdr altogether.

        The tp(4) man page refers to the csmg_level field of the
        cmsghdr struct, rather than the cmsg_level field.

        It would also be helpful, I think, to have a man page cmsg(3)
        for what is currently called CMSG_DATA(3) (purely for mnemonic
        value -- I keep forgetting what it's called; Linux calls it
        cmsg(3), by the way), and to refer to that in the SEE ALSO
        sections of any man page that mentions ancillary data:

                inet6_option_space(3), inet6_rthdr_space(3), ip(4),
                ip6(4), recv(2), send(2), tp(4), unix(4)

>How-To-Repeat:
>Fix:

        Apply the following patches in src/share/man/man4/:

--- ip.4        23 Dec 2006 06:58:20 +0000      1.22
+++ ip.4        17 Aug 2008 21:59:23 +0000      
@@ -141,7 +141,7 @@
 address.
 The cmsghdr fields have the following values:
 .Bd -literal
-cmsg_len = sizeof(struct in_addr)
+cmsg_len = CMSG_LEN(sizeof(struct in_addr))
 cmsg_level = IPPROTO_IP
 cmsg_type = IP_RECVDSTADDR
 .Ed
@@ -161,7 +161,7 @@
 that contains a cmsghdr structure followed by the struct sockaddr_dl.
 The cmsghdr fields have the following values:
 .Bd -literal
-cmsg_len = sizeof(struct sockaddr_dl)
+cmsg_len = CMSG_LEN(sizeof(struct sockaddr_dl))
 cmsg_level = IPPROTO_IP
 cmsg_type = IP_RECVIF
 .Ed

--- tp.4        25 May 2005 00:13:24 +0000      1.17
+++ tp.4        17 Aug 2008 22:14:31 +0000      
@@ -204,7 +204,7 @@
 will contain
 .Dv SOL_TRANSPORT
 for the
-.Va csmg_level
+.Va cmsg_level
 and
 .Dv TPOPT_CONN_DATA
 for
@@ -229,7 +229,7 @@
 must contain
 .Dv SOL_TRANSPORT
 for
-.Va csmg_level
+.Va cmsg_level
 and
 .Dv TPOPT_DISC_DATA
 for

--- unix.4      10 Aug 2007 23:52:21 +0000      1.19
+++ unix.4      17 Aug 2008 21:46:59 +0000      
@@ -229,7 +229,7 @@
 of groups.
 The cmsghdr fields have the following values:
 .Bd -literal
-cmsg_len = sizeof(struct cmsghdr) + SOCKCREDSIZE(ngroups)
+cmsg_len = CMSG_LEN(SOCKCREDSIZE(ngroups))
 cmsg_level = SOL_SOCKET
 cmsg_type = SCM_CREDS
 .Ed