[PATCH v2 2/8] man/man7/unix.7: Multiple same-typed SCM_* messages may be sent in one message

["Günther Noack" <gnoack3000@gmail.com>]

In the Linux kernel code, __scm_send() in linux.git net/core/scm.c
walks all control messages in a loop like this:

	for_each_cmsghdr(cmsg, msg) {
		// ...
		switch (cmsg->cmsg_type)
		{
		case SCM_RIGHTS:
			... append(!) file descriptors
			    up to the SCM_MAX_FD limit ...
			break;
		case SCM_CREDENTIALS:
			... replace previously set credentials ...
			break;
		default:
			goto error;
		}
	}

So it is possible to pass multiple SCM_* messages -- they will compose
if possible and override the previous value if not.  Since their
contents are being conflated that way, they will appear as one message
again on the receiving side.

Keep the recommendation as portability advice, and describe the Linux
behavior.

Fixes: 5b5cb1958062 (2018-07-10; "unix.7: When sending ancillary data, only one item of each type may be sent")
Cc: Michael Kerrisk <mtk.manpages@gmail.com>
Cc: Kuniyuki Iwashima <kuniyu@google.com>
Assisted-by: LLM
Signed-off-by: Günther Noack <gnoack3000@gmail.com>
---

Notes:
    The factual analysis in the commit message is correct.
    
    I kept the LLM phrasing; it did not seem overly wordy to me and the
    style is in line with the paragraph after it, which also documents
    Linux-only vs. portable APIs that way.

 man/man7/unix.7 | 19 ++++++++++++++++++-
 1 file changed, 18 insertions(+), 1 deletion(-)

diff --git a/man/man7/unix.7 b/man/man7/unix.7
index 94b9e82af3c0..1695f1c120c7 100644
--- a/man/man7/unix.7
+++ b/man/man7/unix.7
@@ -538,7 +538,24 @@ .SS Ancillary messages
 .P
 When sending ancillary data with
 .BR sendmsg (2),
-only one item of each of the above types may be included in the sent message.
+portable applications should include
+only one item of each of the above types in the sent message.
+On Linux,
+if several
+.B SCM_RIGHTS
+items are included,
+their file descriptors are combined into a single list,
+to which the
+.B SCM_MAX_FD
+limit applies as a whole,
+and the receiver gets them in a single
+.B SCM_RIGHTS
+item;
+if several
+.B SCM_CREDENTIALS
+items are included,
+each of them is checked,
+and the last one is sent.
 .P
 At least one byte of real data should be sent when sending ancillary data.
 On Linux, this is required to successfully send ancillary data over
-- 
2.56.0