'\" t
.\"     Title: nn_cmsg
.\"    Author: [see the "AUTHOR(S)" section]
.\" Generator: Asciidoctor 2.0.26
.\"      Date: 2021-02-08
.\"    Manual: NNG Reference Manual
.\"    Source: \ \&
.\"  Language: English
.\"
.TH "NN_CMSG" "3compat" "2021-02-08" "\ \&" "NNG Reference Manual"
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.ss \n[.ss] 0
.nh
.ad l
.de URL
\fI\\$2\fP <\\$1>\\$3
..
.als MTO URL
.if \n[.g] \{\
.  mso www.tmac
.  am URL
.    ad l
.  .
.  am MTO
.    ad l
.  .
.  LINKSTYLE blue R < >
.\}
.SH "NAME"
nn_cmsg \- message control data (compatible API)
.SH "SYNOPSIS"
.sp
.if n .RS 4
.nf
.fam C
#include <nanomsg/nn.h>

struct nn_cmsghdr {
    size_t cmsg_len;
    int\&    cmsg_level;
    int\&    cmsg_type;
};
.fam
.fi
.if n .RE
.SH "DESCRIPTION"
.sp
The \f(CRnn_cmsghdr\fP structure describes a block of control data that is
associated with a message either sent by \f(CRnn_sendmsg()\fP
or received by \f(CRnn_recvmsg()\fP.
.if n .sp
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
.B Note
.ps -1
.br
.sp
This structure and supporting macros are provided for API
compatibility with legacy \fIlibnanomsg\fP.
Consider using the relevant modern API instead.
.sp .5v
.RE
.sp
Each header is followed by \f(CRcmsg_len\fP bytes of data, plus any padding required
to align the structure.
.sp
The only defined ancillary data at this time is the protocol headers used by
the protocols.
This uses \f(CRcmsg_level\fP set to \f(CRPROTO_SP\fP and the \f(CRcmsg_type\fP set to
\f(CRSP_HDR\fP.
The actual data for this will vary from depending on the protocol used.
.sp
Convenience macros are provided to make working with these fields easier.
.sp
\f(CRstruct nn_cmsghdr *NN_CMSG_FIRSTHDR(struct nn_msghdr *\fIhdr\fP)\fP
.RS 4
This macro returns the first \f(CRstruct nn_cmsghdr\fP header in \fIhdr\fP.
.RE
.sp
\f(CRstruct nn_cmsghdr *NN_CMSG_NXTHDR(struct nn_msghdr *\fIhdr\fP, struct nn_cmsghdr *\fIch\fP)\fP
.RS 4
This macro returns a pointer to the next \f(CRstruct nn_cmsghdr\fP in \fIhdr\fP after \fIch\fP.
.RE
.sp
\f(CRvoid *NN_CMSG_DATA(struct nn_cmsghdr *\fIch\fP)\fP
.RS 4
This macro returns a pointer to the header\-specific data for \fIch\fP.
.RE
.sp
\f(CRsize_t NN_CMSG_ALIGN(size_t \fIlen\fP)\fP
.RS 4
This macro returns the length specified by \fIlen\fP, plus any padding required to
provide the necessary alignment for another structure.
.RE
.sp
\f(CRsize_t NN_CMSG_SPACE(size_t \fIlen\fP)\fP
.RS 4
This macro returns the amount of space required for a header, with \fIlen\fP
bytes of following data, and any necessary padding.
.RE
.sp
\f(CRsize_t NN_CMSG_LEN(size_t \fIlen\fP)\fP
.RS 4
This macro evaluates to the length of the header (including alignment),
and the associated data of length \fIlen\fP, but without any trailing padding
to align for another header.
.RE
.SH "SEE ALSO"
.sp
nn_recvmsg(3compat),
nn_sendmsg(3compat),
nng_compat(3compat),
nng(7)