View Source: cmsg(3) - Waikato Linux Users Group

Edit PageHistory Diff Info LikePages
CMSG
!!!CMSG
NAME
SYNOPSIS
DESCRIPTION
EXAMPLE
NOTES
CONFORMS TO
SEE ALSO
----
!!NAME


CMSG_ALIGN, CMSG_SPACE, CMSG_NXTHDR, CMSG_FIRSTHDR - Access ancillary data.
!!SYNOPSIS


__#include __


__struct cmsghdr *CMSG_FIRSTHDR(struct msghdr
*__''msgh''__);
struct cmsghdr *CMSG_NXTHDR(struct msghdr
*__''msgh''__, struct cmsghdr
*__''cmsg''__);
size_t CMSG_ALIGN(size_t__ ''length''__);
size_t CMSG_SPACE(size_t__ ''length''__);
size_t CMSG_LEN(size_t__ ''length''__);
unsigned char *CMSG_DATA(struct cmsghdr
*__''cmsg''__);__


struct cmsghdr {
socklen_t   cmsg_len;   /* data byte count, including header */
int         cmsg_level; /* originating protocol */
int         cmsg_type;  /* protocol-specific type */
/* followed by  unsigned char   cmsg_data[[]; */
};
!!DESCRIPTION


These macros are used to create and access control messages
(also called ancillary data) that are not a part of the
socket payload. This control information may include the
interface the packet was received on, various rarely used
header fields, an extended error description, a set of file
descriptors or unix credentials. For instance, control
messages can be used to send additional header fields such
as IP options. Ancillary data is sent by calling
sendmsg(2) and received by calling recvmsg(2).
See their manual pages for more information.


Ancillary data is a sequence of __struct cmsghdr__
structures with appended data. This sequence should only be
accessed using the macros described in this manual page and
never directly. See the specific protocol man pages for the
available control message types. The maximum ancillary
buffer size allowed per socket can be set using the
__net.core.optmem_max__ sysctl; see
socket(7).


__CMSG_FIRSTHDR__ returns a pointer to the first
__cmsghdr__ in the ancillary data buffer associated with
the passed __msghdr__.


__CMSG_NXTHDR__ returns the next valid __cmsghdr__
after the passed __cmsghdr.__ It returns __NULL__ when
there isn't enough space left in the buffer.


__CMSG_ALIGN__, given a length, returns it including the
required alignment. This is a constant
expression.


__CMSG_SPACE__ returns the number of bytes an ancillary
element with payload of the passed data length occupies.
This is a constant expression.


__CMSG_DATA__ returns a pointer to the data portion of a
__cmsghdr__.


__CMSG_LEN__ returns the value to store in the
''cmsg_len'' member of the __cmsghdr__ structure,
taking into account any necessary alignment. It takes the
data length as an argument. This is a constant
expression.


To create ancillary data, first initialize the
''msg_controllen'' member of the __msghdr__ with the
length of the control message buffer. Use
__CMSG_FIRSTHDR__ on the __msghdr__ to get the first
control message and __CMSG_NEXTHDR__ to get all
subsequent ones. In each control message, initialize
''cmsg_len'' (with __CMSG_LEN__), the other
__cmsghdr__ header fields, and the data portion using
__CMSG_DATA__. Finally, the ''msg_controllen'' field
of the __msghdr__ should be set to the sum of the
__CMSG_SPACE__ of the length of all control messages in
the buffer. For more information on the __msghdr__, see
recvmsg(2).


When the control message buffer is too short to store all
messages, the __MSG_CTRUNC__ flag is set in the
''msg_flags'' member of the __msghdr__.
!!EXAMPLE


This code looks for the __IP_TTL__ option in a received
ancillary buffer:


struct msghdr msgh;
struct cmsghdr *cmsg;
int *ttlptr;
int received_ttl;
/* Receive auxiliary data in msgh */
for (cmsg = CMSG_FIRSTHDR(


The code below passes an array of file descriptors over a
Unix socket using __SCM_RIGHTS__:


struct msghdr msg = {0};
struct cmsghdr *cmsg;
int myfds[[NUM_FD]; /* Contains the file descriptors to pass. */
char buf[[CMSG_SPACE(sizeof myfds)];  /* ancillary data buffer */
int *fdptr;
msg.msg_control = buf;
msg.msg_controllen = sizeof buf;
cmsg = CMSG_FIRSTHDR(
!!NOTES


For portability, ancillary data should be accessed only
using the macros described here. __CMSG_ALIGN__ is a
Linux extension and should be not used in portable
programs.


In Linux, __CMSG_LEN__, __CMSG_DATA__, and
__CMSG_ALIGN__ are constant expressions (assuming their
argument is constant) - this could be used to declare the
size of global variables. This may be not portable,
however.
!!CONFORMS TO


This ancillary data model conforms to the POSIX.1003.1g
draft, 4.4BSD-Lite, the IPv6 advanced API described in
RFC2292 and the Single Unix specification v2.
__CMSG_ALIGN__ is a Linux extension.
!!SEE ALSO


sendmsg(2), recvmsg(2)


RFC 2292
----
9 pages link to cmsg(3):
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.
Last edited on Tuesday, June 4, 2002 12:24:14 am by "perry"
Edit PageHistory Diff Info LikePages