1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
|
# 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_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 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}}
|
