misc/38993: the macros CMSG_DATA &c. should be documented

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

>Number:         38993
>Category:       misc
>Synopsis:       the macros CMSG_DATA &c. should be documented
>Confidential:   no
>Severity:       serious
>Priority:       medium
>Responsible:    misc-bug-people
>State:          open
>Class:          change-request
>Submitter-Id:   net
>Arrival-Date:   Fri Jun 20 01:05:00 +0000 2008
>Originator:     Taylor R Campbell <campbell%mumble.net@localhost>
>Release:        NetBSD 4.0_STABLE
>Organization:
>Environment:
        
        
System: NetBSD slate.localdomain 4.0_STABLE NetBSD 4.0_STABLE (GENERIC) #0: Sat 
Jun 7 06:55:02 UTC 2008 
riastradh%slate.localdomain@localhost:/home/riastradh/netbsd/4/obj/sys/arch/macppc/compile/GENERIC
 macppc
Architecture: powerpc
Machine: macppc
>Description:

        The macros CMSG_DATA, CMSG_FIRSTHDR, CMSG_NXTHDR, CMSG_SPACE,
        and CMSG_LEN are documented in no man pages of which I am
        aware.  Since they are extremely easy to use incorrectly, and
        since they are necessary in order to use the control message
        part of the BSD sockets API, they should be documented clearly,
        and mentioned in the man page for recvmsg(2), where the
        relevant structs, msghdr and cmsghdr, are described.  Also, the
        sendmsg(2) man page should mention SCM_RIGHTS and refer to the
        documentation for CMSG_DATA &c. and how they should be used
        with SCM_RIGHTS to transmit file descriptors between processes.

>How-To-Repeat:

>Fix:

        OpenBSD has a man page CMSG_DATA.3 for the macros, which could
        be used.  (Note that there have been recent changes to it; the
        revision in OpenBSD-current as of 2008-04 describes the correct
        usage, as emphatically affirmed by Theo, and the revision one
        finds in 4.3 is incorrect.)  It would require a small
        modification for NetBSD to note that CMSG_SPACE and CMSG_LEN
        expand to non-constant expressions; the example code should
        probably be changed to use dynamic heap allocation rather than
        static stack allocation.

>Unformatted: