Adding upstream version 6.8.upstream/6.8upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 261 insertions, 0 deletions

diff --git a/man/man3/cmsg.3 b/man/man3/cmsg.3
new file mode 100644
index 0000000..6a4eee4
--- /dev/null
+++ b/man/man3/cmsg.3
@@ -0,0 +1,261 @@
+.\" SPDX-License-Identifier: Linux-man-pages-1-para
+.\"
+.\" This man page is Copyright (C) 1999 Andi Kleen <ak@muc.de>.
+.\"
+.\" $Id: cmsg.3,v 1.8 2000/12/20 18:10:31 ak Exp $
+.TH CMSG 3 2024-05-02 "Linux man-pages (unreleased)"
+.SH NAME
+CMSG_ALIGN, CMSG_SPACE, CMSG_NXTHDR, CMSG_FIRSTHDR \- access ancillary data
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <sys/socket.h>
+.P
+.BI "struct cmsghdr *CMSG_FIRSTHDR(struct msghdr *" msgh );
+.BI "struct cmsghdr *CMSG_NXTHDR(struct msghdr *" msgh ,
+.BR "                            struct cmsghdr *" cmsg );
+.BI "size_t CMSG_ALIGN(size_t " length );
+.BI "size_t CMSG_SPACE(size_t " length );
+.BI "size_t CMSG_LEN(size_t " length );
+.BI "unsigned char *CMSG_DATA(struct cmsghdr *" cmsg );
+.fi
+.SH DESCRIPTION
+These macros are used to create and access control messages (also called
+ancillary data) that are not a part of the socket payload.
+This control information may
+include the interface the packet was received on, various rarely used header
+fields, an extended error description, a set of file descriptors, or UNIX
+credentials.
+For instance, control messages can be used to send
+additional header fields such as IP options.
+Ancillary data is sent by calling
+.BR sendmsg (2)
+and received by calling
+.BR recvmsg (2).
+See their manual pages for more information.
+.P
+Ancillary data is a sequence of
+.I cmsghdr
+structures with appended data.
+See the specific protocol man pages for the available control message types.
+The maximum ancillary buffer size allowed per socket can be set using
+.IR /proc/sys/net/core/optmem_max ;
+see
+.BR socket (7).
+.P
+The
+.I cmsghdr
+structure is defined as follows:
+.P
+.in +4n
+.EX
+struct cmsghdr {
+    size_t cmsg_len;    /* Data byte count, including header
+                           (type is socklen_t in POSIX) */
+    int    cmsg_level;  /* Originating protocol */
+    int    cmsg_type;   /* Protocol\-specific type */
+/* followed by
+   unsigned char cmsg_data[]; */
+};
+.EE
+.in
+.P
+The sequence of
+.I cmsghdr
+structures should never be accessed directly.
+Instead, use only the following macros:
+.TP
+.BR CMSG_FIRSTHDR ()
+returns a pointer to the first
+.I cmsghdr
+in the ancillary
+data buffer associated with the passed
+.IR msghdr .
+It returns NULL if there isn't enough space for a
+.I cmsghdr
+in the buffer.
+.TP
+.BR CMSG_NXTHDR ()
+returns the next valid
+.I cmsghdr
+after the passed
+.IR cmsghdr .
+It returns NULL when there isn't enough space left in the buffer.
+.IP
+When initializing a buffer that will contain a series of
+.I cmsghdr
+structures (e.g., to be sent with
+.BR sendmsg (2)),
+that buffer should first be zero-initialized
+to ensure the correct operation of
+.BR CMSG_NXTHDR ().
+.TP
+.BR CMSG_ALIGN (),
+given a length, returns it including the required alignment.
+This is a
+constant expression.
+.TP
+.BR CMSG_SPACE ()
+returns the number of bytes an ancillary element with payload of the
+passed data length occupies.
+This is a constant expression.
+.TP
+.BR CMSG_DATA ()
+returns a pointer to the data portion of a
+.IR cmsghdr .
+The pointer returned cannot be assumed to be suitably aligned for
+accessing arbitrary payload data types.
+Applications should not cast it to a pointer type matching the payload,
+but should instead use
+.BR memcpy (3)
+to copy data to or from a suitably declared object.
+.TP
+.BR CMSG_LEN ()
+returns the value to store in the
+.I cmsg_len
+member of the
+.I cmsghdr
+structure, taking into account any necessary
+alignment.
+It takes the data length as an argument.
+This is a constant
+expression.
+.P
+To create ancillary data, first initialize the
+.I msg_controllen
+member of the
+.I msghdr
+with the length of the control message buffer.
+Use
+.BR CMSG_FIRSTHDR ()
+on the
+.I msghdr
+to get the first control message and
+.BR CMSG_NXTHDR ()
+to get all subsequent ones.
+In each control message, initialize
+.I cmsg_len
+(with
+.BR CMSG_LEN ()),
+the other
+.I cmsghdr
+header fields, and the data portion using
+.BR CMSG_DATA ().
+Finally, the
+.I msg_controllen
+field of the
+.I msghdr
+should be set to the sum of the
+.BR CMSG_SPACE ()
+of the length of
+all control messages in the buffer.
+For more information on the
+.IR msghdr ,
+see
+.BR recvmsg (2).
+.SH VERSIONS
+For portability, ancillary data should be accessed using only the macros
+described here.
+.P
+In Linux,
+.BR CMSG_LEN (),
+.BR CMSG_DATA (),
+and
+.BR CMSG_ALIGN ()
+are constant expressions (assuming their argument is constant),
+meaning that these values can be used to declare the size of global variables.
+This may not be portable, however.
+.SH STANDARDS
+.TP
+.BR CMSG_FIRSTHDR ()
+.TQ
+.BR CMSG_NXTHDR ()
+.TQ
+.BR CMSG_DATA ()
+POSIX.1-2008.
+.TP
+.BR CMSG_SPACE ()
+.TQ
+.BR CMSG_LEN ()
+.TQ
+.BR CMSG_ALIGN ()
+Linux.
+.SH HISTORY
+This ancillary data model conforms to the POSIX.1g draft, 4.4BSD-Lite,
+the IPv6 advanced API described in RFC\ 2292 and SUSv2.
+.P
+.BR CMSG_SPACE ()
+and
+.BR CMSG_LEN ()
+.\" https://www.austingroupbugs.net/view.php?id=978#c3242
+will be included in the next POSIX release (Issue 8).
+.SH EXAMPLES
+This code looks for the
+.B IP_TTL
+option in a received ancillary buffer:
+.P
+.in +4n
+.EX
+struct msghdr msgh;
+struct cmsghdr *cmsg;
+int received_ttl;
+\&
+/* Receive auxiliary data in msgh */
+\&
+for (cmsg = CMSG_FIRSTHDR(&msgh); cmsg != NULL;
+        cmsg = CMSG_NXTHDR(&msgh, cmsg)) {
+    if (cmsg\->cmsg_level == IPPROTO_IP
+            && cmsg\->cmsg_type == IP_TTL) {
+        memcpy(&receive_ttl, CMSG_DATA(cmsg), sizeof(received_ttl));
+        break;
+    }
+}
+\&
+if (cmsg == NULL) {
+    /* Error: IP_TTL not enabled or small buffer or I/O error */
+}
+.EE
+.in
+.P
+The code below passes an array of file descriptors over a
+UNIX domain socket using
+.BR SCM_RIGHTS :
+.P
+.in +4n
+.EX
+struct msghdr msg = { 0 };
+struct cmsghdr *cmsg;
+int myfds[NUM_FD];  /* Contains the file descriptors to pass */
+char iobuf[1];
+struct iovec io = {
+    .iov_base = iobuf,
+    .iov_len = sizeof(iobuf)
+};
+union {         /* Ancillary data buffer, wrapped in a union
+                   in order to ensure it is suitably aligned */
+    char buf[CMSG_SPACE(sizeof(myfds))];
+    struct cmsghdr align;
+} u;
+\&
+msg.msg_iov = &io;
+msg.msg_iovlen = 1;
+msg.msg_control = u.buf;
+msg.msg_controllen = sizeof(u.buf);
+cmsg = CMSG_FIRSTHDR(&msg);
+cmsg\->cmsg_level = SOL_SOCKET;
+cmsg\->cmsg_type = SCM_RIGHTS;
+cmsg\->cmsg_len = CMSG_LEN(sizeof(myfds));
+memcpy(CMSG_DATA(cmsg), myfds, sizeof(myfds));
+.EE
+.in
+.P
+For a complete code example that shows passing of file descriptors
+over a UNIX domain socket, see
+.BR seccomp_unotify (2).
+.SH SEE ALSO
+.BR recvmsg (2),
+.BR sendmsg (2)
+.P
+RFC\ 2292