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