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

---
version: tip
layout: manpage_v2
title: nng_dial(3)
---
<h1>nng_dial(3)</h1>
<div class="sect1">
<h2 id="_name">NAME</h2>
<div class="sectionbody">
<div class="paragraph">
<p>nng_dial - create and start dialer</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">int</span><span class="tok-w"> </span><span class="tok-nf">nng_dial</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-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">url</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_dialer</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">dp</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-n">flags</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_dial()</code> function creates a newly initialized
<a href="nng_dialer.5.html"><code>nng_dialer</code></a> object,
associated with socket <em>s</em>, and configured to dial the
address specified by <em>url</em>, and starts it.
If the value of <em>dp</em> is not <code>NULL</code>, then
the newly created dialer is stored at the address indicated by <em>dp</em>.</p>
</div>
<div class="paragraph">
<p>Dialers initiate a remote connection to a listener.
Upon a successful
connection being established, they create a <a href="nng_pipe.5.html">pipe</a>,
add it to the socket, and then wait for that pipe to be closed.
When the pipe is closed, the dialer attempts to re-establish the connection.
Dialers will also periodically retry a connection automatically if an attempt
to connect asynchronously fails.</p>
</div>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<i class="fa icon-tip" title="Tip"></i>
</td>
<td class="content">
While it is convenient to think of dialers as clients, the relationship
between the listener or dialer is orthogonal to any server or client status
that might be associated with a given protocol.
For example, a <a href="nng_req.7.html"><em>req</em></a>
socket might have associated dialers, but might also have associated listeners.
It may even have some of each at the same time!
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>Normally, the first attempt to connect to the address indicated by <em>url</em> is done
synchronously, including any necessary name resolution.
As a result, a failure, such as if the connection is refused, will be returned
immediately, and no further action will be taken.</p>
</div>
<div class="paragraph">
<p>However, if the special value <code>NNG_FLAG_NONBLOCK</code> is
supplied in <em>flags</em>, then the connection attempt is made asynchronously.</p>
</div>
<div class="paragraph">
<p>Furthermore, if the connection was closed for a synchronously dialed
connection, the dialer will still attempt to redial asynchronously.</p>
</div>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<i class="fa icon-tip" title="Tip"></i>
</td>
<td class="content">
While <code>NNG_FLAG_NONBLOCK</code> can help an application be more resilient,
it also generally makes diagnosing failures somewhat more difficult.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>Because the dialer is started immediately, it is generally not possible
to apply extra configuration; if that is needed applications should consider
using <a href="nng_dialer_create.3.html"><code>nng_dialer_create()</code></a> and
<a href="nng_dialer_start.3.html"><code>nng_dialer_start()</code></a> instead.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_return_values">RETURN VALUES</h2>
<div class="sectionbody">
<div class="paragraph">
<p>This function returns 0 on success, and non-zero otherwise.</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_EADDRINVAL</code>
</td>
<td class="hdlist2">
<p>An invalid <em>url</em> was specified.</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_ECONNREFUSED</code>
</td>
<td class="hdlist2">
<p>The remote peer refused the connection.</p>
</td>
</tr>
<tr>
<td class="hdlist1">
<code>NNG_ECONNRESET</code>
</td>
<td class="hdlist2">
<p>The remote peer reset the connection.</p>
</td>
</tr>
<tr>
<td class="hdlist1">
<code>NNG_EINVAL</code>
</td>
<td class="hdlist2">
<p>An invalid set of <em>flags</em> or an invalid <em>url</em> was specified.</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_EPEERAUTH</code>
</td>
<td class="hdlist2">
<p>Authentication or authorization failure.</p>
</td>
</tr>
<tr>
<td class="hdlist1">
<code>NNG_EPROTO</code>
</td>
<td class="hdlist2">
<p>A protocol error occurred.</p>
</td>
</tr>
<tr>
<td class="hdlist1">
<code>NNG_EUNREACHABLE</code>
</td>
<td class="hdlist2">
<p>The remote address is not reachable.</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_dialer_close.3.html">nng_dialer_close(3)</a>,
<a href="nng_dialer_create.3.html">nng_dialer_create(3)</a>
<a href="nng_dialer_start.3.html">nng_dialer_start(3)</a>,
<a href="nng_listen.3.html">nng_listen(3)</a>,
<a href="nng_strerror.3.html">nng_strerror(3)</a>,
<a href="nng_dialer.5.html">nng_dialer(5)</a>,
<a href="nng_pipe.5.html">nng_pipe(5)</a>,
<a href="nng.7.html">nng(7)</a></p>
</div>
</div>
</div>