aboutsummaryrefslogtreecommitdiff
path: root/docs/nng_send.adoc
diff options
context:
space:
mode:
Diffstat (limited to 'docs/nng_send.adoc')
-rw-r--r--docs/nng_send.adoc94
1 files changed, 0 insertions, 94 deletions
diff --git a/docs/nng_send.adoc b/docs/nng_send.adoc
deleted file mode 100644
index a6c98790..00000000
--- a/docs/nng_send.adoc
+++ /dev/null
@@ -1,94 +0,0 @@
-= nng_send(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_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)>>