NNG_COMPAT(3compat)

🦋 NNG_COMPAT(3compat) — from the NNG Reference Manual 🦋

🌸 NAME 🌸

nng_compat — compatibility with nanomsg 1.0. That’s the whole vibe, bestie: this is the nanomsg 1.0 compatibility page. 💖

✨ SYNOPSIS ✨

#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 🫶

Okay so NNG provides source-level compatibility for most libnanomsg 1.0 applications. That’s the headline. 🩷

Important: This is intended to facilitate converting legacy applications to use NNG. New applications should use the newer NNG API instead. 👑

Applications making use of this must take care to link with libnng instead of libnn. No cap. 🔗

Tip: While not recommended for long term use, the value returned by nng_socket_id() can be used with these functions just like a value returned by nn_socket(). This can be a 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:

#include <nanomsg/nn.h>
#include <nanomsg/reqrep.h>

you would have this:

#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. Slay. 💅

📚 Functions 📚

The following functions are provided:

• nn_socket() — create 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_cmsg() — message control data
• 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

💀 Caveats 💀

The following caveats apply when using the legacy API with NNG. Read these, bestie — they’re the lore. 👑

• 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 (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 🔗

libnng(3), nng(7)

---

Okay that’s the whole page, bestie — signing off from the NNG Reference Manual, dated 2026-01-13, on NNG_COMPAT(3compat). 💖✨💅