# 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_socket_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_listener_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`           | [`nng_fini`]                                 | 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_sendmsg`], [`nng_recvmsg`]             | There are differences as a separate [`nng_msg`] structure is involved.                                |
| `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 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 URL,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}}
