CMSG_DATA man page on OpenBSD

Man page or keyword search:  
man Server   11362 pages
apropos Keyword Search (all sections)
Output format
OpenBSD logo
[printable version]

CMSG_DATA(3)		  OpenBSD Programmer's Manual		  CMSG_DATA(3)

NAME
     CMSG_DATA, CMSG_FIRSTHDR, CMSG_LEN, CMSG_NXTHDR, CMSG_SPACE - socket
     control message routines

SYNOPSIS
     #include <sys/socket.h>

     void *
     CMSG_DATA(struct cmsghdr *);

     struct cmsghdr *
     CMSG_FIRSTHDR(struct msghdr *);

     size_t
     CMSG_LEN(size_t);

     struct cmsghdr *
     CMSG_NXTHDR(struct msghdr *, struct cmsghdr *);

     size_t
     CMSG_SPACE(size_t);

DESCRIPTION
     The control message API is used to construct ancillary data objects for
     use in control messages sent and received across sockets.

     Control messages are passed around by the recvmsg(2) and sendmsg(2)
     system calls.  The cmsghdr structure, described in recvmsg(2), is used to
     specify a chain of control messages.

     These routines should be used instead of directly accessing the control
     message header members and data buffers as they ensure that necessary
     alignment constraints are met.

     The following routines are provided:

     CMSG_DATA(cmsg)
	     This routine accesses the data portion of the control message
	     header cmsg.  It ensures proper alignment constraints on the
	     beginning of ancillary data are met.

     CMSG_FIRSTHDR(mhdr)
	     This routine accesses the first control message attached to the
	     message msg.  If no control messages are attached to the message,
	     this routine returns NULL.

     CMSG_LEN(len)
	     This routine determines the size in bytes of a control message,
	     which includes the control message header.	 len specifies the
	     length of the data held by the control message.  This value is
	     what is normally stored in the cmsg_len of each control message.
	     This routine accounts for any alignment constraints on the
	     beginning of ancillary data.

     CMSG_NXTHDR(mhdr, cmsg)
	     This routine returns the location of the control message
	     following cmsg in the message mhdr.  If cmsg is the last control
	     message in the chain, this routine returns NULL.

     CMSG_SPACE(len)
	     This routine determines the size in bytes needed to hold a
	     control message and its contents of length len, which includes
	     the control message header.  This value is what is normally
	     stored in msg_msgcontrollen.  This routine accounts for any
	     alignment constraints on the beginning of ancillary data as well
	     as any needed to pad the next control message.

EXAMPLES
     The following example constructs a control message containing a file
     descriptor and passes it over a socket:

	   struct msghdr    msg;
	   struct cmsghdr  *cmsg;
	   union {
		   struct cmsghdr hdr;
		   unsigned char    buf[CMSG_SPACE(sizeof(int))];
	   } cmsgbuf;

	   memset(&msg, 0, sizeof(msg));
	   msg.msg_control = &cmsgbuf.buf;
	   msg.msg_controllen = sizeof(cmsgbuf.buf);

	   cmsg = CMSG_FIRSTHDR(&msg);
	   cmsg->cmsg_len = CMSG_LEN(sizeof(int));
	   cmsg->cmsg_level = SOL_SOCKET;
	   cmsg->cmsg_type = SCM_RIGHTS;
	   *(int *)CMSG_DATA(cmsg) = fd;

	   if (sendmsg(s, &msg, 0) == -1)
		   err(1, "sendmsg");

     And an example that receives and decomposes the control message:

	   struct msghdr    msg;
	   struct cmsghdr  *cmsg;
	   union {
		   struct cmsghdr hdr;
		   unsigned char    buf[CMSG_SPACE(sizeof(int))];
	   } cmsgbuf;

	   memset(&msg, 0, sizeof(msg));
	   msg.msg_control = &cmsgbuf.buf;
	   msg.msg_controllen = sizeof(cmsgbuf.buf);

	   if (recvmsg(s, &msg, 0) == -1)
		   err(1, "recvmsg");
	   if ((msg.msg_flags & MSG_TRUNC) || (msg.msg_flags & MSG_CTRUNC))
		   errx(1, "control message truncated");
	   for (cmsg = CMSG_FIRSTHDR(&msg); cmsg != NULL;
	       cmsg = CMSG_NXTHDR(&msg, cmsg)) {
		   if (cmsg->cmsg_len == CMSG_LEN(sizeof(int)) &&
		       cmsg->cmsg_level == SOL_SOCKET &&
		       cmsg->cmsg_type == SCM_RIGHTS) {
			   fd = *(int *)CMSG_DATA(cmsg);
			   /* Do something with the descriptor. */
		   }
	   }

SEE ALSO
     recvmsg(2), sendmsg(2), socket(2)

HISTORY
     The control message API first appeared in 4.2BSD.

OpenBSD 4.9			March 24, 2008			   OpenBSD 4.9
[top]

List of man pages available for OpenBSD

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net