nanomsg.md

Migrating from libnanomsg

Previous version of NNG offered direct API compatibility with libnanomsg, but that support is no longer offered in this version.

If your application is still using legacy libnanomsg APIs, you will need to update it for this version of NNG.

Header Files

Most applications can replace all #include <nn/*.h> statements with #include <nng/nng.h>.

Link Libraries

Replace -lnanomsg with -lnng. It may be necessary to include additional system libraries, such as -lpthread, depending on your system.

Initialization

It is necessary to explicitly initialize the library, using the [nng_init] function. This must be called before any other function.

Types

Sockets, dialers, and listeners in libnanomsg are simple integers. In NNG, these are struct types.

Messages are quite different in NNG, with the absence of the POSIX message control headers.

The struct nn_msghdr structure has no equivalent. See nng_msg for the NNG approach to messages. Likewise there is no struct nn_cmsghdr equivalent.

API Conversions

Nanomsg API	NNG Equivalent	Notes
nn_strerror	[nng_strerror]
nn_errno	None	Errors are returned directly rather than through errno.
nn_socket	Various	Use the appropriate protocol constructor, such as nng_req0_open.
nn_close	nng_close
nn_bind	nng_listen, nng_listener_create	Allocating a listener with nng_lister_create and configuring it offers more capabilities.
nn_connect	nng_dial, nng_dialer_create	Allocating a dialer with nng_dialer_create and configuring it offers more capabilities.
nn_shutdown	nng_lister_close, nng_dialer_close
nn_allocmsg	[nng_msg_alloc]	There are significant semantic differences.
nn_freemsg	[nng_msg_free]
nn_reallocmsg	[nng_msg_realloc]
nn_send	nng_send
nn_recv	nng_recv
nn_sendmsg	nng_sendmsg
nn_getsockopt	nng_socket_get	NNG has typed accessors for options, and also separate functions for dialers and listeners.
nn_setsockopt	nng_socket_set
nn_device	nng_device
nn_poll	None	Can be constructed using nng_aio. Few if any applications ever used this API.
nn_term	None	The nng_fini API can do this, but is not recommended except when debugging memory leaks.
nn_get_statistic	nng_stats_get	The statistics in NNG are completely different, with different semantics and no stability guarantees.
NN_POLLIN	None	Used only with nn_poll.
NN_POLLOUT	None	Used only with nn_poll.
NN_MSG	NNG_FLAG_ALLOC	See nng_send and nng_recv for details.
NN_CMSG_ALIGN	None
NN_CMSG_FIRSTHDR	None
NN_CMSG_NXTHDR	None
NN_CMSG_DATA	None
NN_CMSG_LEN	None
NN_CMSG_SPACE	None
struct nn_iovec	nng_iov
struct nn_msghdr	[nng_msg]
struct nn_cmsghdr	[nng_msg] and [nng_msg_header]

Options

The following options are changed.

Nanomsg Option	NNG Eqvaivalent	Notes
NN_LINGER	None	NNG does not support tuning this.
NN_SNDBUF	NNG_OPT_SENDBUF	NNG value is given in messages, not bytes.
NN_RCVBUF	NNG_OPT_RECVBUF	NNG value is given in messages, not bytes.
NN_SNDTIMEO	NNG_OPT_SENDTIMEO
NN_RCVTIMEO	NNG_OPT_RECVTIMEO
NN_RECONNECT_IVL	NNG_OPT_RECONNMINT
NN_RECONNECT_IVL_MAX	NNG_OPT_RECONNMAXT
NN_SNDPRIO	None	Not supported in NNG yet.
NN_RCVPRIO	None	Not supported in NNG yet.
NN_RCVFD	[nng_socket_get_recv_poll_fd]	No longer an option, use a function call.
NN_SNDFD	[nng_socket_get_send_poll_fd]	No longer an option, use a function call.
NN_DOMAIN	None	NNG options are not divided by domain or protocol.
NN_PROTOCOL	[nng_socket_proto_id]	No longer an option. See also nng_socket_proto_name.
NN_IPV4ONLY	None	Use URL such as tcp4:// to obtain this functionality.
NN_SOCKET_NAME	None	Removed from NNG.
NN_MAXTTL	NNG_OPT_MAXTTL
NN_SUB_SUBSCRIBE	[nng_sub0_socket_subscribe]	No longer an option, use a function call.
NN_SUB_UNSUBSCRIBE	[nng_sub0_socket_unsubscribe]	No longer an option, use a function call.

Error Codes

Most of the error codes have similar names in NNG, just prefixed with NNG_. There are some exceptions. Be aware that the numeric values are not the same.

Nanomsg Error	NNG Error	Notes
EINTR	[NNG_EINTR]
ENOMEM	[NNG_ENOMEM]
EINVAL	[NNG_EINVAL], [NNG_EADDRINVAL], [NNG_EBADTYPE], [NNG_EAMBIGUOUS]	NNG discrimates between different types of errors.
EBUSY	[NNG_EBUSY]
ETIMEDOUT	[NNG_ETIMEDOUT]
ECONNREFUSED	[NNG_ECONNREFUSED]
EBADF	[NNG_ECLOSED], [NNG_ECANCELED]	Canceling an operation returns differently than using an invalid or closed object.
EAGAIN	[NNG_EAGAIN]
ENOTSUP	[NNG_ENOTSUP]
EADDRINUSE	[NNG_EADDRINUSE]
EFSM	[NNG_ESTATE]	Not a legal POSIX errno value.
ENOENT	[NNG_ENOENT]
EPROTO	[NNG_EPROTO]
EHOSTUNREACH	[NNG_EUNREACHABLE]
EACCCES	[NNG_EPERM], [NNG_EWRITEONLY], [NNG_EREADONLY], [NNG_ECRYPTO], [NNG_EPEERAUTH]	NNG has more fine grained reasons for access failures.
EMSGSIZE	[NNG_EMSGSIZE]
ECONNABORTED	[NNG_ECONNABORTED]
ECONNRESET	[NNG_ECONNRESET]
EEXIST	[NNG_EEXIST]
EMFILE	[NNG_ENOFILES]
ENOSPC	[NNG_ENOSPC]

Local Addresses for Dialing

The ability to specify the source address in the UROL,to use when using nn_dial inside the URL is not present in NNG. The correct way to specify the local address is using the NNG_OPT_LOCADDR option on the dialer before starting to dial.

{{#include ../xref.md}}