'\" t
.\"     Title: nn_allocmsg
.\"    Author: [see the "AUTHOR(S)" section]
.\" Generator: Asciidoctor 2.0.26
.\"      Date: 2021-02-08
.\"    Manual: NNG Reference Manual
.\"    Source: \ \&
.\"  Language: English
.\"
.TH "NN_ALLOCMSG" "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_allocmsg \- allocate message (compatible API)
.SH "SYNOPSIS"
.sp
.if n .RS 4
.nf
.fam C
#include <nanomsg/nn.h>

void *nn_allocmsg(size_t size, int type);
.fam
.fi
.if n .RE
.SH "DESCRIPTION"
.sp
The \f(CRnn_allocmsg()\fP allocates a message structure of size \fIsize\fP, and is
primarily used to support zero\-copy send operations, making use of the
\f(CRNNG_MSG\fP special size indicator.
The value returned is a pointer to the start of the message payload buffer.
.sp
The value of \fIsize\fP must be positive, and small enough to hold reasonable
message data plus book\-keeping information.
.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 function is provided for API
compatibility with legacy \fIlibnanomsg\fP.
Consider using the relevant modern API instead.
.sp .5v
.RE
.sp
The value of \fItype\fP \fBmust\fP be zero.
(This argument was reserved to support different kinds of memory spaces
for RDMA devices, but this was never developed in the legacy API.)
.sp
The returned message must be disposed of by either
\f(CRnn_freemsg()\fP or
\f(CRnn_send()\fP when the caller is finished with it.
.SH "RETURN VALUES"
.sp
This function returns a pointer to message buffer space, or \f(CRNULL\fP
on failure.
.SH "ERRORS"
.sp
\f(CRENOMEM\fP
.RS 4
Insufficient memory is available.
.RE
.sp
\f(CREINVAL\fP
.RS 4
An invalid \fIsize\fP or \fItype\fP was specified.
.RE
.sp
\f(CRETERM\fP
.RS 4
The library is shutting down.
.RE
.SH "SEE ALSO"
.sp
nn_errno(3compat),
nn_freemsg(3compat),
nn_reallocmsg(3compat),
nn_send(3compat),
nng_compat(3compat),
nng(7)