path: root/man/tip/nng_compat.3compat.html

---
version: tip
layout: manpage_v2
title: nng_compat(3compat)
---
<h1>nng_compat(3compat)</h1>
<div class="sect1">
<h2 id="_name">NAME</h2>
<div class="sectionbody">
<div class="paragraph">
<p>nng_compat - compatibility with nanomsg 1.0</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;nanomsg/nn.h&gt;</span>

<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf">&lt;nanomsg/bus.h&gt;</span>
<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf">&lt;nanomsg/pair.h&gt;</span>
<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf">&lt;nanomsg/pipeline.h&gt;</span>
<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf">&lt;nanomsg/pubsub.h&gt;</span>
<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf">&lt;nanomsg/reqrep.h&gt;</span>
<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf">&lt;nanomsg/survey.h&gt;</span>

<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf">&lt;nanomsg/inproc.h&gt;</span>
<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf">&lt;nanomsg/ipc.h&gt;</span>
<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf">&lt;nanomsg/tcp.h&gt;</span>
<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf">&lt;nanomsg/ws.h&gt;</span></code></pre>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_description">DESCRIPTION</h2>
<div class="sectionbody">
<div class="paragraph">
<p>
<a href="nng.7.html"><em>NNG</em></a> provides source-level compatibility for
most <em>libnanomsg</em> 1.0 applications.</p>
</div>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<i class="fa icon-important" title="Important"></i>
</td>
<td class="content">
This is intended to facilitate converting legacy applications to
use <em>NNG</em>.
New applications should use the newer <a href="nng.7.html"><em>NNG</em></a> API instead.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>Applications making use of this must take care
to link with <a href="libnng.3.html"><em>libnng</em></a> instead of <em>libnn</em>.</p>
</div>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<i class="fa icon-tip" title="Tip"></i>
</td>
<td class="content">
While not recommended for long term use, the value returned by
<a href="nng_socket_id.3.html"><code>nng_socket_id()</code></a> can be used with these functions
just like a value returned by <a href="nn_socket.3compat.html"><code>nn_socket()</code></a>.
This can be way to facilitate incremental transition to the new API.
</td>
</tr>
</table>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
Some capabilities, protocols, and transports, will not be accessible
using this API, as the compatible API has no provision for expression
of certain concepts introduced in the new API.
</td>
</tr>
</table>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
While reasonable efforts have been made to provide for compatibility,
some things may behave differently, and some less common parts of the
<em>libnanomsg</em> 1.0 API are not supported at this time, including certain
options and the statistics API.
See the <a href="#_caveats">Caveats</a> section below.
</td>
</tr>
</table>
</div>
<div class="sect2">
<h3 id="_compiling">Compiling</h3>
<div class="paragraph">
<p>When compiling legacy <em>nanomsg</em> applications, it will generally be
necessary to change the include search path to add the <code>compat</code> subdirectory
of the directory where headers were installed.
For example, if <em>NNG</em> is installed in <code>$prefix</code>, then header files will
normally be located in <code>$prefix/include/nng</code>.
In this case, to build legacy <em>nanomsg</em> apps against <em>NNG</em> you would
add <code>$prefix/include/nng/compat</code> to your compiler&#8217;s search path.</p>
</div>
<div class="paragraph">
<p>Alternatively, you can change your source code so that <code>#include</code> statements
referring to <code>&lt;nanomsg&gt;</code> instead refer to <code>&lt;nng/compat/nanomsg&gt;</code>.
For example, instead of:</p>
</div>
<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;nanomsg/nn.h&gt;</span>
<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf">&lt;nanomsg/reqrep.h&gt;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>you would have this:</p>
</div>
<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/compat/nanomsg/nn.h&gt;</span>
<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf">&lt;nng/compat/nanomsg/reqrep.h&gt;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>Legacy applications built using these methods should be linked against <em>libnng</em>
instead of <em>libnn</em>, just like any other <em>NNG</em> application.</p>
</div>
</div>
<div class="sect2">
<h3 id="_functions">Functions</h3>
<div class="paragraph">
<p>The following functions are provided:</p>
</div>
<div class="hdlist">
<table>
<tr>
<td class="hdlist1">
<a href="nn_socket.3compat.html"><code>nn_socket()</code></a>
</td>
<td class="hdlist2">
<p>create socket</p>
</td>
</tr>
<tr>
<td class="hdlist1">
<a href="nn_getsockopt.3compat.html"><code>nn_getsockopt()</code></a>
</td>
<td class="hdlist2">
<p>get socket option</p>
</td>
</tr>
<tr>
<td class="hdlist1">
<a href="nn_setsockopt.3compat.html"><code>nn_setsockopt()</code></a>
</td>
<td class="hdlist2">
<p>set socket option</p>
</td>
</tr>
<tr>
<td class="hdlist1">
<a href="nn_bind.3compat.html"><code>nn_bind()</code></a>
</td>
<td class="hdlist2">
<p>accept connections from remote peers</p>
</td>
</tr>
<tr>
<td class="hdlist1">
<a href="nn_connect.3compat.html"><code>nn_connect()</code></a>
</td>
<td class="hdlist2">
<p>connect to remote peer</p>
</td>
</tr>
<tr>
<td class="hdlist1">
<a href="nn_send.3compat.html"><code>nn_send()</code></a>
</td>
<td class="hdlist2">
<p>send data</p>
</td>
</tr>
<tr>
<td class="hdlist1">
<a href="nn_recv.3compat.html"><code>nn_recv()</code></a>
</td>
<td class="hdlist2">
<p>receive data</p>
</td>
</tr>
<tr>
<td class="hdlist1">
<a href="nn_shutdown.3compat.html"><code>nn_shutdown()</code></a>
</td>
<td class="hdlist2">
<p>shut down endpoint</p>
</td>
</tr>
<tr>
<td class="hdlist1">
<a href="nn_close.3compat.html"><code>nn_close()</code></a>
</td>
<td class="hdlist2">
<p>close socket</p>
</td>
</tr>
<tr>
<td class="hdlist1">
<a href="nn_poll.3compat.html"><code>nn_poll()</code></a>
</td>
<td class="hdlist2">
<p>poll sockets</p>
</td>
</tr>
<tr>
<td class="hdlist1">
<a href="nn_device.3compat.html"><code>nn_device()</code></a>
</td>
<td class="hdlist2">
<p>create forwarding device</p>
</td>
</tr>
<tr>
<td class="hdlist1">
<a href="nn_recvmsg.3compat.html"><code>nn_recvmsg()</code></a>
</td>
<td class="hdlist2">
<p>receive message</p>
</td>
</tr>
<tr>
<td class="hdlist1">
<a href="nn_sendmsg.3compat.html"><code>nn_sendmsg()</code></a>
</td>
<td class="hdlist2">
<p>send message</p>
</td>
</tr>
<tr>
<td class="hdlist1">
<a href="nn_cmsg.3compat.html"><code>nn_cmsg()</code></a>
</td>
<td class="hdlist2">
<p>message control data</p>
</td>
</tr>
<tr>
<td class="hdlist1">
<a href="nn_get_statistic.3compat.html"><code>nn_get_statistic()</code></a>
</td>
<td class="hdlist2">
<p>get statistic (stub)</p>
</td>
</tr>
<tr>
<td class="hdlist1">
<a href="nn_allocmsg.3compat.html"><code>nn_allocmsg()</code></a>
</td>
<td class="hdlist2">
<p>allocate message</p>
</td>
</tr>
<tr>
<td class="hdlist1">
<a href="nn_reallocmsg.3compat.html"><code>nn_reallocmsg()</code></a>
</td>
<td class="hdlist2">
<p>reallocate message</p>
</td>
</tr>
<tr>
<td class="hdlist1">
<a href="nn_freemsg.3compat.html"><code>nn_freemsg()</code></a>
</td>
<td class="hdlist2">
<p>free message</p>
</td>
</tr>
<tr>
<td class="hdlist1">
<a href="nn_errno.3compat.html"><code>nn_errno()</code></a>
</td>
<td class="hdlist2">
<p>return most recent error</p>
</td>
</tr>
<tr>
<td class="hdlist1">
<a href="nn_strerror.3compat.html"><code>nn_strerror()</code></a>
</td>
<td class="hdlist2">
<p>return message for error</p>
</td>
</tr>
<tr>
<td class="hdlist1">
<a href="nn_term.3compat.html"><code>nn_term()</code></a>
</td>
<td class="hdlist2">
<p>terminate library</p>
</td>
</tr>
</table>
</div>
</div>
<div class="sect2">
<h3 id="_caveats">Caveats</h3>
<div class="paragraph">
<p>The following caveats apply when using the legacy API with <em>NNG</em>.</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Socket numbers can be quite large.
The legacy <em>libnanomsg</em> attempted to reuse socket numbers, like
file descriptors in UNIX systems.
<em>NNG</em> avoids this to prevent accidental reuse or
collision after a descriptor is closed.
Consequently, socket numbers can become quite large, and should
probably not be used for array indices.</p>
</li>
<li>
<p>The following options (<code>nn_getsockopt</code>) are unsupported:
<code>NN_SNDPRIO</code>, <code>NN_RCVPRIO</code>, <code>NN_IPV4ONLY</code>.
The priority options may be supported in the future, when
the underlying capability is present in <em>NNG</em>.</p>
</li>
<li>
<p>Access to statistics using this legacy API
(<a href="nn_get_statistic.3compat.html"><code>nn_get_statistic()</code></a>) is unsupported.</p>
</li>
<li>
<p>Some transports can support longer URLs than legacy <em>libnanomsg</em> can.
It is a good idea to use short pathnames in URLs if interoperability
is a concern.</p>
</li>
<li>
<p>Only absolute paths are supported in <code>ipc://</code> URLs.
For example, <code>ipc:///tmp/mysocket</code> is acceptable, but <code>ipc://mysocket</code> is not.</p>
</li>
<li>
<p>The WebSocket transport in this implementation (<code>ws://</code> URLs)
only supports BINARY frames.</p>
</li>
<li>
<p>Some newer transports are unusable from this mode.
In particular, this legacy API offers no way to configure
TLS or ZeroTier parameters that may be required for use.</p>
</li>
<li>
<p>ABI versioning of the compatibility layer is not supported,
and the <code>NN_VERSION_</code> macros are not present.</p>
</li>
<li>
<p>Runtime symbol information is not implemented.
Specifically, there is no <code>nn_symbol()</code> function yet.
(This may be addressed later if there is a need.)</p>
</li>
<li>
<p>The TCP transport (<code>tcp://</code> URLs) does not support specifying the local
address or interface when binding.  (This could be fixed in the future,
but most likely this will be available only using the new API.)</p>
</li>
<li>
<p>The values of <code>NN_RCVMAXSIZE</code> are constrained.
Specifically, values set larger than 2GB using the new API will be reported
as unlimited (<code>-1</code>) in the new API, and the value <code>0</code> will disable any
enforcement, just like <code>-1</code>.
(There is no practical reason to ever want to limit the receive size to
zero.)</p>
</li>
<li>
<p>This implementation counts buffers in terms of messages rather than bytes.
As a result, the buffer sizes accessed with <code>NN_SNDBUF</code> and <code>NN_RCVBUF</code> are
rounded up to a whole number of kilobytes, then divided by 1024, in order
to approximate buffering assuming 1 KB messages.
Few applications should need to adjust the default values.</p>
</li>
</ul>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_see_also">SEE ALSO</h2>
<div class="sectionbody">
<div class="paragraph text-left">
<p><a href="libnng.3.html">libnng(3)</a>,
<a href="nng.7.html">nng(7)</a></p>
</div>
</div>
</div>