aboutsummaryrefslogtreecommitdiff
path: root/docs/ref/migrate
diff options
context:
space:
mode:
authorGarrett D'Amore <garrett@damore.org>2024-11-10 00:47:11 -0800
committerGarrett D'Amore <garrett@damore.org>2024-11-11 11:03:13 -0800
commit95fc24120509110553e03573028c34c76a53eb7f (patch)
tree398c024fe2a4b181ea0c23e126ee4cfca488d45e /docs/ref/migrate
parent713b80f440cb414cd0b856bde0ea1b31f939777f (diff)
downloadnng-95fc24120509110553e03573028c34c76a53eb7f.tar.gz
nng-95fc24120509110553e03573028c34c76a53eb7f.tar.bz2
nng-95fc24120509110553e03573028c34c76a53eb7f.zip
Migration update referencing nng_init (but note not documented yet.)
Diffstat (limited to 'docs/ref/migrate')
-rw-r--r--docs/ref/migrate/nanomsg.md159
-rw-r--r--docs/ref/migrate/nng1.md5
2 files changed, 88 insertions, 76 deletions
diff --git a/docs/ref/migrate/nanomsg.md b/docs/ref/migrate/nanomsg.md
index 67e6505a..be4d2665 100644
--- a/docs/ref/migrate/nanomsg.md
+++ b/docs/ref/migrate/nanomsg.md
@@ -15,6 +15,11 @@ Most applications can replace all `#include <nn/*.h>` statements with `#include
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.
@@ -28,90 +33,92 @@ 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` | No equivalent. Errors are redirectly rather than through `errno`. |
-| `nn_socket` | 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` |
+| 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` | `NNG_OPT_SOCKNAME` |
-| `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. |
+| 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` | `NNG_OPT_SOCKNAME` |
+| `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` |
+| 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`] |
+
+{{#include ../xref.md}}
diff --git a/docs/ref/migrate/nng1.md b/docs/ref/migrate/nng1.md
index 7a6698d0..2c6087e2 100644
--- a/docs/ref/migrate/nng1.md
+++ b/docs/ref/migrate/nng1.md
@@ -8,6 +8,11 @@ This guide should help in migrating applications to use NNG 2.0.
Applications using the legacy `libnanomsg` API will have to be updated to native _NNG_ interfaces.
See the [Migrating From libnanomsg](nanomsg.md) chapter for details.
+## Library Initialization
+
+It is now required for applications to initialize the library explicitly before using it.
+This is done using the [`nng_init`] function.
+
## Transport Specific Functions
Transports have not needed to be registered for a long time now,
generated by cgit v1.2.3-70-g09d2 (git 2.46.0) at 2026-01-18 11:53:36 +0000