man3/cmsg.3

   1 .\" This man page is Copyright (C) 1999 Andi Kleen <ak@muc.de>.
   2 .\"
   3 .\" %%%LICENSE_START(VERBATIM_ONE_PARA)
   4 .\" Permission is granted to distribute possibly modified copies
   5 .\" of this page provided the header is included verbatim,
   6 .\" and in case of nontrivial modification author and date
   7 .\" of the modification is added to the header.
   8 .\" %%%LICENSE_END
   9 .\"
  10 .\" $Id: cmsg.3,v 1.8 2000/12/20 18:10:31 ak Exp $
  11 .TH CMSG 3 2021-03-22 "Linux man-pages (unreleased)"
  12 .SH NAME
  13 CMSG_ALIGN, CMSG_SPACE, CMSG_NXTHDR, CMSG_FIRSTHDR \- access ancillary data
  14 .SH LIBRARY
  15 Standard C library
  16 .RI ( libc ", " \-lc )
  17 .SH SYNOPSIS
  18 .nf
  19 .B #include <sys/socket.h>
  20 .PP
  21 .BI "struct cmsghdr *CMSG_FIRSTHDR(struct msghdr *" msgh );
  22 .BI "struct cmsghdr *CMSG_NXTHDR(struct msghdr *" msgh ,
  23 .BR "                            struct cmsghdr *" cmsg );
  24 .BI "size_t CMSG_ALIGN(size_t " length );
  25 .BI "size_t CMSG_SPACE(size_t " length );
  26 .BI "size_t CMSG_LEN(size_t " length );
  27 .BI "unsigned char *CMSG_DATA(struct cmsghdr *" cmsg );
  28 .fi
  29 .SH DESCRIPTION
  30 These macros are used to create and access control messages (also called
  31 ancillary data) that are not a part of the socket payload.
  32 This control information may
  33 include the interface the packet was received on, various rarely used header
  34 fields, an extended error description, a set of file descriptors, or UNIX
  35 credentials.
  36 For instance, control messages can be used to send
  37 additional header fields such as IP options.
  38 Ancillary data is sent by calling
  39 .BR sendmsg (2)
  40 and received by calling
  41 .BR recvmsg (2).
  42 See their manual pages for more information.
  43 .PP
  44 Ancillary data is a sequence of
  45 .I cmsghdr
  46 structures with appended data.
  47 See the specific protocol man pages for the available control message types.
  48 The maximum ancillary buffer size allowed per socket can be set using
  49 .IR /proc/sys/net/core/optmem_max ;
  50 see
  51 .BR socket (7).
  52 .PP
  53 The
  54 .I cmsghdr
  55 structure is defined as follows:
  56 .PP
  57 .in +4n
  58 .EX
  59 struct cmsghdr {
  60     size_t cmsg_len;    /* Data byte count, including header
  61                            (type is socklen_t in POSIX) */
  62     int    cmsg_level;  /* Originating protocol */
  63     int    cmsg_type;   /* Protocol\-specific type */
  64 /* followed by
  65    unsigned char cmsg_data[]; */
  66 };
  67 .EE
  68 .in
  69 .PP
  70 The sequence of
  71 .I cmsghdr
  72 structures should never be accessed directly.
  73 Instead, use only the following macros:
  74 .IP * 3
  75 .BR CMSG_FIRSTHDR ()
  76 returns a pointer to the first
  77 .I cmsghdr
  78 in the ancillary
  79 data buffer associated with the passed
  80 .IR msghdr .
  81 It returns NULL if there isn't enough space for a
  82 .I cmsghdr
  83 in the buffer.
  84 .IP *
  85 .BR CMSG_NXTHDR ()
  86 returns the next valid
  87 .I cmsghdr
  88 after the passed
  89 .IR cmsghdr .
  90 It returns NULL when there isn't enough space left in the buffer.
  91 .IP
  92 When initializing a buffer that will contain a series of
  93 .I cmsghdr
  94 structures (e.g., to be sent with
  95 .BR sendmsg (2)),
  96 that buffer should first be zero-initialized
  97 to ensure the correct operation of
  98 .BR CMSG_NXTHDR ().
  99 .IP *
 100 .BR CMSG_ALIGN (),
 101 given a length, returns it including the required alignment.
 102 This is a
 103 constant expression.
 104 .IP *
 105 .BR CMSG_SPACE ()
 106 returns the number of bytes an ancillary element with payload of the
 107 passed data length occupies.
 108 This is a constant expression.
 109 .IP *
 110 .BR CMSG_DATA ()
 111 returns a pointer to the data portion of a
 112 .IR cmsghdr .
 113 The pointer returned cannot be assumed to be suitably aligned for
 114 accessing arbitrary payload data types.
 115 Applications should not cast it to a pointer type matching the payload,
 116 but should instead use
 117 .BR memcpy (3)
 118 to copy data to or from a suitably declared object.
 119 .IP *
 120 .BR CMSG_LEN ()
 121 returns the value to store in the
 122 .I cmsg_len
 123 member of the
 124 .I cmsghdr
 125 structure, taking into account any necessary
 126 alignment.
 127 It takes the data length as an argument.
 128 This is a constant
 129 expression.
 130 .PP
 131 To create ancillary data, first initialize the
 132 .I msg_controllen
 133 member of the
 134 .I msghdr
 135 with the length of the control message buffer.
 136 Use
 137 .BR CMSG_FIRSTHDR ()
 138 on the
 139 .I msghdr
 140 to get the first control message and
 141 .BR CMSG_NXTHDR ()
 142 to get all subsequent ones.
 143 In each control message, initialize
 144 .I cmsg_len
 145 (with
 146 .BR CMSG_LEN ()),
 147 the other
 148 .I cmsghdr
 149 header fields, and the data portion using
 150 .BR CMSG_DATA ().
 151 Finally, the
 152 .I msg_controllen
 153 field of the
 154 .I msghdr
 155 should be set to the sum of the
 156 .BR CMSG_SPACE ()
 157 of the length of
 158 all control messages in the buffer.
 159 For more information on the
 160 .IR msghdr ,
 161 see
 162 .BR recvmsg (2).
 163 .SH STANDARDS
 164 This ancillary data model conforms to the POSIX.1g draft, 4.4BSD-Lite,
 165 the IPv6 advanced API described in RFC\ 2292 and SUSv2.
 166 .BR CMSG_FIRSTHDR (),
 167 .BR CMSG_NXTHDR (),
 168 and
 169 .BR CMSG_DATA ()
 170 are specified in POSIX.1-2008.
 171 .BR CMSG_SPACE ()
 172 and
 173 .BR CMSG_LEN ()
 174 .\" https://www.austingroupbugs.net/view.php?id=978#c3242
 175 will be included in the next POSIX release (Issue 8).
 176 .PP
 177 .BR CMSG_ALIGN ()
 178 is a Linux extension.
 179 .SH NOTES
 180 For portability, ancillary data should be accessed using only the macros
 181 described here.
 182 .BR CMSG_ALIGN ()
 183 is a Linux extension and should not be used in portable programs.
 184 .PP
 185 In Linux,
 186 .BR CMSG_LEN (),
 187 .BR CMSG_DATA (),
 188 and
 189 .BR CMSG_ALIGN ()
 190 are constant expressions (assuming their argument is constant),
 191 meaning that these values can be used to declare the size of global variables.
 192 This may not be portable, however.
 193 .SH EXAMPLES
 194 This code looks for the
 195 .B IP_TTL
 196 option in a received ancillary buffer:
 197 .PP
 198 .in +4n
 199 .EX
 200 struct msghdr msgh;
 201 struct cmsghdr *cmsg;
 202 int received_ttl;
 203
 204 /* Receive auxiliary data in msgh */
 205
 206 for (cmsg = CMSG_FIRSTHDR(&msgh); cmsg != NULL;
 207         cmsg = CMSG_NXTHDR(&msgh, cmsg)) {
 208     if (cmsg\->cmsg_level == IPPROTO_IP
 209             && cmsg\->cmsg_type == IP_TTL) {
 210         memcpy(&receive_ttl, CMSG_DATA(cmsg), sizeof(received_ttl));
 211         break;
 212     }
 213 }
 214
 215 if (cmsg == NULL) {
 216     /* Error: IP_TTL not enabled or small buffer or I/O error */
 217 }
 218 .EE
 219 .in
 220 .PP
 221 The code below passes an array of file descriptors over a
 222 UNIX domain socket using
 223 .BR SCM_RIGHTS :
 224 .PP
 225 .in +4n
 226 .EX
 227 struct msghdr msg = { 0 };
 228 struct cmsghdr *cmsg;
 229 int myfds[NUM_FD];  /* Contains the file descriptors to pass */
 230 char iobuf[1];
 231 struct iovec io = {
 232     .iov_base = iobuf,
 233     .iov_len = sizeof(iobuf)
 234 };
 235 union {         /* Ancillary data buffer, wrapped in a union
 236                    in order to ensure it is suitably aligned */
 237     char buf[CMSG_SPACE(sizeof(myfds))];
 238     struct cmsghdr align;
 239 } u;
 240
 241 msg.msg_iov = &io;
 242 msg.msg_iovlen = 1;
 243 msg.msg_control = u.buf;
 244 msg.msg_controllen = sizeof(u.buf);
 245 cmsg = CMSG_FIRSTHDR(&msg);
 246 cmsg\->cmsg_level = SOL_SOCKET;
 247 cmsg\->cmsg_type = SCM_RIGHTS;
 248 cmsg\->cmsg_len = CMSG_LEN(sizeof(myfds));
 249 memcpy(CMSG_DATA(cmsg), myfds, sizeof(myfds));
 250 .EE
 251 .in
 252 .PP
 253 For a complete code example that shows passing of file descriptors
 254 over a UNIX domain socket, see
 255 .BR seccomp_unotify (2).
 256 .SH SEE ALSO
 257 .BR recvmsg (2),
 258 .BR sendmsg (2)
 259 .PP
 260 RFC\ 2292