original/man3/cmsg.3

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