1= nng_compat(3compat) 2// 3// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> 4// Copyright 2018 Capitar IT Group BV <info@capitar.com> 5// 6// This document is supplied under the terms of the MIT License, a 7// copy of which should be located in the distribution where this 8// file was obtained (LICENSE.txt). A copy of the license may also be 9// found online at https://opensource.org/licenses/MIT. 10// 11 12== NAME 13 14nng_compat - compatibility with nanomsg 1.0 15 16== SYNOPSIS 17 18[source, c] 19---- 20#include <nanomsg/nn.h> 21 22#include <nanomsg/bus.h> 23#include <nanomsg/pair.h> 24#include <nanomsg/pipeline.h> 25#include <nanomsg/pubsub.h> 26#include <nanomsg/reqrep.h> 27#include <nanomsg/survey.h> 28 29#include <nanomsg/inproc.h> 30#include <nanomsg/ipc.h> 31#include <nanomsg/tcp.h> 32#include <nanomsg/ws.h> 33---- 34 35== DESCRIPTION 36 37(((compatibility layer))) 38xref:nng.7.adoc[_NNG_] provides source-level compatibility for 39most _libnanomsg_ 1.0 applications. 40 41IMPORTANT: This is intended to facilitate converting ((legacy applications)) to 42use _NNG_. 43New applications should use the newer xref:nng.7.adoc[_NNG_] API instead. 44 45Applications making use of this must take care 46to link with xref:libnng.3.adoc[_libnng_] instead of _libnn_. 47 48TIP: While not recommended for long term use, the value returned by 49xref:nng_socket_id.3.adoc[`nng_socket_id()`] can be used with these functions 50just like a value returned by xref:nn_socket.3compat.adoc[`nn_socket()`]. 51This can be way to facilitate incremental transition to the new API. 52 53NOTE: Some capabilities, protocols, and transports, will not be accessible 54using this API, as the compatible API has no provision for expression 55of certain concepts introduced in the new API. 56 57NOTE: While reasonable efforts have been made to provide for compatibility, 58some things may behave differently, and some less common parts of the 59_libnanomsg_ 1.0 API are not supported at this time, including certain 60options and the statistics API. 61See the <<Caveats>> section below. 62 63=== Compiling 64 65When compiling legacy _nanomsg_ applications, it will generally be 66necessary to change the include search path to add the `compat` subdirectory 67of the directory where headers were installed. 68For example, if _NNG_ is installed in `$prefix`, then header files will 69normally be located in `$prefix/include/nng`. 70In this case, to build legacy _nanomsg_ apps against _NNG_ you would 71add `$prefix/include/nng/compat` to your compiler's search path. 72 73Alternatively, you can change your source code so that `#include` statements 74referring to `<nanomsg>` instead refer to `<nng/compat/nanomsg>`. 75For example, instead of: 76 77[source,c] 78---- 79#include <nanomsg/nn.h> 80#include <nanomsg/reqrep.h> 81---- 82 83you would have this: 84 85[source,c] 86---- 87#include <nng/compat/nanomsg/nn.h> 88#include <nng/compat/nanomsg/reqrep.h> 89---- 90 91Legacy applications built using these methods should be linked against _libnng_ 92instead of _libnn_, just like any other _NNG_ application. 93 94=== Functions 95 96The following functions are provided: 97 98// For PDF, we don't have horizontal lists, so we have to conditionalize 99// this and use tables there -- it looks ugly otherwise. 100ifndef::backend-pdf[] 101[horizontal] 102xref:nn_socket.3compat.adoc[`nn_socket()`]:: create socket 103xref:nn_getsockopt.3compat.adoc[`nn_getsockopt()`]:: get socket option 104xref:nn_setsockopt.3compat.adoc[`nn_setsockopt()`]:: set socket option 105xref:nn_bind.3compat.adoc[`nn_bind()`]:: accept connections from remote peers 106xref:nn_connect.3compat.adoc[`nn_connect()`]:: connect to remote peer 107xref:nn_send.3compat.adoc[`nn_send()`]:: send data 108xref:nn_recv.3compat.adoc[`nn_recv()`]:: receive data 109xref:nn_shutdown.3compat.adoc[`nn_shutdown()`]:: shut down endpoint 110xref:nn_close.3compat.adoc[`nn_close()`]:: close socket 111xref:nn_poll.3compat.adoc[`nn_poll()`]:: poll sockets 112xref:nn_device.3compat.adoc[`nn_device()`]:: create forwarding device 113xref:nn_recvmsg.3compat.adoc[`nn_recvmsg()`]:: receive message 114xref:nn_sendmsg.3compat.adoc[`nn_sendmsg()`]:: send message 115xref:nn_cmsg.3compat.adoc[`nn_cmsg()`]:: message control data 116xref:nn_get_statistic.3compat.adoc[`nn_get_statistic()`]:: get statistic (stub) 117xref:nn_allocmsg.3compat.adoc[`nn_allocmsg()`]:: allocate message 118xref:nn_reallocmsg.3compat.adoc[`nn_reallocmsg()`]:: reallocate message 119xref:nn_freemsg.3compat.adoc[`nn_freemsg()`]:: free message 120xref:nn_errno.3compat.adoc[`nn_errno()`]:: return most recent error 121xref:nn_strerror.3compat.adoc[`nn_strerror()`]:: return message for error 122xref:nn_term.3compat.adoc[`nn_term()`]:: terminate library 123endif::[] 124ifdef::backend-pdf[] 125// Add links for the following as they are written. 126[.hdlist,width=90%, grid=rows,cols="1,2", align="center"] 127|=== 128|xref:nn_socket.3compat.adoc[`nn_socket()`]|create socket 129|xref:nn_getsockopt.3compat.adoc[`nn_getsockopt()`]|get socket option 130|xref:nn_setsockopt.3compat.adoc[`nn_setsockopt()`]|set socket option 131|xref:nn_bind.3compat.adoc[`nn_bind()`]|accept connections from remote peers 132|xref:nn_connect.3compat.adoc[`nn_connect()`]|connect to remote peer 133|xref:nn_send.3compat.adoc[`nn_send()`]|send data 134|xref:nn_recv.3compat.adoc[`nn_recv()`]|receive data 135|xref:nn_shutdown.3compat.adoc[`nn_shutdown()`]|shut down endpoint 136|xref:nn_close.3compat.adoc[`nn_close()`]|close socket 137|xref:nn_poll.3compat.adoc[`nn_poll()`]|poll sockets 138|xref:nn_device.3compat.adoc[`nn_device()`]|create forwarding device 139|xref:nn_recvmsg.3compat.adoc[`nn_recvmsg()`]|receive message 140|xref:nn_sendmsg.3compat.adoc[`nn_sendmsg()`]|send message 141|xref:nn_cmsg.3compat.adoc[`nn_cmsg()`]|message control data 142|xref:nn_get_statistic.3compat.adoc[`nn_get_statistic()`]|get statistic (stub) 143|xref:nn_allocmsg.3compat.adoc[`nn_allocmsg()`]|allocate message 144|xref:nn_reallocmsg.3compat.adoc[`nn_reallocmsg()`]|reallocate message 145|xref:nn_freemsg.3compat.adoc[`nn_freemsg()`]|free message 146|xref:nn_errno.3compat.adoc[`nn_errno()`]|return most recent error 147|xref:nn_strerror.3compat.adoc[`nn_strerror()`]|return message for error 148|xref:nn_term.3compat.adoc[`nn_term()`]|terminate library 149|=== 150endif::[] 151 152=== Caveats 153 154The following caveats apply when using the legacy API with _NNG_. 155 156* Socket numbers can be quite large. 157 The legacy _libnanomsg_ attempted to reuse socket numbers, like 158 file descriptors in UNIX systems. 159 _NNG_ avoids this to prevent accidental reuse or 160 collision after a descriptor is closed. 161 Consequently, socket numbers can become quite large, and should 162 probably not be used for array indices. 163 164* The following options (`nn_getsockopt`) are unsupported: 165 `NN_SNDPRIO`, `NN_RCVPRIO`, `NN_IPV4ONLY`. 166 The priority options may be supported in the future, when 167 the underlying capability is present in _NNG_. 168 169* Access to statistics using this legacy API 170 (xref:nn_get_statistic.3compat.adoc[`nn_get_statistic()`]) is unsupported. 171 172* Some transports can support longer URLs than legacy _libnanomsg_ can. 173 It is a good idea to use short pathnames in URLs if interoperability 174 is a concern. 175 176* Only absolute paths are supported in `ipc://` URLs. 177 For example, `ipc:///tmp/mysocket` is acceptable, but `ipc://mysocket` is not. 178 179* The WebSocket transport in this implementation (`ws://` URLs) 180 only supports BINARY frames. 181 182* Some newer transports are unusable from this mode. 183 In particular, this legacy API offers no way to configure 184 TLS or ZeroTier parameters that may be required for use. 185 186* ABI versioning of the compatibility layer is not supported, 187 and the `NN_VERSION_` macros are not present. 188 189* Runtime symbol information is not implemented. 190 Specifically, there is no `nn_symbol()` function yet. 191 (This may be addressed later if there is a need.) 192 193* The TCP transport (`tcp://` URLs) does not support specifying the local 194 address or interface when binding. (This could be fixed in the future, 195 but most likely this will be available only using the new API.) 196 197* The values of `NN_RCVMAXSIZE` are constrained. 198 Specifically, values set larger than 2GB using the new API will be reported 199 as unlimited (`-1`) in the new API, and the value `0` will disable any 200 enforcement, just like `-1`. 201 (There is no practical reason to ever want to limit the receive size to 202 zero.) 203 204* This implementation counts buffers in terms of messages rather than bytes. 205 As a result, the buffer sizes accessed with `NN_SNDBUF` and `NN_RCVBUF` are 206 rounded up to a whole number of kilobytes, then divided by 1024, in order 207 to approximate buffering assuming 1 KB messages. 208 Few applications should need to adjust the default values. 209 210== SEE ALSO 211 212[.text-left] 213xref:libnng.3.adoc[libnng(3)], 214xref:nng.7.adoc[nng(7)] 215