nng_recv* added

8 files changed, 480 insertions, 0 deletions

diff --git a/docs/reference/src/SUMMARY.md b/docs/reference/src/SUMMARY.md
index 40a02f7d..1a911e37 100644
--- a/docs/reference/src/SUMMARY.md
+++ b/docs/reference/src/SUMMARY.md
@@ -61,6 +61,9 @@
     - [nng_pull_open](sock/nng_pull_open.md)
     - [nng_push_open](sock/nng_push_open.md)
     - [nng_respondent_open](sock/nng_respondent_open.md)
+    - [nng_recv](sock/nng_recv.md)
+    - [nng_recv_aio](sock/nng_recv_aio.md)
+    - [nng_recvmsg](sock/nng_recvmsg.md)
     - [nng_rep_open](sock/nng_rep_open.md)
     - [nng_req_open](sock/nng_req_open.md)
     - [nng_sub_open](sock/nng_sub_open.md)
diff --git a/docs/reference/src/refs.md b/docs/reference/src/refs.md
index cb5c74f1..98a3d153 100644
--- a/docs/reference/src/refs.md
+++ b/docs/reference/src/refs.md
@@ -54,6 +54,12 @@
 [nng_surveyor_open]: ../sock/nng_surveyor_open.md
 [nng_close]: ../sock/nng_close.md
 [nng_device]: ../sock/nng_device.md
+[nng_recv]: ../sock/nng_recv.md
+[nng_recv_aio]: ../sock/nng_recv_aio.md
+[nng_recvmsg]: ../sock/nng_recvmsg.md
+[nng_send]: ../sock/nng_send.md
+[nng_send_aio]: ../sock/nng_send_aio.md
+[nng_sendmsg]: ../sock/nng_sendmsg.md
 
 <!-- Messages -->
 
diff --git a/docs/reference/src/sock/nng_recv.md b/docs/reference/src/sock/nng_recv.md
new file mode 100644
index 00000000..178661f7
--- /dev/null
+++ b/docs/reference/src/sock/nng_recv.md
@@ -0,0 +1,83 @@
+# nng_recv
+
+## NAME
+
+nng_recv --- recv data
+
+## SYNOPSIS
+
+```c
+#include <nng/nng.h>
+
+int nng_recv(nng_socket s, void *data, size_t *sizep, int flags);
+```
+
+## DESCRIPTION
+
+The `nng_recv()` receives a message from the [socket][socket] _s_,
+obtaining its body content.
+
+The _flags_ is a bit mask that may contain any of the following values:
+
+- `NNG_FLAG_NONBLOCK`:\
+  The function returns immediately, even if no message is available.
+  Without this flag, the function will wait until a message is received
+  by the socket _s_, or any configured timer expires.
+
+- `NNG_FLAG_ALLOC`:\
+  If this flag is present, then a {{i:zero-copy}} mode is used.
+  In this case the caller must set the value of _data_ to the location
+  of another pointer (of type `void *`), and the _sizep_ pointer must be set
+  to a location to receive the size of the message body.
+  The function will then allocate a message buffer
+  (as if by [`nng_alloc()`][nng_alloc]), fill it with
+  the message body, and store it at the address referenced by _data_, and update
+  the size referenced by _sizep_.
+  The caller is responsible for disposing of the received buffer either by
+  the [`nng_free()`][nng_free] function or passing the message (also
+  with the {{i:`NNG_FLAG_ALLOC`}} flag) in a call to [`nng_send()`][nng_send].
+
+If the special flag `NNG_FLAG_ALLOC` (see above) is not specified, then the
+caller must set _data_ to a buffer to receive the message body content,
+and must store the size of that buffer at the location pointed to by _sizep_.
+When the function returns, if it is successful, the size at _sizep_ will be
+updated with the actual message body length copied into _data_.
+
+> [!NOTE]
+> The semantics of what receiving a message means vary from protocol to
+> protocol, so examination of the protocol documentation is encouraged.
+> (For example, with a [_REQ_][req] socket a message may only be received
+> after a request has been sent, and a [_SUB_][sub] socket
+> may only receive messages corresponding to topics to which it has subscribed.)
+> Furthermore, some protocols may not support receiving data at all, such as
+> [_PUB_][pub].
+
+> [!TIP]
+> The `NNG_FLAG_ALLOC` flag can be used to reduce data copies, thereby
+> increasing performance, particularly if the buffer is reused to send
+> a response using the same flag. However, the [`nng_recvmsg()`][nng_recvmsg] function is even better in this regard, and should be preferred over this
+> function when possible.
+
+## RETURN VALUES
+
+This function returns 0 on success, and non-zero otherwise.
+
+## ERRORS
+
+- `NNG_EAGAIN`: The operation would block, but `NNG_FLAG_NONBLOCK` was specified.
+- `NNG_ECLOSED`: The socket _s_ is not open.
+- `NNG_EINVAL`: An invalid set of _flags_ was specified.
+- `NNG_EMSGSIZE`: The received message did not fit in the size provided.
+- `NNG_ENOMEM`: Insufficient memory is available.
+- `NNG_ENOTSUP`: The protocol for socket _s_ does not support receiving.
+- `NNG_ESTATE`: The socket _s_ cannot receive data in this state.
+- `NNG_ETIMEDOUT`: The operation timed out.
+
+## SEE ALSO
+
+[nng_alloc][nng_alloc],
+[nng_free][nng_free],
+[nng_recvmsg][nng_recvmsg],
+[nng_send][nng_send]
+
+{{#include ../refs.md}}
diff --git a/docs/reference/src/sock/nng_recv_aio.md b/docs/reference/src/sock/nng_recv_aio.md
new file mode 100644
index 00000000..257ec691
--- /dev/null
+++ b/docs/reference/src/sock/nng_recv_aio.md
@@ -0,0 +1,65 @@
+# nng_recv_aio
+
+## NAME
+
+nng_recv_aio --- receive message asynchronously
+
+## SYNOPSIS
+
+```c
+#include <nng/nng.h>
+
+void nng_recv_aio(nng_socket s, nng_aio *aio);
+```
+
+## DESCRIPTION
+
+The `nng_recv_aio()` function receives a [message][msg] using the
+[socket][socket] _s_ asynchronously.
+
+When a message is successfully received by the socket, it is
+stored in the _aio_ by an internal call equivalent to
+[`nng_aio_set_msg()`][nng_aio_set_msg], then the completion
+callback on the _aio_ is executed.
+In this case, [`nng_aio_result()`][nng_aio_result] will
+return zero.
+The callback function is responsible for retrieving the message
+and disposing of it appropriately.
+
+> [!IMPORTANT]
+> Failing to dispose of successfully received messages
+> will leak the memory associated with it.
+
+If for some reason the asynchronous receive cannot be completed
+successfully (including by being canceled or timing out), then
+the callback will still be executed,
+but `nng_aio_result()` will be non-zero.
+
+> [!NOTE]
+> The semantics of what receiving a message means varies from protocol to
+> protocol, so examination of the protocol documentation is encouraged.
+> For example, with [_PUB_][pub] socket the data is broadcast, so that
+> only peers who have a suitable subscription will be able to receive it.
+> Furthermore, some protocols may not support receiving (such as
+> _PUB_) or may require other conditions.
+> (For example, [_REQ_][req] sockets cannot normally receive data
+> until they have first sent a request.)
+
+## ERRORS
+
+- `NNG_ECANCELED`: The operation was aborted.
+- `NNG_ECLOSED`: The socket _s_ is not open.
+- `NNG_ENOMEM`: Insufficient memory is available.
+- `NNG_ENOTSUP`: The protocol for socket _s_ does not support receiving.
+- `NNG_ESTATE`: The socket _s_ cannot receive data in this state.
+- `NNG_ETIMEDOUT`: The receive timeout expired.
+
+## SEE ALSO
+
+[Messages][msg],
+[Sockets][socket],
+[Asynchronous I/O][aio],
+[nng_aio_get_msg][nng_aio_get_msg],
+[nng_msg_alloc][nng_msg_alloc]
+
+{{#include ../refs.md}}
diff --git a/docs/reference/src/sock/nng_recvmsg.md b/docs/reference/src/sock/nng_recvmsg.md
new file mode 100644
index 00000000..3d3912c0
--- /dev/null
+++ b/docs/reference/src/sock/nng_recvmsg.md
@@ -0,0 +1,68 @@
+# nng_recvmsg
+
+## NAME
+
+nng_recvmsg --- receive a message
+
+## SYNOPSIS
+
+```c
+#include <nng/nng.h>
+
+int nng_recvmsg(nng_socket s, nng_msg **msgp, int flags);
+```
+
+## DESCRIPTION
+
+The `nng_recvmsg()` receives a [message][msg] on [socket][socket] _s_, storing the
+received message at the location pointed to by _msgp_.
+
+This function gives access to the message structure, and thus may
+offer more functionality than the simpler [`nng_recv()`][nng_recv] function.[^1] [^2]
+
+[^1]: It is also more efficient.
+[^2]: An asynchronous form of this function is available as [`nng_recv_aio()`][nng_recv_aio].
+
+The _flags_ may contain the following value:
+
+- {{i:`NNG_FLAG_NONBLOCK`}}: \
+  The function returns immediately, even if no message is available.
+  Without this flag, the function will wait until a message is received
+  by the socket _s_, or any configured timer expires.
+
+After successfully receiving a message, the caller is responsible for
+disposing of it when it is no longer needed.
+
+> [!IMPORTANT]
+> Failing to dispose of the message will leak the memory associated with it.
+
+> [!NOTE]
+> The semantics of what receiving a message means vary from protocol to
+> protocol, so examination of the protocol documentation is encouraged.
+> (For example, with a [_REQ_][req] socket a message may only be received
+> after a request has been sent).
+> Furthermore, some protocols do not support receiving data at all.
+
+## RETURN VALUES
+
+This function returns 0 on success, and non-zero otherwise.
+
+## ERRORS
+
+- `NNG_EAGAIN`: The operation would block, but `NNG_FLAG_NONBLOCK` was specified.
+- `NNG_ECLOSED`: The socket _s_ is not open.
+- `NNG_EINVAL`: An invalid set of _flags_ was specified.
+- `NNG_ENOMEM`: Insufficient memory is available.
+- `NNG_ENOTSUP`: The protocol for socket _s_ does not support receiving.
+- `NNG_ESTATE`: The socket _s_ cannot receive data in this state.
+- `NNG_ETIMEDOUT`: The operation timed out.
+
+## SEE ALSO
+
+[Messages][msg],
+[Sockets][socket],
+[nng_msg_free][nng_msg_free],
+[nng_recv][nng_recv],
+[nng_sendmsg][nng_sendmsg]
+
+{{#include ../refs.md}}
diff --git a/docs/reference/src/sock/nng_send.3.adoc b/docs/reference/src/sock/nng_send.3.adoc
new file mode 100644
index 00000000..4932712a
--- /dev/null
+++ b/docs/reference/src/sock/nng_send.3.adoc
@@ -0,0 +1,90 @@
+# nng_send
+
+## NAME
+
+nng_send --- send data
+
+## SYNOPSIS
+
+```
+#include <nng/nng.h>
+
+int nng_send(nng_socket s, void *data, size_t size, int flags);
+```
+
+## DESCRIPTION
+
+The `nng_send()` function sends a message containing the _data_ of
+length _size_ using the xref:nng_socket.5.adoc[socket] _s_.
+
+NOTE: The semantics of what sending a message means vary from protocol to
+protocol, so examination of the protocol documentation is encouraged.
+(For example, with an xref:nng_pub.7.adoc[_pub_] socket the data is broadcast, so that
+any peers who have a suitable subscription will be able to receive it using
+xref:nng_recv.3.adoc[`nng_recv()`] or a similar function.)
+Furthermore, some protocols may not support sending data (such as
+xref:nng_sub.7.adoc[_sub_]) or may require other conditions.
+(For example, xref:nng_rep.7.adoc[_rep_] sockets cannot normally send data,
+which are responses to requests, until they have first received a request.)
+
+The _flags_ may contain either of (or neither of) the following values:
+
+`NNG_FLAG_NONBLOCK`::
+    The function returns immediately, regardless of whether
+    the socket is able to accept the data or not.  If the socket is unable
+    to accept the data (such as if backpressure exists because the peers
+    are consuming messages too slowly, or no peer is present), then the
+    function will return with `NNG_EAGAIN`.  If this flag is not specified,
+    then the function will block if such a condition exists.
+
+`NNG_FLAG_ALLOC`::
+    The _data_ was allocated using xref:nng_alloc.3.adoc[`nng_alloc()`], or was
+    obtained from a call to xref:nng_recv.3.adoc[`nng_recv()`] with
+    the `NNG_FLAG_ALLOC` flag.
+    If this function returns success, then the _data_ is "owned" by the
+    function, and it will assume responsibility for calling
+    xref:nng_free.3.adoc[`nng_free()`] when it is no longer needed.
+    In the absence of this flag, the _data_ is copied by the implementation
+    before the function returns to the caller.
+
+TIP: The `NNG_FLAG_ALLOC` flag can be used to reduce data copies, thereby
+increasing performance.
+
+NOTE: Regardless of the presence or absence of `NNG_FLAG_NONBLOCK`, there may
+be queues between the sender and the receiver.
+Furthermore, there is no guarantee that the message has actually been delivered.
+Finally, with some protocols, the semantic is implicitly `NNG_FLAG_NONBLOCK`,
+such as with xref:nng_pub.7.adoc[_pub_] sockets, which are best-effort delivery only.
+
+IMPORTANT: When using `NNG_FLAG_ALLOC`, it is important that the value of _size_
+match the actual allocated size of the data.
+Using an incorrect size results
+in unspecified behavior, which may include heap corruption, program crashes,
+or trans-dimensional mutation of the program's author.
+
+## RETURN VALUES
+
+This function returns 0 on success, and non-zero otherwise.
+
+## ERRORS
+
+* `NNG_EAGAIN`: The operation would block, but `NNG_FLAG_NONBLOCK` was specified.
+* `NNG_ECLOSED`: The socket _s_ is not open.
+* `NNG_EINVAL`: An invalid set of _flags_ was specified.
+* `NNG_EMSGSIZE`: The value of _size_ is too large.
+* `NNG_ENOMEM`: Insufficient memory is available.
+* `NNG_ENOTSUP`: The protocol for socket _s_ does not support sending.
+* `NNG_ESTATE`: The socket _s_ cannot send data in this state.
+* `NNG_ETIMEDOUT`: The operation timed out.
+
+## SEE ALSO
+
+[nng_alloc][nng_alloc],
+[nng_free][nng_free],
+[nng_recv][nng_recv],
+[nng_sendmsg][nng_sendmsg],
+[nng_strerror][nng_strerror],
+[nng_socket][nng_socket],
+[nng][nng]
+
+{{#include ../refs.md}}
diff --git a/docs/reference/src/sock/nng_send_aio.3.adoc b/docs/reference/src/sock/nng_send_aio.3.adoc
new file mode 100644
index 00000000..4597619c
--- /dev/null
+++ b/docs/reference/src/sock/nng_send_aio.3.adoc
@@ -0,0 +1,81 @@
+# nng_send_aio
+
+## NAME
+
+nng_send_aio --- send message asynchronously
+
+## SYNOPSIS
+
+```
+#include <nng/nng.h>
+
+void nng_send_aio(nng_socket s, nng_aio *aio);
+```
+
+## DESCRIPTION
+
+The `nng_send_aio()` sends a xref:nng_msg.5.adoc[message] using the
+xref:nng_socket.5.adoc[socket] _s_ asynchronously.
+
+The message to send must have previously been set on the _aio_
+using the xref:nng_aio_set_msg.3.adoc[`nng_aio_set_msg()`] function.
+The function assumes ownership of the message.
+
+If the message was successfully queued for delivery to the socket,
+then the _aio_ will be completed, and xref:nng_aio_result.3.adoc[`nng_aio_result()`]
+will return zero.  In this case the socket will dispose of the
+message when it is finished with it.
+
+NOTE: The operation will be completed, and the callback associated
+with the _aio_ executed, as soon as the socket accepts the message
+for sending.
+This does _not_ indicate that the message was actually delivered, as it
+may still be buffered in the sending socket, buffered in the receiving
+socket, or in flight over physical media.
+
+If the operation fails for any reason (including cancellation or timeout),
+then the _aio_ callback will be executed and
+xref:nng_aio_result.3.adoc[`nng_aio_result()`]
+will return a non-zero error status.
+In this case, the callback has a responsibility to retrieve the message from
+the _aio_ with
+xref:nng_aio_get_msg.3.adoc[`nng_aio_get_msg()`] and dispose of it appropriately.
+(This may include retrying the send operation on the same or a different
+socket, or deallocating the message with xref:nng_msg_free.3.adoc[`nng_msg_free()`].)
+
+NOTE: The semantics of what sending a message means varies from protocol to
+protocol, so examination of the protocol documentation is encouraged.
+(For example, with a xref:nng_pub.7.adoc[_pub_] socket the data is broadcast, so that
+any peers who have a suitable subscription will be able to receive it using
+xref:nng_recv.3.adoc[`nng_recv()`] or a similar function.)
+Furthermore, some protocols may not support sending (such as
+xref:nng_sub.7.adoc[_sub_]) or may require other conditions.
+(For example, xref:nng_rep.7.adoc[_rep_] sockets cannot normally send data, which
+are responses to requests, until they have first received a request.)
+
+## RETURN VALUES
+
+None.  (The operation completes asynchronously.)
+
+## ERRORS
+
+* `NNG_ECANCELED`: The operation was aborted.
+* `NNG_ECLOSED`: The socket _s_ is not open.
+* `NNG_EMSGSIZE`: The message is too large.
+* `NNG_ENOMEM`: Insufficient memory is available.
+* `NNG_ENOTSUP`: The protocol for socket _s_ does not support sending.
+* `NNG_ESTATE`: The socket _s_ cannot send data in this state.
+* `NNG_ETIMEDOUT`: The send timeout expired.
+
+## SEE ALSO
+
+[nng_aio_get_msg][nng_aio_get_msg],
+[nng_aio_set_msg][nng_aio_set_msg],
+[nng_msg_alloc][nng_msg_alloc],
+[nng_strerror][nng_strerror],
+[nng_aio][nng_aio],
+[nng_msg][nng_msg],
+[nng_socket][nng_socket],
+[nng][nng]
+
+{{#include ../refs.md}}
diff --git a/docs/reference/src/sock/nng_sendmsg.3.adoc b/docs/reference/src/sock/nng_sendmsg.3.adoc
new file mode 100644
index 00000000..004ae78d
--- /dev/null
+++ b/docs/reference/src/sock/nng_sendmsg.3.adoc
@@ -0,0 +1,84 @@
+# nng_sendmsg
+
+## NAME
+
+nng_sendmsg --- send message
+
+## SYNOPSIS
+
+```
+#include <nng/nng.h>
+
+int nng_sendmsg(nng_socket s, nng_msg *msg, int flags);
+```
+
+## DESCRIPTION
+
+The `nng_sendmsg()` sends message _msg_ using the socket _s_.
+
+If the function returns zero, indicating it has accepted the message for
+delivery, then the _msg_ is owned by the socket _s_, and the caller
+must not make any further use of it.
+The socket will free the message when it is finished.
+
+If the function returns non-zero, then it is the caller's responsibility
+to dispose of the _msg_, which may include freeing it, sending it to
+another socket, or simply trying again later.
+
+TIP: Using this function gives access to the message structure, and may
+offer more functionality than the simpler xref:nng_send.3.adoc[`nng_send()`] function.
+
+NOTE: The semantics of what sending a message means vary from protocol to
+protocol, so examination of the protocol documentation is encouraged.
+(For example, with a xref:nng_pub.7.adoc[_pub_] socket the data is broadcast, so that
+any peers who have a suitable subscription will be able to receive it using
+xref:nng_recv.3.adoc[`nng_recv()`] or a similar function.)
+Furthermore, some protocols may not support sending (such as
+xref:nng_sub.7.adoc[_sub_]) or may require other conditions.
+(For example, xref:nng_rep.7.adoc[_rep_] sockets cannot normally send data, which
+are responses to requests, until they have first received a request.)
+
+The _flags_ may contain the following value:
+
+`NNG_FLAG_NONBLOCK`::
+    The function returns immediately, regardless of whether
+    the socket is able to accept the data or not.
+    If the socket is unable to accept the data (such as if backpressure exists
+    because the peers are consuming messages too slowly, or no peer is present),
+    then the function will return with `NNG_EAGAIN`.
+    If this flag is not specified, then the function will block if such a
+    condition exists.
+
+
+NOTE: Regardless of the presence or absence of `NNG_FLAG_NONBLOCK`, there may
+be queues between the sender and the receiver.
+Furthermore, there is no guarantee that the message has actually been delivered.
+Finally, with some protocols, the semantic is implicitly `NNG_FLAG_NONBLOCK`,
+such as with xref:nng_pub.7.adoc[_pub_] sockets, which are best-effort delivery only.
+
+## RETURN VALUES
+
+This function returns 0 on success, and non-zero otherwise.
+
+## ERRORS
+
+* `NNG_EAGAIN`: The operation would block, but `NNG_FLAG_NONBLOCK` was specified.
+* `NNG_ECLOSED`: The socket _s_ is not open.
+* `NNG_EINVAL`: An invalid set of _flags_ was specified.
+* `NNG_EMSGSIZE`: The value of _size_ is too large.
+* `NNG_ENOMEM`: Insufficient memory is available.
+* `NNG_ENOTSUP`: The protocol for socket _s_ does not support sending.
+* `NNG_ESTATE`: The socket _s_ cannot send data in this state.
+* `NNG_ETIMEDOUT`: The operation timed out.
+
+## SEE ALSO
+
+[nng_msg_alloc][nng_msg_alloc],
+[nng_recvmsg][nng_recvmsg],
+[nng_send][nng_send],
+[nng_strerror][nng_strerror],
+[nng_msg][nng_msg],
+[nng_socket][nng_socket],
+[nng][nng]
+
+{{#include ../refs.md}}