Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
CMSG_DATA(3)	       FreeBSD Library Functions 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) sys-
     tem 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 be-
	     ginning 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	begin-
	     ning of ancillary data.

     CMSG_NXTHDR(mhdr, cmsg)
	     This routine returns the location of the control message follow-
	     ing cmsg in the message mhdr.  If cmsg is the last	control	mes-
	     sage in the chain,	this routine returns NULL.

     CMSG_SPACE(len)
	     This routine determines the size in bytes needed to hold a	con-
	     trol 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 con-
	     straints 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 de-
     scriptor and passes it over a socket:

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

	   io_vector[0].iov_base = &ch;
	   io_vector[0].iov_len	= 1;

	   memset(&msg,	0, sizeof(msg));
	   msg.msg_control = &cmsgbuf.buf;
	   msg.msg_controllen =	sizeof(cmsgbuf.buf);
	   msg.msg_iov = io_vector;
	   msg.msg_iovlen = 1;

	   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;
	   struct iovec	io_vector[1];

	   io_vector[0].iov_base = &ch;
	   io_vector[0].iov_len	= 1;

	   memset(&msg,	0, sizeof(msg));
	   msg.msg_control = &cmsgbuf.buf;
	   msg.msg_controllen =	sizeof(cmsgbuf.buf);
	   msg.msg_iov = io_vector;
	   msg.msg_iovlen = 1;

	   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.

FreeBSD	13.0			 April 3, 2017			  FreeBSD 13.0

NAME | SYNOPSIS | DESCRIPTION | EXAMPLES | SEE ALSO | HISTORY

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=CMSG_DATA&sektion=3&manpath=OpenBSD+6.9>

home | help