From 98f23e10cc1d65da6a7f6c7e4f5665d7afc27a86 Mon Sep 17 00:00:00 2001
From: Garrett D'Amore <garrett@damore.org>
Date: Thu, 15 Mar 2018 08:40:17 -0700
Subject: fixes #286 nng_pair0_open (and all others) need man page fixes #279
 consider restructuring man sections

This represents a rather significant rework, and major editing
effort, for the entire set of manual pages.

All of the pages now have a section number in their filename;
this assists in some other tooling, particularly ebook generation
as every link needs to be programmatically modified when combined
into an ebook.

Section 5 is introduced, and populated with pages for the main
types, and all options are now documented.

Numerous errors have been corrected, including rewriting certain
portions such as the header section of the surveyor protocol.

Much work has been done to facilitate index generation, although
certainly more work remains here.

Every internal link within these pages now resolves; there are no
more dead links.  (This is required to generate Kindle format books.)
---
 docs/man/nng_send_aio.3.adoc | 88 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 88 insertions(+)
 create mode 100644 docs/man/nng_send_aio.3.adoc

(limited to 'docs/man/nng_send_aio.3.adoc')

diff --git a/docs/man/nng_send_aio.3.adoc b/docs/man/nng_send_aio.3.adoc
new file mode 100644
index 00000000..bb110015
--- /dev/null
+++ b/docs/man/nng_send_aio.3.adoc
@@ -0,0 +1,88 @@
+= nng_send_aio(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_aio - send message asynchronously
+
+== SYNOPSIS
+
+[source, c]
+----
+#include <nng/nng.h>
+
+void nng_send_aio(nng_socket s, nng_aio *aio);
+----
+
+== DESCRIPTION
+
+The `nng_send_aio()` sends a <<nng_msg.5#,message>> using the
+<<nng_socket.5#,socket>> _s_ asynchronously.
+
+The message to send must have previously been set on the _aio_
+using the <<nng_aio_set_msg.3#,`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 <<nng_aio_result.3#,`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 <<nng_aio_result.3#,`nng_aio_result()`>>
+will return a non-zero error status.
+In this case, the callback has a responsibity to retrieve the message from
+the _aio_ with <<nng_aio_get_msg.3#,`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 <<nng_msg_free.3#,`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 <<nng_pub.7#,_pub_>> socket the data is broadcast, so that
+any peers who have a suitable subscription will be able to receive it using
+<<nng_recv.3#,`nng_recv()`>> or a similar function.)
+Furthermore, some protocols may not support sending (such as
+<<nng_sub.7#,_sub_>>) or may require other conditions.
+(For example, <<nng_rep.7#,_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.3#,nng_aio_get_msg(3)>>,
+<<nng_aio_set_msg.3#,nng_aio_set_msg(3)>>,
+<<nng_msg_alloc.3#,nng_msg_alloc(3)>>,
+<<nng_strerror.3#,nng_strerror(3)>>,
+<<nng_aio.5#,nng_aio(5)>>,
+<<nng_msg.5#,nng_msg(5)>>,
+<<nng_socket.5#,nng_socket(5)>>,
+<<nng.7#,nng(7)>>
-- 
cgit v1.2.3-70-g09d2

