= 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 should use the newer <<nng.7#,_nng_>> API instead.

Applications making use of this ((compatibility layer)) must 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:

// For PDF, we don't have horizontal lists, so we have to conditionalize
// this and use tables there -- it looks ugly otherwise.
ifndef::backend-pdf[]
[horizontal]
`<<nn_socket.3compat#,nn_socket()>>`:: create socket
`<<nn_getsockopt.3compat#,nn_getsockopt()>>`:: get socket option
`<<nn_setsockopt.3compat#,nn_setsockopt()>>`:: set socket option
`<<nn_bind.3compat#,nn_bind()>>`:: accept connections from remote peers
`<<nn_connect.3compat#,nn_connect()>>`:: connect to remote peer
`<<nn_send.3compat#,nn_send()>>`:: send data
`<<nn_recv.3compat#,nn_recv()>>`:: receive data
`<<nn_shutdown.3compat#,nn_shutdown()>>`:: shut down endpoint
`<<nn_close.3compat#,nn_close()>>`:: close socket
`<<nn_poll.3compat#,nn_poll()>>`:: poll sockets
`<<nn_device.3compat#,nn_device()>>`:: create forwarding device
`<<nn_recvmsg.3compat#,nn_recvmsg()>>`:: receive message
`<<nn_sendmsg.3compat#,nn_sendmsg()>>`:: send message
`<<nn_cmsg.3compat#,nn_cmsg()>>`:: message control data
`<<nn_get_statistic.3compat#,nn_get_statistic()>>`:: get statistic (stub)
`<<nn_allocmsg.3compat#,nn_allocmsg()>>`:: allocate message
`<<nn_reallocmsg.3compat#,nn_reallocmsg()>>`:: reallocate message
`<<nn_freemsg.3compat#,nn_freemsg()>>`:: free message
`<<nn_errno.3compat#,nn_errno()>>`:: return most recent error
`<<nn_strerror.3compat#,nn_strerror()>>`:: return message for error
`<<nn_term.3compat#,nn_term()>>`:: terminate library
endif::[]
ifdef::backend-pdf[]
// Add links for the following as they are written.
[.hdlist,width=90%, grid=rows,cols="1,2", align="center"]
|===
|`<<nn_socket.3compat#,nn_socket()`>>|create socket
|`<<nn_getsockopt.3compat#,nn_getsockopt()>>`|get socket option
|`<<nn_setsockopt.3compat#,nn_setsockopt()>>`|set socket option
|`<<nn_bind.3compat#,nn_bind()>>`|accept connections from remote peers
|`<<nn_connect.3compat#,nn_connect()>>`|connect to remote peer
|`<<nn_send.3compat#,nn_send()>>`|send data
|`<<nn_recv.3compat#,nn_recv()>>`|receive data
|`<<nn_shutdown.3compat#,nn_shutdown()>>`|shut down endpoint
|`<<nn_close.3compat#,nn_close()>>`|close socket
|`<<nn_poll.3compat#,nn_poll()>>`|poll sockets
|`<<nn_device.3compat#,nn_device()>>`|create forwarding device
|`<<nn_recvmsg.3compat#,nn_recvmsg()>>`|receive message
|`<<nn_sendmsg.3compat#,nn_sendmsg()>>`|send message
|`<<nn_cmsg.3compat#,nn_cmsg()>>`|message control data
|`<<nn_get_statistic.3compat#,nn_get_statistic()>>`|get statistic (stub)
|`<<nn_allocmsg.3compat#,nn_allocmsg()>>`|allocate message
|`<<nn_reallocmsg.3compat#,nn_reallocmsg()>>`|reallocate message
|`<<nn_freemsg.3compat#,nn_freemsg()>>`|free message
|`<<nn_errno.3compat#,nn_errno()>>`|return most recent error
|`<<nn_strerror.3compat#,nn_strerror()>>`|return message for error
|`<<nn_term.3compat#,nn_term()>>`|terminate library
|===
endif::[]

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: Access to statistics using this legacy API
(`<<nn_get_statistic.3compat#,nn_get_statistic()>>`) is unsupported.

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.

== SEE ALSO

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