path: root/man/tip/nng_send_aio.3.html

---
version: tip
layout: manpage_v2
title: nng_send_aio(3)
---
<h1>nng_send_aio(3)</h1>
<div class="sect1">
<h2 id="_name">NAME</h2>
<div class="sectionbody">
<div class="paragraph">
<p>nng_send_aio - send message asynchronously</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_synopsis">SYNOPSIS</h2>
<div class="sectionbody">
<div class="listingblock">
<div class="content">
<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf">&lt;nng/nng.h&gt;</span>

<span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-nf">nng_send_aio</span><span class="tok-p">(</span><span class="tok-n">nng_socket</span><span class="tok-w"> </span><span class="tok-n">s</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_aio</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">aio</span><span class="tok-p">);</span></code></pre>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_description">DESCRIPTION</h2>
<div class="sectionbody">
<div class="paragraph">
<p>The <code>nng_send_aio()</code> sends a <a href="nng_msg.5.html">message</a> using the
<a href="nng_socket.5.html">socket</a> <em>s</em> asynchronously.</p>
</div>
<div class="paragraph">
<p>The message to send must have previously been set on the <em>aio</em>
using the <a href="nng_aio_set_msg.3.html"><code>nng_aio_set_msg()</code></a> function.
The function assumes ownership of the message.</p>
</div>
<div class="paragraph">
<p>If the message was successfully queued for delivery to the socket,
then the <em>aio</em> will be completed, and <a href="nng_aio_result.3.html"><code>nng_aio_result()</code></a>
will return zero.  In this case the socket will dispose of the
message when it is finished with it.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
The operation will be completed, and the callback associated
with the <em>aio</em> executed, as soon as the socket accepts the message
for sending.
This does <em>not</em> 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.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>If the operation fails for any reason (including cancellation or timeout),
then the <em>aio</em> callback will be executed and
<a href="nng_aio_result.3.html"><code>nng_aio_result()</code></a>
will return a non-zero error status.
In this case, the callback has a responsibility to retrieve the message from
the <em>aio</em> with
<a href="nng_aio_get_msg.3.html"><code>nng_aio_get_msg()</code></a> and dispose of it appropriately.
(This may include retrying the send operation on the same or a different
socket, or deallocating the message with <a href="nng_msg_free.3.html"><code>nng_msg_free()</code></a>.)</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
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 <a href="nng_pub.7.html"><em>pub</em></a> socket the data is broadcast, so that
any peers who have a suitable subscription will be able to receive it using
<a href="nng_recv.3.html"><code>nng_recv()</code></a> or a similar function.)
Furthermore, some protocols may not support sending (such as
<a href="nng_sub.7.html"><em>sub</em></a>) or may require other conditions.
(For example, <a href="nng_rep.7.html"><em>rep</em></a> sockets cannot normally send data, which
are responses to requests, until they have first received a request.)
</td>
</tr>
</table>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_return_values">RETURN VALUES</h2>
<div class="sectionbody">
<div class="paragraph">
<p>None.  (The operation completes asynchronously.)</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_errors">ERRORS</h2>
<div class="sectionbody">
<div class="hdlist">
<table>
<tr>
<td class="hdlist1">
<code>NNG_ECANCELED</code>
</td>
<td class="hdlist2">
<p>The operation was aborted.</p>
</td>
</tr>
<tr>
<td class="hdlist1">
<code>NNG_ECLOSED</code>
</td>
<td class="hdlist2">
<p>The socket <em>s</em> is not open.</p>
</td>
</tr>
<tr>
<td class="hdlist1">
<code>NNG_EMSGSIZE</code>
</td>
<td class="hdlist2">
<p>The message is too large.</p>
</td>
</tr>
<tr>
<td class="hdlist1">
<code>NNG_ENOMEM</code>
</td>
<td class="hdlist2">
<p>Insufficient memory is available.</p>
</td>
</tr>
<tr>
<td class="hdlist1">
<code>NNG_ENOTSUP</code>
</td>
<td class="hdlist2">
<p>The protocol for socket <em>s</em> does not support sending.</p>
</td>
</tr>
<tr>
<td class="hdlist1">
<code>NNG_ESTATE</code>
</td>
<td class="hdlist2">
<p>The socket <em>s</em> cannot send data in this state.</p>
</td>
</tr>
<tr>
<td class="hdlist1">
<code>NNG_ETIMEDOUT</code>
</td>
<td class="hdlist2">
<p>The send timeout expired.</p>
</td>
</tr>
</table>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_see_also">SEE ALSO</h2>
<div class="sectionbody">
<div class="paragraph text-left">
<p><a href="nng_aio_get_msg.3.html">nng_aio_get_msg(3)</a>,
<a href="nng_aio_set_msg.3.html">nng_aio_set_msg(3)</a>,
<a href="nng_msg_alloc.3.html">nng_msg_alloc(3)</a>,
<a href="nng_strerror.3.html">nng_strerror(3)</a>,
<a href="nng_aio.5.html">nng_aio(5)</a>,
<a href="nng_msg.5.html">nng_msg(5)</a>,
<a href="nng_socket.5.html">nng_socket(5)</a>,
<a href="nng.7.html">nng(7)</a></p>
</div>
</div>
</div>