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