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