diff options
Diffstat (limited to 'man3/cmsg.3')
| -rw-r--r-- | man3/cmsg.3 | 261 |
1 files changed, 0 insertions, 261 deletions
diff --git a/man3/cmsg.3 b/man3/cmsg.3 deleted file mode 100644 index 2d0a70e..0000000 --- a/man3/cmsg.3 +++ /dev/null @@ -1,261 +0,0 @@ -.\" 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 2023-10-31 "Linux man-pages 6.7" -.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 |