= nng_compat(3compat)
//
// 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_compat - compatibility with nanomsg 1.0

== SYNOPSIS

[source, c]
----
#include <nn/nn.h>
----

== DESCRIPTION

The <<nng.7#,_nng_>> library provides source-level compatibility for
most _nanomsg_ 1.0 applications.

IMPORTANT: This is intended to faciliate converting legacy applications to
use the _nng_ library.
New applications shoud not use the newer <<nng.7#,_nng_>> API instead.

Applications making use of this ((compatibility layer)) take care
to link with <<libnng.3#,_libnng_>> instead of _libnn_.

NOTE: 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 newer <<nng.7#,_nng_>> API.

NOTE: While reasonable efforts have been made to provide for compatibility,
some things may behave differently, and some less common parts of the
_nanomsg_ 1.0 API are not supported at this time, including certain
options and the statistics API.

TIP: If an installation of the older _nanomsg_ library is present on
the build system, it may be necessary to provide a different search
path for header files to ensure that the compatibility definitions are
used in compilation.

=== Functions

The following functions are provided:

// Add links for the following as they are written.
|===
|`nn_socket()`|create a socket
|`nn_getsockopt()`|get socket option
|`nn_setsockopt()`|set socket option
|`nn_bind()`|accept connections from remote peers
|`nn_connect()`|connect to remote peer
|`nn_send()`|send data
|`nn_recv()`|receive data
|`nn_shutdown()`|shut down endpoint
|`nn_close()`|close socket
|`nn_poll()`|poll sockets
|`nn_device()`|create forwarding device
|`nn_recvmsg()`|receive message
|`nn_sendmsg()`|send message
|`nn_get_statistic()`|get statistic (stub)
|`nn_allocmsg()`|allocate message
|`nn_reallocmsg()`|reallocate message
|`nn_freemsg()`|free message
|`nn_errno()`|return most recent error
|`nn_strerror()`|return message for error
|`nn_term()`|terminate library
|===

NOTE: Documentation for the compatibility functions will be
supplied here later.
In the meantime it can be found online at the
http://nanomsg.org[nanomsg site].

There are a few caveats, that should be kept in mind.

NOTE: Socket numbers can be quite large.
The legacy _libnanomsg_ attempted to reuse socket numbers, like
file descriptors in UNIX systems.
The _nng_ library 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.

NOTE: The following options (`nn_getsockopt`) are unsupported:
`NN_PROTOCOL`, `NN_SNDPRIO`, `NN_RCVPRIO`, `NN_IPV4ONLY`.
Some of these will probably be added back in the future when
the relevant support is added to _nng_.

NOTE: Statistics (`nn_get_statistic`) are unsupported.
The plan is to support statistics in the native _nng_ API, but
we think there is no need for this in a compatibility layer.
Hence, this function returns `ENOTSUP`.

NOTE: Some transports can support longer URLs than legacy _libnanomsg_ can.
It is a good idea to use short pathnames in URLs if interoperability
is a concern.

NOTE: Some transports are unusable from this mode.
In particular, this legacy API offers no way to configure
TLS parameters that are required for use.

NOTE: ABI versioning is not supported.
We don't offer the `NN_VERSION_` macros.  Sorry.

NOTE: Runtime symbol information is not implemented.
Specifically, there is no `nn_symbol()` function yet.
(This may be addressed later if there is a need.)

IMPORTANT: The `nn_term()` function is destructive and should be avoided.
This function closes down all sockets, and really there is no good
reason to ever use it.
Removal from existing code is advised.
(Keep track of sockets and close them explicitly if necessary.)

IMPORTANT: It *is* possible at present to intermix sockets between the new and
the old APIs, but this is not a guaranteed feature, and should only
be used temporarily to facilitate transitioning code to the new APIs.

// === Common Functions
//
// The following common functions exist in _libnng_.
//
// |===
// |<<nng_alloc.3#,nng_alloc()>>|allocate memory
// |<<nng_free.3#,nng_free()>>|free memory
// |<<nng_strerror.3#,nng_strerror()>>|return an error description
// |<<nng_version.3#,nng_version()>>|report library version
// |===
//

== SEE ALSO

<<nng.7#,nng(7)>>