diff options
| -rw-r--r-- | docs/nng_recv.adoc | 83 | ||||
| -rw-r--r-- | docs/nng_send.adoc | 98 |
2 files changed, 181 insertions, 0 deletions
diff --git a/docs/nng_recv.adoc b/docs/nng_recv.adoc new file mode 100644 index 00000000..d87d5bd9 --- /dev/null +++ b/docs/nng_recv.adoc @@ -0,0 +1,83 @@ += nng_recv(3) +:doctype: manpage +:manmanual: nng +:mansource: nng +:manvolnum: 3 +:copyright: Copyright 2018 mailto:info@staysail.tech[Staysail Systems, Inc.] + \ + Copyright 2018 mailto:info@capitar.com[Capitar IT Group BV] + \ + {blank} + \ + This document is supplied under the terms of the \ + https://opensource.org/licenses/MIT[MIT License]. + +== NAME + +nng_recv - recv data + +== SYNOPSIS + +[source, 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. + +If the special flag `NNG_FLAG_ALLOC` 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_. + +If the special flag `NNG_FLAG_ALLOC` is present, then a "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(3)>>), fill it with +the message body, and store it at the address referenced by _data_, and update +the size referenced by _sizep_. When this flag is present, the caller assumes +responsibility for disposing of the received buffer either by the function +<<nng_free#,nng_free(3)>> or reusing the message for sending (with the same +size) via <<nng_send#nng_send(3)>>. + +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 an <<nng_req#,nng_req(3)>> socket a message may only be received +after a request has been sent, and an <<nng_sub#,nng_sub(3)>> 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 +<<nng_pub#,nng_pub(3)>>. + +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. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +`NNG_EAGAIN`:: The socket _s_ cannot accept data for sending. +`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. + +== SEE ALSO + +<<nng_alloc#,nng_alloc(3)>>, +<<nng_free#,nng_free(3)>>, +<<nng_recvmsg#,nng_recvmsg(3)>>, +<<nng_send#,nng_send(3)>>, +<<nng_strerror#,nng_strerror(3)>>, +<<nng#,nng(7)>> + +== COPYRIGHT + +{copyright} diff --git a/docs/nng_send.adoc b/docs/nng_send.adoc new file mode 100644 index 00000000..79b77705 --- /dev/null +++ b/docs/nng_send.adoc @@ -0,0 +1,98 @@ += nng_send(3) +:doctype: manpage +:manmanual: nng +:mansource: nng +:manvolnum: 3 +:copyright: Copyright 2018 mailto:info@staysail.tech[Staysail Systems, Inc.] + \ + Copyright 2018 mailto:info@capitar.com[Capitar IT Group BV] + \ + {blank} + \ + This document is supplied under the terms of the \ + https://opensource.org/licenses/MIT[MIT License]. + +== NAME + +nng_send - send data + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> + +int nng_send(nng_socket s, void *data, size_t size, int flags); +----------- + +== DESCRIPTION + +The `nng_send()` sends a message containing the _data_ of length _size_ +using the 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 <<nng_pub#,nng_pub(3)>> socket the data is broadcast, so that +any peers who have a suitable subscription will be able to receive it using +<<nng_recv#,nng_recv(3)>> or a similar function.) Furthermore, some protocols +may not support sending data (such as <<nng_sub#,nng_sub(3)>>) or may +require other conditions. (For example, <<nng_rep#,nng_rep(3)>> 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 <<nng_alloc#,nng_alloc(3)>>, or was obtained + from a call to <<nng_recv#,nng_recv(3)>> 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 + <<nng_free#,nng_free(3)>> 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 implictly `NNG_FLAG_NONBLOCK`, such as with +<<nng_pub#,nng_pub(3)>> sockets, which are best-effort delivery only. + +WARNING: 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 transdimensional mutation of the program's author. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +`NNG_EAGAIN`:: The socket _s_ cannot accept data for sending. +`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. + +== SEE ALSO + +<<nng_alloc#,nng_alloc(3)>>, +<<nng_free#,nng_free(3)>>, +<<nng_recv,nng_recv(3)>>, +<<nng_sendmsg#,nng_sendmsg(3)>>, +<<nng_strerror#,nng_strerror(3)>>, +<<nng#,nng(7)>> + +== COPYRIGHT + +{copyright} |