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 2017-09-15 "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 .IP *
 110 .BR CMSG_LEN ()
 111 returns the value to store in the
 112 .I cmsg_len
 113 member of the
 114 .I cmsghdr
 115 structure, taking into account any necessary
 116 alignment.
 117 It takes the data length as an argument.
 118 This is a constant
 119 expression.
 120 .PP
 121 To create ancillary data, first initialize the
 122 .I msg_controllen
 123 member of the
 124 .I msghdr
 125 with the length of the control message buffer.
 126 Use
 127 .BR CMSG_FIRSTHDR ()
 128 on the
 129 .I msghdr
 130 to get the first control message and
 131 .BR CMSG_NXTHDR ()
 132 to get all subsequent ones.
 133 In each control message, initialize
 134 .I cmsg_len
 135 (with
 136 .BR CMSG_LEN ()),
 137 the other
 138 .I cmsghdr
 139 header fields, and the data portion using
 140 .BR CMSG_DATA ().
 141 Finally, the
 142 .I msg_controllen
 143 field of the
 144 .I msghdr
 145 should be set to the sum of the
 146 .BR CMSG_SPACE ()
 147 of the length of
 148 all control messages in the buffer.
 149 For more information on the
 150 .IR msghdr ,
 151 see
 152 .BR recvmsg (2).
 153 .SH CONFORMING TO
 154 This ancillary data model conforms to the POSIX.1g draft, 4.4BSD-Lite,
 155 the IPv6 advanced API described in RFC\ 2292 and SUSv2.
 156 .BR CMSG_ALIGN ()
 157 is a Linux extension.
 158 .SH NOTES
 159 For portability, ancillary data should be accessed using only the macros
 160 described here.
 161 .BR CMSG_ALIGN ()
 162 is a Linux extension and should not be used in portable programs.
 163 .PP
 164 In Linux,
 165 .BR CMSG_LEN (),
 166 .BR CMSG_DATA (),
 167 and
 168 .BR CMSG_ALIGN ()
 169 are constant expressions (assuming their argument is constant),
 170 meaning that these values can be used to declare the size of global variables.
 171 This may not be portable, however.
 172 .SH EXAMPLE
 173 This code looks for the
 174 .B IP_TTL
 175 option in a received ancillary buffer:
 176 .PP
 177 .in +4n
 178 .EX
 179 struct msghdr msgh;
 180 struct cmsghdr *cmsg;
 181 int *ttlptr;
 182 int received_ttl;
 183
 184 /* Receive auxiliary data in msgh */
 185
 186 for (cmsg = CMSG_FIRSTHDR(&msgh); cmsg != NULL;
 187         cmsg = CMSG_NXTHDR(&msgh, cmsg)) {
 188     if (cmsg\->cmsg_level == IPPROTO_IP
 189             && cmsg\->cmsg_type == IP_TTL) {
 190         ttlptr = (int *) CMSG_DATA(cmsg);
 191         received_ttl = *ttlptr;
 192         break;
 193     }
 194 }
 195
 196 if (cmsg == NULL) {
 197     /* Error: IP_TTL not enabled or small buffer or I/O error */
 198 }
 199 .EE
 200 .in
 201 .PP
 202 The code below passes an array of file descriptors over a
 203 UNIX domain socket using
 204 .BR SCM_RIGHTS :
 205 .PP
 206 .in +4n
 207 .EX
 208 struct msghdr msg = { 0 };
 209 struct cmsghdr *cmsg;
 210 int myfds[NUM_FD];  /* Contains the file descriptors to pass */
 211 char iobuf[1];
 212 struct iovec io = {
 213     .iov_base = iobuf,
 214     .iov_len = sizeof(iobuf)
 215 };
 216 union {         /* Ancillary data buffer, wrapped in a union
 217                    in order to ensure it is suitably aligned */
 218     char buf[CMSG_SPACE(sizeof(myfds))];
 219     struct cmsghdr align;
 220 } u;
 221
 222 msg.msg_iov = &io;
 223 msg.msg_iovlen = 1;
 224 msg.msg_control = u.buf;
 225 msg.msg_controllen = sizeof(u.buf);
 226 cmsg = CMSG_FIRSTHDR(&msg);
 227 cmsg\->cmsg_level = SOL_SOCKET;
 228 cmsg\->cmsg_type = SCM_RIGHTS;
 229 cmsg\->cmsg_len = CMSG_LEN(sizeof(int) * NUM_FD);
 230 memcpy(CMSG_DATA(cmsg), myfds, NUM_FD * sizeof(int));
 231 .EE
 232 .in
 233 .SH SEE ALSO
 234 .BR recvmsg (2),
 235 .BR sendmsg (2)
 236 .PP
 237 RFC\ 2292