Migration update referencing nng_init (but note not documented yet.)

3 files changed, 91 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,
diff --git a/docs/ref/xref.md b/docs/ref/xref.md
index 1139fa87..55ec1a3c 100644
--- a/docs/ref/xref.md
+++ b/docs/ref/xref.md
@@ -93,6 +93,8 @@
 [`nng_aio_set_output`]: /TODO.md
 [`nng_send`]: /TODO.md
 [`nng_recv`]: /TODO.md
+[`nng_init`]: /TODO.md
+[`nng_fini`]: /TODO.md
 
 <!-- Macros -->
 
@@ -103,6 +105,7 @@
 [`NNG_ETIMEDOUT`]: /api/errors.md#NNG_ETIMEDOUT
 [`NNG_ECONNREFUSED`]: /api/errors.md#NNG_ECONNREFUSED
 [`NNG_ECLOSED`]: /api/errors.md#NNG_ECLOSED
+[`NNG_EPROTO`]: /api/errors.md#NNG_EPROTO
 [`NNG_EAGAIN`]: /api/errors.md#NNG_EAGAIN
 [`NNG_ENOTSUP`]: /api/errors.md#NNG_ENOTSUP
 [`NNG_EADDRINUSE`]: /api/errors.md#NNG_EADDRINUSE