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