3 files changed, 156 insertions, 0 deletions
diff --git a/docs/ref/SUMMARY.md b/docs/ref/SUMMARY.md
index eb20a8c8..7e9bcc2d 100644
--- a/docs/ref/SUMMARY.md
+++ b/docs/ref/SUMMARY.md
@@ -2,6 +2,10 @@
 
 - [API Reference](./api/index.md)
 
+  - [Messages](./api/msg/index.md)
+
+    - [nng_msg](./api/msg/nng_msg.md)
+
   - [Threading and Synchronization](./api/thr/index.md)
 
     - [nng_cv](./api/thr/nng_cv.md)
diff --git a/docs/ref/api/msg/index.md b/docs/ref/api/msg/index.md
new file mode 100644
index 00000000..18a3f620
--- /dev/null
+++ b/docs/ref/api/msg/index.md
@@ -0,0 +1,5 @@
+# Messages
+
+These interfaces deal with messages, used in the Scalability Protocols.
+
+- [nng_msg](./nng_msg.md) --- message
diff --git a/docs/ref/api/msg/nng_msg.md b/docs/ref/api/msg/nng_msg.md
new file mode 100644
index 00000000..84d6c273
--- /dev/null
+++ b/docs/ref/api/msg/nng_msg.md
@@ -0,0 +1,147 @@
+# nng_msg
+
+## NAME
+
+nng_msg --- message
+
+## SYNOPSIS
+
+```c
+#include <nng/nng.h>
+
+typedef struct nng_msg nng_msg;
+
+int nng_msg_alloc(nng_msg **msgp, size_t size);
+void nng_msg_free(nng_msg *msg);
+int nng_msg_dup(nng_msg **dup, nng_msg *msg);
+int nng_msg_realloc(nng_msg **msgp, size_t size);
+int nng_msg_reserve(nng_msg *msg, size_t capacity);
+size_t nng_msg_capacity(nng_msg *msg);
+```
+
+## DESCRIPTION
+
+An {{i:`nng_msg`}} represents a single {{i:message}} sent between Scalability Protocols peers.
+
+Messages in Scalability Protocols are the fundamental unit of transmission and reception,
+as these protocols are fundamentally message-oriented.
+
+> [!NOTE]
+> The `nng_msg` structure is opaque, and applications should never try to
+> rely on the size of it, nor access internal members directly.
+> This insulates the application from changes in subsequent _NNG_ versions
+> that would affect the binary representation of the `nng_msg` itself.
+
+Messages have a [body][nng_msg_body]{{hi:body}}, containing the application-supplied
+payload, and a [header][nng_msg_header]{{hi:header}}, containing protocol specific routing and similar
+related information.
+
+> [!TIP]
+> Only applications using [raw mode][raw] need to access the message header.
+
+### Creating and Destroying Messages
+
+Messages are allocated using {{i:`nng_msg_alloc`}},
+and are deallocated using {{i:`nng_msg_free`}}.
+
+The `nng_msg_alloc` function takes a _size_ argument, and returns a message
+with a preallocated body of that size in the _msgp_ parameter.
+
+Messages can be deallocated when no longer needed using `nng_msg_free`.
+
+A message may be duplicated using the {{i:`nng_msg_dup`}} function, which can be useful
+when a copy must be saved or modified. The contents of the duplicate message will
+be the same, but the actual pointers may be different, and the amount of reserved
+space may be different as well.
+
+### Message Size and Capacity
+
+The message size may be changed by use of the {{i:`nng_msg_realloc`}} function. This
+function will reallocate the underlying memory for the message referenced by _msgp_,
+preserving contents, to provide the new buffer, and return the new message in _msgp_.
+If the new size is smaller than the original message, it will
+truncate the message, but not perform any allocations.
+If the new message is different, then the original is freed.
+If reallocation fails due to insufficient memory, then the original is left intact.
+
+If message growth is anticipated, the {{i:`nng_msg_reserve`}} function can be used
+to ensure that the buffers underlying the message will be sufficient to hold a message
+of at least _capacity_ bytes. The actual message {{i:capacity}} can be obtained using the
+{{i:`nng_msg_capacity`}}. As long as the new size will not exceeed that capacity,
+any functions that change the message will do so without an allocation, and are guaranteed
+to succeed.
+
+> [!IMPORTANT]
+> Any pointers to message content obtained before a call to `nng_msg_realloc` or
+> `nng_msg_reserve` (or any other function that changes the message size) should be
+> treated as invalid, as the locations pointed to may be deallocated by these functions.
+
+### Performance Considerations
+
+While there are convenience wrappers for sending and receiving arrays of
+bytes, using message objects directly when possible will give better
+performance by reducing data copies and needless allocations.
+
+These functions are designed to try to avoid copying message contents
+by making use of scratch areas at the beginning and end of the message.
+These scratch areas, the "{{i:headroom}}" and "{{i:tailroom}}", are automatically
+included when allocating a message.
+
+Using `nng_msg_reserve` to ensure that adequate buffer space is availabe
+in advance can reduce repeated allocations and data copies when modifying messages.
+
+## RETURN VALUES
+
+The `nng_msg_alloc`, `nng_msg_dup`, `nng_msg_realloc`, and `nng_msg_reserve`
+functions return zero on success, or an error value on failure, typically `NNG_ENOMEM`.
+
+The `nng_msg_capacity` function returns the total body capacity of the message _msg_.
+
+## ERRORS
+
+- `NNG_ENOMEM`: Insufficient free memory exists to perform the operation.
+
+## Examples
+
+### Example 1: Preparing a message for use
+
+```c
+    #include <nng/nng.h>
+
+    nng_msg *m;
+    if (nng_msg_alloc(&m, strlen("content") + 1) != 0) {
+       // handle error
+    }
+    strcpy(nng_msg_body(m), "content");
+```
+
+### Example 2: Preallocating message content
+
+```c
+    if (nng_msg_alloc(&m, 1024) != 0) {
+        // handle error
+    }
+    while ((val64 = next_datum()) != 0) P
+        if (nng_msg_append_u64(m, val64) != 0) {
+            // handle error
+        }
+    }
+```
+
+## SEE ALSO
+
+[nng_aio_get_msg][nng_aio_get_msg],
+[nng_msg_body][nng_msg_body],
+[nng_msg_header][nng_msg_header],
+[nng_msg_set_pipe][nng_msg_set_pipe],
+[nng_recvmsg][nng_recvmsg],
+[nng_sendmsg][nng_sendmsg]
+
+[nng_msg_body]: ./nng_msg_body.md
+[nng_msg_header]: ./nng_msg_header.md
+[nng_msg_set_pipe]: ./nng_msg_set_pipe.md
+[nng_aio_get_msg]: TODO.md
+[nng_aio_set_msg]: TODO.md
+[nng_recvmsg]: TODO.md
+[nng_sendmsg]: TODO.md
+[raw]: TODO.md