From 6bb7936eee3cff1555dde56aaf62d5baeefda7a4 Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Fri, 2 Mar 2018 17:33:49 -0800 Subject: Add nng_sendmsg and nng_recvmsg manual pages. --- docs/man/libnng.adoc | 2 +- docs/man/nng_recvmsg.adoc | 67 ++++++++++++++++++++++++++++++++++++ docs/man/nng_sendmsg.adoc | 88 +++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 156 insertions(+), 1 deletion(-) create mode 100644 docs/man/nng_recvmsg.adoc create mode 100644 docs/man/nng_sendmsg.adoc diff --git a/docs/man/libnng.adoc b/docs/man/libnng.adoc index 72516705..0c5ee75f 100644 --- a/docs/man/libnng.adoc +++ b/docs/man/libnng.adoc @@ -90,7 +90,7 @@ Most applications will only interact with the body. |<>|return the message body length |<>|reallocate a message |<>|remove data from start of message body -|<>|receive a message +|<>|receive a message |<>|send a message |=== diff --git a/docs/man/nng_recvmsg.adoc b/docs/man/nng_recvmsg.adoc new file mode 100644 index 00000000..03cc99b2 --- /dev/null +++ b/docs/man/nng_recvmsg.adoc @@ -0,0 +1,67 @@ += nng_recvmsg(3) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_recvmsg - recv message + +== SYNOPSIS + +[source, c] +----------- +#include + +int nng_recvmsg(nng_socket s, nng_msg **msgp, int flags); +----------- + +== DESCRIPTION + +The `nng_recvmsg()` receives a message on socket _s_, storing the +received message at the location pointed to by _msgp_. + +TIP: Using this function gives access to the message structure, and thus may +offer more functionality than the simpler <> function. + +The _flags_ may contain the following value: + +`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. + +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 <> socket a message may only be received +after a request has been sent, and an <> 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 +<>. + +== 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_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 + +<>, +<>, +<>, +<>, +<> diff --git a/docs/man/nng_sendmsg.adoc b/docs/man/nng_sendmsg.adoc new file mode 100644 index 00000000..708c1f3b --- /dev/null +++ b/docs/man/nng_sendmsg.adoc @@ -0,0 +1,88 @@ += nng_sendmsg(3) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_sendmsg - send message + +== SYNOPSIS + +[source, c] +----------- +#include + +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 <> 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 an <> socket the data is broadcast, so that +any peers who have a suitable subscription will be able to receive it using +<> or a similar function.) Furthermore, some protocols +may not support sending (such as <>) or may +require other conditions. (For example, <> 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 implictly `NNG_FLAG_NONBLOCK`, such as with +<> sockets, which are best-effort delivery only. + +== 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 + +<>, +<>, +<>, +<>, +<> -- cgit v1.2.3-70-g09d2