= nng_msg_reserve(3)
//
// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech>
// Copyright 2018 Capitar IT Group BV <info@capitar.com>
//
// This document is supplied under the terms of the MIT License, a
// copy of which should be located in the distribution where this
// file was obtained (LICENSE.txt).  A copy of the license may also be
// found online at https://opensource.org/licenses/MIT.
//

== NAME

nng_msg_reserve - reserve storage for a message

== SYNOPSIS

[source, c]
----
#include <nng/nng.h>

int nng_msg_reserve(nng_msg *msg, size_t capacity);
----

== DESCRIPTION

The `nng_msg_reserve()` function ensures a message has allocated enough storage 
to accommodate a body of the given length.
This message attempts to avoid extra allocations,
and will reuse the existing memory when possible.

TIP: Using this message before xref:nng_msg_append.3.adoc[`nng_msg_append()`]
will prevent additional memory allocations until the message's length exceeds
the alotted capacity.

NOTE: Pointers to message body and header content obtained prior to this
function must not be in use, as the underlying memory used for the message
may have changed, particularly if the message capacity is increasing.

== RETURN VALUES

This function returns 0 on success, and non-zero otherwise.

== ERRORS

[horizontal]
`NNG_ENOMEM`:: Insufficient free memory exists to reallocate a message.

== SEE ALSO

[.text-left]
xref:nng_msg_capacity.3.adoc[nng_msg_capacity(3)],
xref:nng_msg_alloc.3.adoc[nng_msg_alloc(3)],
xref:nng_msg_append.3.adoc[nng_msg_append(3)],
xref:nng_msg_body.3.adoc[nng_msg_body(3)],
xref:nng_msg_chop.3.adoc[nng_msg_chop(3)],
xref:nng_msg_free.3.adoc[nng_msg_free(3)],
xref:nng_msg_insert.3.adoc[nng_msg_insert(3)],
xref:nng_msg_len.3.adoc[nng_msg_len(3)],
xref:nng_msg_trim.3.adoc[nng_msg_trim(3)],
xref:nng_strerror.3.adoc[nng_strerror(3)],
xref:nng_msg.5.adoc[nng_msg(5)],
xref:nng.7.adoc[nng(7)]