doompanning/docs/man/nng_compat.3compat.adoc

= 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 <nanomsg/nn.h>

#include <nanomsg/bus.h>
#include <nanomsg/pair.h>
#include <nanomsg/pipeline.h>
#include <nanomsg/pubsub.h>
#include <nanomsg/reqrep.h>
#include <nanomsg/survey.h>

#include <nanomsg/inproc.h>
#include <nanomsg/ipc.h>
#include <nanomsg/tcp.h>
#include <nanomsg/ws.h>
----

== DESCRIPTION

(((compatibility layer)))
xref:nng.7.adoc[_NNG_] provides source-level compatibility for
most _libnanomsg_ 1.0 applications.

IMPORTANT: This is intended to facilitate converting ((legacy applications)) to
use _NNG_.
New applications should use the newer xref:nng.7.adoc[_NNG_] API instead.

Applications making use of this must take care
to link with xref:libnng.3.adoc[_libnng_] instead of _libnn_.

TIP: While not recommended for long term use, the value returned by
xref:nng_socket_id.3.adoc[`nng_socket_id()`] can be used with these functions
just like a value returned by xref:nn_socket.3compat.adoc[`nn_socket()`].
This can be way to facilitate incremental transition to the new API.

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 new API.

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

=== Compiling

When compiling legacy _nanomsg_ applications, it will generally be
necessary to change the include search path to add the `compat` subdirectory
of the directory where headers were installed.
For example, if _NNG_ is installed in `$prefix`, then header files will
normally be located in `$prefix/include/nng`.
In this case, to build legacy _nanomsg_ apps against _NNG_ you would
add `$prefix/include/nng/compat` to your compiler's search path.

Alternatively, you can change your source code so that `#include` statements
referring to `<nanomsg>` instead refer to `<nng/compat/nanomsg>`.
For example, instead of:

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

you would have this:

[source,c]
----
#include <nng/compat/nanomsg/nn.h>
#include <nng/compat/nanomsg/reqrep.h>
----

Legacy applications built using these methods should be linked against _libnng_
instead of _libnn_, just like any other _NNG_ application.

=== 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]
xref:nn_socket.3compat.adoc[`nn_socket()`]:: create socket
xref:nn_getsockopt.3compat.adoc[`nn_getsockopt()`]:: get socket option
xref:nn_setsockopt.3compat.adoc[`nn_setsockopt()`]:: set socket option
xref:nn_bind.3compat.adoc[`nn_bind()`]:: accept connections from remote peers
xref:nn_connect.3compat.adoc[`nn_connect()`]:: connect to remote peer
xref:nn_send.3compat.adoc[`nn_send()`]:: send data
xref:nn_recv.3compat.adoc[`nn_recv()`]:: receive data
xref:nn_shutdown.3compat.adoc[`nn_shutdown()`]:: shut down endpoint
xref:nn_close.3compat.adoc[`nn_close()`]:: close socket
xref:nn_poll.3compat.adoc[`nn_poll()`]:: poll sockets
xref:nn_device.3compat.adoc[`nn_device()`]:: create forwarding device
xref:nn_recvmsg.3compat.adoc[`nn_recvmsg()`]:: receive message
xref:nn_sendmsg.3compat.adoc[`nn_sendmsg()`]:: send message
xref:nn_cmsg.3compat.adoc[`nn_cmsg()`]:: message control data
xref:nn_get_statistic.3compat.adoc[`nn_get_statistic()`]:: get statistic (stub)
xref:nn_allocmsg.3compat.adoc[`nn_allocmsg()`]:: allocate message
xref:nn_reallocmsg.3compat.adoc[`nn_reallocmsg()`]:: reallocate message
xref:nn_freemsg.3compat.adoc[`nn_freemsg()`]:: free message
xref:nn_errno.3compat.adoc[`nn_errno()`]:: return most recent error
xref:nn_strerror.3compat.adoc[`nn_strerror()`]:: return message for error
xref:nn_term.3compat.adoc[`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"]
|===
|xref:nn_socket.3compat.adoc[`nn_socket()`]|create socket
|xref:nn_getsockopt.3compat.adoc[`nn_getsockopt()`]|get socket option
|xref:nn_setsockopt.3compat.adoc[`nn_setsockopt()`]|set socket option
|xref:nn_bind.3compat.adoc[`nn_bind()`]|accept connections from remote peers
|xref:nn_connect.3compat.adoc[`nn_connect()`]|connect to remote peer
|xref:nn_send.3compat.adoc[`nn_send()`]|send data
|xref:nn_recv.3compat.adoc[`nn_recv()`]|receive data
|xref:nn_shutdown.3compat.adoc[`nn_shutdown()`]|shut down endpoint
|xref:nn_close.3compat.adoc[`nn_close()`]|close socket
|xref:nn_poll.3compat.adoc[`nn_poll()`]|poll sockets
|xref:nn_device.3compat.adoc[`nn_device()`]|create forwarding device
|xref:nn_recvmsg.3compat.adoc[`nn_recvmsg()`]|receive message
|xref:nn_sendmsg.3compat.adoc[`nn_sendmsg()`]|send message
|xref:nn_cmsg.3compat.adoc[`nn_cmsg()`]|message control data
|xref:nn_get_statistic.3compat.adoc[`nn_get_statistic()`]|get statistic (stub)
|xref:nn_allocmsg.3compat.adoc[`nn_allocmsg()`]|allocate message
|xref:nn_reallocmsg.3compat.adoc[`nn_reallocmsg()`]|reallocate message
|xref:nn_freemsg.3compat.adoc[`nn_freemsg()`]|free message
|xref:nn_errno.3compat.adoc[`nn_errno()`]|return most recent error
|xref:nn_strerror.3compat.adoc[`nn_strerror()`]|return message for error
|xref:nn_term.3compat.adoc[`nn_term()`]|terminate library
|===
endif::[]

=== Caveats

The following caveats apply when using the legacy API with _NNG_.

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

* The following options (`nn_getsockopt`) are unsupported:
  `NN_SNDPRIO`, `NN_RCVPRIO`, `NN_IPV4ONLY`.
  The priority options may be supported in the future, when
  the underlying capability is present in _NNG_.

* Access to statistics using this legacy API
  (xref:nn_get_statistic.3compat.adoc[`nn_get_statistic()`]) is unsupported.

* 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.

* Only absolute paths are supported in `ipc://` URLs.
  For example, `ipc:///tmp/mysocket` is acceptable, but `ipc://mysocket` is not.

* The WebSocket transport in this implementation (`ws://` URLs)
  only supports BINARY frames.

* 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.

* ABI versioning of the compatibility layer is not supported,
  and the `NN_VERSION_` macros are not present.

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

* The TCP transport (`tcp://` 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.)

* The values of `NN_RCVMAXSIZE` are constrained.
  Specifically, values set larger than 2GB using the new API will be reported
  as unlimited (`-1`) in the new API, and the value `0` will disable any
  enforcement, just like `-1`.
  (There is no practical reason to ever want to limit the receive size to
  zero.)

* This implementation counts buffers in terms of messages rather than bytes.
  As a result, the buffer sizes accessed with `NN_SNDBUF` and `NN_RCVBUF` 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.

== SEE ALSO

[.text-left]
xref:libnng.3.adoc[libnng(3)],
xref:nng.7.adoc[nng(7)]