Add & document msg_capacity, msg_reserve (#1458)

* Add & document msg_capacity, msg_reserve

* reserve/capacity code style

* Documentation references to reserve/capacity

1 files changed, 63 insertions, 0 deletions

diff --git a/docs/man/nng_msg_reserve.3.adoc b/docs/man/nng_msg_reserve.3.adoc
new file mode 100644
index 00000000..254c1e94
--- /dev/null
+++ b/docs/man/nng_msg_reserve.3.adoc
@@ -0,0 +1,63 @@
+= 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)]