>Number:         32844
>Category:       kern
>Synopsis:       unix domain sockets documentation is incomplete
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    kern-bug-people
>State:          open
>Class:          change-request
>Submitter-Id:   net
>Arrival-Date:   Wed Feb 15 10:35:04 +0000 2006
>Originator:     Christian Biere
>Release:        NetBSD 3.99.15
>Environment:
System: NetBSD cyclonus 3.99.15 NetBSD 3.99.15 (STARSCREAM) #2: Wed Feb 15 09:55:36 CET 2006 bin@cyclonus:/o/NetBSD/obj/sys/arch/i386/compile/STARSCREAM i386
Architecture: i386
Machine: i386
>Description:
The manual page for recvmsg(2) is somewhat incomplete. The rather
important CMSG_* macros are not mentioned at all. OpenBSD (at least
current) has a very useful additional manual page CMSG_DATA(3) which
explains these macros. [Sidenote: The example on the  OpenBSD manual
page is slightly wrong because it assumes only a single file
descriptor is passed with SCM_RIGHTS and the code could cause a file
descriptor leak.]

The manual page for unix(4) claims that LOCAL_CREDS is a socket-level
option for getsockopt() and setsockopt(). I think that's slightly
wrong because it implies "level = SOL_SOCKET" but the correct use is
"level = 0". I was wondering why the receiver got no SCM_CREDS even
though setsockopt() succeeded. STFW gained that everybody uses 0
instead of SOL_SOCKET here.

The same manual page claims there is only LOCAL_CREDS but actually
there is also LOCAL_CONNWAIT. The equivalent of FreeBSD explains
it.

This might be OT for this PR but I think there could be another
macro CMSG_DATA_LEN() that returns the effective payload size:

#define CMSG_DATA_LEN(cmsg) \
  ((cmsg)->cmsg_len - ((char *) CMSG_DATA(cmsg) - (char *) (cmsg)))

Knowing this length is vital for SCM_RIGHTS which may carry more
than a single file descriptor and the amount can be derived
from this length only.

Another half-OT complaint: CMSG_SPACE() and CMSG_LEN() currently
do not gain constant expressions due to the use of an inline
function in these macros which means they cannot properly be
used for static memory allocations. Even for automatic storage
this requires C99 IIRC.

>How-To-Repeat:
scroll-up
>Fix: