share/man/man3/CMSG_DATA.3

   1 .\"     $NetBSD$
   2 .\"     $OpenBSD: CMSG_DATA.3,v 1.5 2008/03/24 16:11:07 deraadt Exp $
   3 .\" Written by Jared Yanovich <jaredy@openbsd.org>
   4 .\" Public domain, July 3, 2005
   5 .Dd June 20, 2008
   6 .Dt CMSG_DATA 3
   7 .Os
   8 .Sh NAME
   9 .Nm CMSG_DATA ,
  10 .Nm CMSG_FIRSTHDR ,
  11 .Nm CMSG_LEN ,
  12 .Nm CMSG_NXTHDR ,
  13 .Nm CMSG_SPACE
  14 .Nd socket control message routines
  15 .Sh SYNOPSIS
  16 .In sys/socket.h
  17 .Ft void *
  18 .Fn CMSG_DATA "struct cmsghdr *"
  19 .Ft struct cmsghdr *
  20 .Fn CMSG_FIRSTHDR "struct msghdr *"
  21 .Ft size_t
  22 .Fn CMSG_LEN "size_t"
  23 .Ft struct cmsghdr *
  24 .Fn CMSG_NXTHDR "struct msghdr *" "struct cmsghdr *"
  25 .Ft size_t
  26 .Fn CMSG_SPACE "size_t"
  27 .Sh DESCRIPTION
  28 The control message API is used to construct ancillary data objects for
  29 use in control messages sent and received across sockets.
  30 .Pp
  31 Control messages are passed around by the
  32 .Xr recvmsg 2
  33 and
  34 .Xr sendmsg 2
  35 system calls.
  36 The
  37 .Vt cmsghdr
  38 structure, described in
  39 .Xr recvmsg 2 ,
  40 is used to specify a chain of control messages.
  41 .Pp
  42 These routines should be used instead of directly accessing the control
  43 message header members and data buffers as they ensure that necessary
  44 alignment constraints are met.
  45 .Pp
  46 The following routines are provided:
  47 .Bl -tag -width Ds
  48 .It Fn CMSG_DATA cmsg
  49 This routine accesses the data portion of the control message header
  50 .Fa cmsg .
  51 It ensures proper alignment constraints on the beginning of ancillary
  52 data are met.
  53 .It Fn CMSG_FIRSTHDR mhdr
  54 This routine accesses the first control message attached to the
  55 message
  56 .Fa msg .
  57 If no control messages are attached to the message, this routine
  58 returns
  59 .Dv NULL .
  60 .It Fn CMSG_LEN len
  61 This routine determines the size in bytes of a control message,
  62 which includes the control message header.
  63 .Fa len
  64 specifies the length of the data held by the control message.
  65 This value is what is normally stored in the
  66 .Fa cmsg_len
  67 of each control message.
  68 This routine accounts for any alignment constraints on the beginning of
  69 ancillary data.
  70 This macro might not evaluate to a compile-time constant.
  71 .It Fn CMSG_NXTHDR mhdr cmsg
  72 This routine returns the location of the control message following
  73 .Fa cmsg
  74 in the message
  75 .Fa mhdr .
  76 If
  77 .Fa cmsg
  78 is the last control message in the chain, this routine returns
  79 .Dv NULL .
  80 .It Fn CMSG_SPACE len
  81 This routine determines the size in bytes needed to hold a control
  82 message and its contents of length
  83 .Fa len ,
  84 which includes the control message header.
  85 This value is what is normally stored in
  86 .Fa msg_msgcontrollen .
  87 This routine accounts for any alignment constraints on the beginning of
  88 ancillary data as well as any needed to pad the next control message.
  89 This macro might not evaluate to a compile-time constant.
  90 .El
  91 .Sh EXAMPLES
  92 The following example constructs a control message containing a file
  93 descriptor and passes it over a socket:
  94 .Bd -literal -offset indent
  95 struct msghdr    msg;
  96 struct cmsghdr  *cmsg;
  97 /* We use a union to make sure hdr is aligned */
  98 union {
  99         struct cmsghdr hdr;
 100         unsigned char    buf[CMSG_SPACE(sizeof(int))];
 101 } *cmsgbuf;
 102
 103 /*
 104  * We allocate in the heap instead of the stack to avoid C99
 105  * variable stack allocation, which breaks gcc -fstack-protector.
 106  */
 107 if ((cmsgbuf = malloc(sizeof(*cmsgbuf))) == NULL)
 108         err(1, "malloc");
 109 (void)memset(&msg, 0, sizeof(msg));
 110 msg.msg_control = cmsgbuf->buf;
 111 msg.msg_controllen = sizeof(cmsgbuf->buf);
 112
 113 cmsg = CMSG_FIRSTHDR(&msg);
 114 cmsg->cmsg_len = CMSG_LEN(sizeof(int));
 115 cmsg->cmsg_level = SOL_SOCKET;
 116 cmsg->cmsg_type = SCM_RIGHTS;
 117 *(int *)CMSG_DATA(cmsg) = fd;
 118
 119 if (sendmsg(s, &msg, 0) == -1)
 120         err(1, "sendmsg");
 121 free(cmsgbuf);
 122 .Ed
 123 .Pp
 124 And an example that receives and decomposes the control message:
 125 .Bd -literal -offset indent
 126 struct msghdr    msg;
 127 struct cmsghdr  *cmsg;
 128 union {
 129         struct cmsghdr hdr;
 130         unsigned char    buf[CMSG_SPACE(sizeof(int))];
 131 } *cmsgbuf;
 132
 133 if ((cmsgbuf = malloc(sizeof(*cmsgbuf))) == NULL)
 134         err(1, "malloc");
 135 (void)memset(&msg, 0, sizeof(msg));
 136 msg.msg_control = cmsgbuf->buf;
 137 msg.msg_controllen = sizeof(cmsgbuf->buf);
 138
 139 if (recvmsg(s, &msg, 0) == -1)
 140         err(1, "recvmsg");
 141 if ((msg.msg_flags & (MSG_TRUNC|MSG_CTRUNC))
 142         errx(1, "control message truncated");
 143 for (cmsg = CMSG_FIRSTHDR(&msg); cmsg != NULL;
 144     cmsg = CMSG_NXTHDR(&msg, cmsg)) {
 145         if (cmsg->cmsg_len == CMSG_LEN(sizeof(int)) &&
 146             cmsg->cmsg_level == SOL_SOCKET &&
 147             cmsg->cmsg_type == SCM_RIGHTS) {
 148                 fd = *(int *)CMSG_DATA(cmsg);
 149                 /* Do something with the descriptor. */
 150         }
 151 }
 152 free(cmsgbuf);
 153 .Ed
 154 .Sh SEE ALSO
 155 .Xr recvmsg 2 ,
 156 .Xr sendmsg 2 ,
 157 .Xr socket 2
 158 .Sh HISTORY
 159 The control message API first appeared in
 160 .Bx 4.2 .