= nng_compat(3compat) // // Copyright 2018 Staysail Systems, Inc. // Copyright 2018 Capitar IT Group BV // // 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 #include #include #include #include #include #include #include #include #include #include ---- == 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 <> 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 `` instead refer to ``. For example, instead of: [source,c] ---- #include #include ---- you would have this: [source,c] ---- #include #include ---- 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)]