fixes #1071 tran_chkopt can be cleaned up

This is a sweeping cleanup of the transport logic around options,
and also harmonizes the names used when setting or getting options.
Additionally, legacy methods are now moved into a separate file and
can be elided via CMake or a preprocessor define.

Fundamentally, the ability to set to transport options via the socket
is deprecated; there are numerous problems with this and my earlier
approaches to deal with this have been somewhat misguided.  Further
these approaches will not work with future protocol work that is
planned (were some options need to be negotiated with peers at the
time of connection establishment.)

Documentation has been updated to reflect this.  The test suites still
make rather broad use of the older APIs, and will be converted later.

16 files changed, 62 insertions, 43 deletions

diff --git a/docs/man/nng_ctx.5.adoc b/docs/man/nng_ctx.5.adoc
index b097d866..cc859c48 100644
--- a/docs/man/nng_ctx.5.adoc
+++ b/docs/man/nng_ctx.5.adoc
@@ -162,11 +162,11 @@ start_echo_service(nng_socket rep_socket)
 xref:libnng.3.adoc[libnng(3)],
 xref:nng_ctx_close.3.adoc[nng_ctx_close(3)],
 xref:nng_ctx_open.3.adoc[nng_ctx_open(3)],
-xref:nng_ctx_getopt.3.adoc[nng_ctx_getopt(3)],
+xref:nng_ctx_get.3.adoc[nng_ctx_get(3)],
 xref:nng_ctx_id.3.adoc[nng_ctx_id(3)],
 xref:nng_ctx_recv.3.adoc[nng_ctx_recv(3)],
 xref:nng_ctx_send.3.adoc[nng_ctx_send(3)],
-xref:nng_ctx_setopt.3.adoc[nng_ctx_setopt(3)],
+xref:nng_ctx_set.3.adoc[nng_ctx_set(3)],
 xref:nng_dialer.5.adoc[nng_dialer(5)],
 xref:nng_listener.5.adoc[nng_listener(5)],
 xref:nng_socket.5.adoc[nng_socket(5)],
diff --git a/docs/man/nng_ctx_getopt.3.adoc b/docs/man/nng_ctx_getopt.3.adoc
index daba5e59..5b7afd70 100644
--- a/docs/man/nng_ctx_getopt.3.adoc
+++ b/docs/man/nng_ctx_getopt.3.adoc
@@ -1,6 +1,6 @@
 = nng_ctx_getopt(3)
 //
-// Copyright 2019 Staysail Systems, Inc. <info@staysail.tech>
+// Copyright 2020 Staysail Systems, Inc. <info@staysail.tech>
 // Copyright 2018 Capitar IT Group BV <info@capitar.com>
 //
 // This document is supplied under the terms of the MIT License, a
@@ -37,7 +37,8 @@ int nng_ctx_getopt_uint64(nng_ctx ctx, const char *opt, uint64_t *u64p);
 
 == DESCRIPTION
 
-NOTE: These functions are deprecated.  Please see xref:nng_ctx_get.3.adoc[nng_ctx_get].
+IMPORTANT: These functions are deprecated.  Please see xref:nng_ctx_get.3.adoc[nng_ctx_get].
+They may not be present if the library was built with `NNG_ELIDE_DEPRECATED`.
 
 (((options, context)))
 The `nng_ctx_getopt()` functions are used to retrieve option values for
diff --git a/docs/man/nng_ctx_setopt.3.adoc b/docs/man/nng_ctx_setopt.3.adoc
index 1fd36e66..f6f7f9ef 100644
--- a/docs/man/nng_ctx_setopt.3.adoc
+++ b/docs/man/nng_ctx_setopt.3.adoc
@@ -1,6 +1,6 @@
 = nng_ctx_setopt(3)
 //
-// Copyright 2019 Staysail Systems, Inc. <info@staysail.tech>
+// Copyright 2020 Staysail Systems, Inc. <info@staysail.tech>
 // Copyright 2018 Capitar IT Group BV <info@capitar.com>
 //
 // This document is supplied under the terms of the MIT License, a
@@ -36,7 +36,8 @@ int nng_ctx_setopt_uint64(nng_ctx ctx, const char *opt, uint64_t u64);
 
 == DESCRIPTION
 
-NOTE: These functions are deprecated.  Please see xref:nng_ctx_set.3.adoc[nng_ctx_set].
+IMPORTANT: These functions are deprecated.  Please see xref:nng_ctx_set.3.adoc[nng_ctx_set].
+They may not be present if the library was built with `NNG_ELIDE_DEPRECATED`.
 
 (((options, context)))
 The `nng_ctx_setopt()` functions are used to configure options for
diff --git a/docs/man/nng_dialer_get.3.adoc b/docs/man/nng_dialer_get.3.adoc
index 29acb811..86f606a9 100644
--- a/docs/man/nng_dialer_get.3.adoc
+++ b/docs/man/nng_dialer_get.3.adoc
@@ -1,6 +1,6 @@
 = nng_dialer_get(3)
 //
-// Copyright 2019 Staysail Systems, Inc. <info@staysail.tech>
+// Copyright 2020 Staysail Systems, Inc. <info@staysail.tech>
 // Copyright 2018 Capitar IT Group BV <info@capitar.com>
 //
 // This document is supplied under the terms of the MIT License, a
@@ -47,8 +47,7 @@ the xref:nng_dialer.5.adoc[dialer] _d_.
 The actual options that may be retrieved in this way
 vary, and many are documented in xref:nng_options.5.adoc[nng_options(5)].
 
-Additionally some transport-specific options and protocol-specific options
-are documented with the transports and protocols themselves.
+Additionally some transport-specific options are documented with the transports themselves.
 
 === Forms
 
diff --git a/docs/man/nng_dialer_getopt.3.adoc b/docs/man/nng_dialer_getopt.3.adoc
index 4f8b3a3e..f69f433f 100644
--- a/docs/man/nng_dialer_getopt.3.adoc
+++ b/docs/man/nng_dialer_getopt.3.adoc
@@ -1,6 +1,6 @@
 = nng_dialer_getopt(3)
 //
-// Copyright 2019 Staysail Systems, Inc. <info@staysail.tech>
+// Copyright 2020 Staysail Systems, Inc. <info@staysail.tech>
 // Copyright 2018 Capitar IT Group BV <info@capitar.com>
 //
 // This document is supplied under the terms of the MIT License, a
@@ -41,7 +41,8 @@ int nng_dialer_getopt_uint64(nng_dialer d, const char *opt, uint64_t *u64p);
 
 == DESCRIPTION
 
-NOTE: These functions are deprecated.  Please see xref:nng_dialer_get.3.adoc[nng_dialer_get].
+IMPORTANT: These functions are deprecated.  Please see xref:nng_dialer_get.3.adoc[nng_dialer_get].
+They may not be present if the library was built with `NNG_ELIDE_DEPRECATED`.
 
 (((options, dialer)))
 The `nng_dialer_getopt()` functions are used to retrieve option values for
@@ -49,8 +50,7 @@ the xref:nng_dialer.5.adoc[dialer] _d_.
 The actual options that may be retrieved in this way
 vary, and many are documented in xref:nng_options.5.adoc[nng_options(5)].
 
-Additionally some transport-specific options and protocol-specific options
-are documented with the transports and protocols themselves.
+Additionally some transport-specific options are documented with the transports themselves.
 
 === Forms
 
diff --git a/docs/man/nng_dialer_set.3.adoc b/docs/man/nng_dialer_set.3.adoc
index 76f20e6c..3363eae9 100644
--- a/docs/man/nng_dialer_set.3.adoc
+++ b/docs/man/nng_dialer_set.3.adoc
@@ -1,6 +1,6 @@
 = nng_dialer_set(3)
 //
-// Copyright 2019 Staysail Systems, Inc. <info@staysail.tech>
+// Copyright 2020 Staysail Systems, Inc. <info@staysail.tech>
 // Copyright 2018 Capitar IT Group BV <info@capitar.com>
 //
 // This document is supplied under the terms of the MIT License, a
@@ -46,8 +46,7 @@ the xref:nng_dialer.5.adoc[dialer] _d_.
 The actual options that may be configured in this way
 vary, and many are documented in xref:nng_options.5.adoc[nng_options(5)].
 
-Additionally some transport-specific options are documented with the
-transports themselves.
+Additionally some transport-specific options are documented with the transports themselves.
 
 NOTE: Once a dialer has started, it is generally not possible to change
 its configuration.
diff --git a/docs/man/nng_dialer_setopt.3.adoc b/docs/man/nng_dialer_setopt.3.adoc
index a554acb5..3aaff1eb 100644
--- a/docs/man/nng_dialer_setopt.3.adoc
+++ b/docs/man/nng_dialer_setopt.3.adoc
@@ -1,6 +1,6 @@
 = nng_dialer_setopt(3)
 //
-// Copyright 2019 Staysail Systems, Inc. <info@staysail.tech>
+// Copyright 2020 Staysail Systems, Inc. <info@staysail.tech>
 // Copyright 2018 Capitar IT Group BV <info@capitar.com>
 //
 // This document is supplied under the terms of the MIT License, a
@@ -40,7 +40,8 @@ int nng_dialer_setopt_uint64(nng_dialer d, const char *opt, uint64_t u64);
 
 == DESCRIPTION
 
-NOTE: These functions are deprecated.  Please see xref:nng_dialer_set.3.adoc[nng_dialer_set].
+IMPORTANT: These functions are deprecated.  Please see xref:nng_dialer_set.3.adoc[nng_dialer_set].
+They may not be present if the library was built with `NNG_ELIDE_DEPRECATED`.
 
 (((options, dialer)))
 The `nng_dialer_setopt()` functions are used to configure options for
diff --git a/docs/man/nng_getopt.3.adoc b/docs/man/nng_getopt.3.adoc
index de3e882f..0c65bd2d 100644
--- a/docs/man/nng_getopt.3.adoc
+++ b/docs/man/nng_getopt.3.adoc
@@ -1,6 +1,6 @@
 = nng_getopt(3)
 //
-// Copyright 2019 Staysail Systems, Inc. <info@staysail.tech>
+// Copyright 2020 Staysail Systems, Inc. <info@staysail.tech>
 // Copyright 2018 Capitar IT Group BV <info@capitar.com>
 //
 // This document is supplied under the terms of the MIT License, a
@@ -39,7 +39,8 @@ int nng_getopt_uint64(nng_socket s, const char *opt, uint64_t *u64p);
 
 == DESCRIPTION
 
-NOTE: These functions are deprecated.  Please see xref:nng_socket_get.3.adoc[nng_socket_get].
+IMPORTANT: These functions are deprecated.  Please see xref:nng_socket_get.3.adoc[nng_socket_get].
+They may not be present if the library was built with `NNG_ELIDE_DEPRECATED`.
 
 (((options, socket)))
 The `nng_getopt()` functions are used to retrieve option values for
diff --git a/docs/man/nng_listener_get.3.adoc b/docs/man/nng_listener_get.3.adoc
index bd59ffa3..83ae6986 100644
--- a/docs/man/nng_listener_get.3.adoc
+++ b/docs/man/nng_listener_get.3.adoc
@@ -1,6 +1,6 @@
 = nng_listener_get(3)
 //
-// Copyright 2019 Staysail Systems, Inc. <info@staysail.tech>
+// Copyright 2020 Staysail Systems, Inc. <info@staysail.tech>
 // Copyright 2018 Capitar IT Group BV <info@capitar.com>
 //
 // This document is supplied under the terms of the MIT License, a
@@ -47,8 +47,7 @@ the xref:nng_listener.5.adoc[listener] _l_.
 The actual options that may be retrieved in this way
 vary, and many are documented in xref:nng_options.5.adoc[nng_options(5)].
 
-Additionally some transport-specific options and protocol-specific options
-are documented with the transports and protocols themselves.
+Additionally some transport-specific options are documented with the transports themselves.
 
 === Forms
 
diff --git a/docs/man/nng_listener_getopt.3.adoc b/docs/man/nng_listener_getopt.3.adoc
index e232da96..828f440d 100644
--- a/docs/man/nng_listener_getopt.3.adoc
+++ b/docs/man/nng_listener_getopt.3.adoc
@@ -1,6 +1,6 @@
 = nng_listener_getopt(3)
 //
-// Copyright 2019 Staysail Systems, Inc. <info@staysail.tech>
+// Copyright 2020 Staysail Systems, Inc. <info@staysail.tech>
 // Copyright 2018 Capitar IT Group BV <info@capitar.com>
 //
 // This document is supplied under the terms of the MIT License, a
@@ -41,7 +41,8 @@ int nng_listener_getopt_uint64(nng_listener l, const char *opt, uint64_t *u64p);
 
 == DESCRIPTION
 
-NOTE: These functions are deprecated.  Please see xref:nng_listener_get.3.adoc[nng_listener_get].
+IMPORTANT: These functions are deprecated.  Please see xref:nng_listener_get.3.adoc[nng_listener_get].
+They may not be present if the library was built with `NNG_ELIDE_DEPRECATED`.
 
 (((options, listener)))
 The `nng_listener_getopt()` functions are used to retrieve option values for
@@ -49,8 +50,8 @@ the xref:nng_listener.5.adoc[listener] _l_.
 The actual options that may be retrieved in this way
 vary, and many are documented in xref:nng_options.5.adoc[nng_options(5)].
 
-Additionally some transport-specific options and protocol-specific options
-are documented with the transports and protocols themselves.
+Additionally some transport-specific options
+are documented with the transports themselves.
 
 === Forms
 
diff --git a/docs/man/nng_listener_set.3.adoc b/docs/man/nng_listener_set.3.adoc
index 89e3ca20..0cfd2112 100644
--- a/docs/man/nng_listener_set.3.adoc
+++ b/docs/man/nng_listener_set.3.adoc
@@ -1,6 +1,6 @@
 = nng_listener_set(3)
 //
-// Copyright 2019 Staysail Systems, Inc. <info@staysail.tech>
+// Copyright 2020 Staysail Systems, Inc. <info@staysail.tech>
 // Copyright 2018 Capitar IT Group BV <info@capitar.com>
 //
 // This document is supplied under the terms of the MIT License, a
@@ -46,8 +46,7 @@ the xref:nng_listener.5.adoc[listener] _l_.
 The actual options that may be configured in this way
 vary, and many are documented in xref:nng_options.5.adoc[nng_options(5)].
 
-Additionally some transport-specific options and protocol-specific options
-are documented with the transports and protocols themselves.
+Additionally some transport-specific options are documented with the transports themselves.
 
 NOTE: Once a listener has started, it is generally not possible to change
 its configuration.
diff --git a/docs/man/nng_listener_setopt.3.adoc b/docs/man/nng_listener_setopt.3.adoc
index 595b8a19..25411adc 100644
--- a/docs/man/nng_listener_setopt.3.adoc
+++ b/docs/man/nng_listener_setopt.3.adoc
@@ -1,6 +1,6 @@
 = nng_listener_setopt(3)
 //
-// Copyright 2019 Staysail Systems, Inc. <info@staysail.tech>
+// Copyright 2020 Staysail Systems, Inc. <info@staysail.tech>
 // Copyright 2018 Capitar IT Group BV <info@capitar.com>
 //
 // This document is supplied under the terms of the MIT License, a
@@ -40,7 +40,8 @@ int nng_listener_setopt_uint64(nng_listener l, const char *opt, uint64_t u64);
 
 == DESCRIPTION
 
-NOTE: These functions are deprecated.  Please see xref:nng_listener_set.3.adoc[nng_listener_set].
+IMPORTANT: These functions are deprecated.  Please see xref:nng_listener_set.3.adoc[nng_listener_set].
+They may not be present if the library was built with `NNG_ELIDE_DEPRECATED`.
 
 (((options, listener)))
 The `nng_listener_setopt()` functions are used to configure options for
@@ -48,8 +49,8 @@ the xref:nng_listener.5.adoc[listener] _l_.
 The actual options that may be configured in this way
 vary, and many are documented in xref:nng_options.5.adoc[nng_options(5)].
 
-Additionally some transport-specific options and protocol-specific options
-are documented with the transports and protocols themselves.
+Additionally some transport-specific options
+are documented with the transports themselves.
 
 NOTE: Once a listener has started, it is generally not possible to change
 its configuration.
diff --git a/docs/man/nng_options.5.adoc b/docs/man/nng_options.5.adoc
index fa78453c..eb1c873b 100644
--- a/docs/man/nng_options.5.adoc
+++ b/docs/man/nng_options.5.adoc
@@ -196,6 +196,14 @@ per-dialer or per-listener basis.
 IMPORTANT: Applications on hostile networks should set this to a non-zero
 value to prevent denial-of-service attacks.
 +
+IMPORTANT: This option should be set before any listeners or dialers are added.
+Ideally this option should be set on specific dialers or listeners; setting it
+on the socket globally is deprecated behavior, and might not work in a future release,
+or might only work for endpoints that have not yet been created.
+(Maximum receive sizes might be negotiated during connection establishment for
+future transports, which means that the option needs to be set before any connections
+are established.)
++
 NOTE: Some transports may have further message size restrictions.
 
 [[NNG_OPT_RECVTIMEO]]
diff --git a/docs/man/nng_setopt.3.adoc b/docs/man/nng_setopt.3.adoc
index 8a526399..6c21cf95 100644
--- a/docs/man/nng_setopt.3.adoc
+++ b/docs/man/nng_setopt.3.adoc
@@ -1,6 +1,6 @@
 = nng_setopt(3)
 
-// Copyright 2019 Staysail Systems, Inc. <info@staysail.tech>
+// Copyright 2020 Staysail Systems, Inc. <info@staysail.tech>
 // Copyright 2018 Capitar IT Group BV <info@capitar.com>
 //
 // This document is supplied under the terms of the MIT License, a
@@ -38,7 +38,8 @@ int nng_setopt_uint64(nng_socket s, const char *opt, uint64_t u64);
 
 == DESCRIPTION
 
-NOTE: These functions are deprecated.  Please see xref:nng_socket_set.3.adoc[nng_socket_set].
+IMPORTANT: These functions are deprecated.  Please see xref:nng_socket_set.3.adoc[nng_socket_set].
+They may not be present if the library was built with `NNG_ELIDE_DEPRECATED`.
 
 (((options, socket)))
 The `nng_setopt()` functions are used to configure options for
diff --git a/docs/man/nng_socket_get.3.adoc b/docs/man/nng_socket_get.3.adoc
index 6c2ec87e..6d8456ad 100644
--- a/docs/man/nng_socket_get.3.adoc
+++ b/docs/man/nng_socket_get.3.adoc
@@ -1,6 +1,6 @@
 = nng_socket_get(3)
 //
-// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech>
+// Copyright 2020 Staysail Systems, Inc. <info@staysail.tech>
 // Copyright 2018 Capitar IT Group BV <info@capitar.com>
 //
 // This document is supplied under the terms of the MIT License, a
@@ -47,8 +47,12 @@ the xref:nng_socket.5.adoc[socket] _s_.
 The actual options that may be retrieved in this way vary.
 A number of them are documented in xref:nng_options.5.adoc[nng_options(5)].
 
-Additionally transport-specific options and protocol-specific options are
-documented with the transports and protocols themselves.
+Additionally protocol-specific options are documented with the protocols themselves.
+
+IMPORTANT: Access to transport options via this function is deprecated, and may be
+removed from a future release.  Applications should instead make use of
+xref:nng_dialer_get.3.adoc[nng_dialer_get] or
+xref:nng_listener_get.3.adoc[nng_listener_get] for specific dialers or listeners.
 
 === Forms
 
diff --git a/docs/man/nng_socket_set.3.adoc b/docs/man/nng_socket_set.3.adoc
index 0b6df4f9..aa5784f3 100644
--- a/docs/man/nng_socket_set.3.adoc
+++ b/docs/man/nng_socket_set.3.adoc
@@ -1,6 +1,6 @@
 = nng_socket_set(3)
 //
-// Copyright 2019 Staysail Systems, Inc. <info@staysail.tech>
+// Copyright 2020 Staysail Systems, Inc. <info@staysail.tech>
 // Copyright 2018 Capitar IT Group BV <info@capitar.com>
 //
 // This document is supplied under the terms of the MIT License, a
@@ -45,13 +45,17 @@ The actual options that may be configured in this way vary, and are
 specified by _opt_.
 A number of them are documented in xref:nng_options.5.adoc[nng_options(5)].
 
-Additionally some transport-specific and protocol-specific options are
-documented with the transports and protocols themselves.
+Protocol-specific options are documented with the protocol in question.
+
+IMPORTANT: Access to transport options via this function is deprecated, and may be
+removed from a future release.  Applications should instead make use of
+xref:nng_dialer_set.3.adoc[nng_dialer_get] or
+xref:nng_listener_set.3.adoc[nng_listener_get] for specific dialers or listeners.
 
 === Forms
 
 The details of the type, size, and semantics of the option will depend
-on the actual option, and will be documented with the option itself.
+on the actual option, and is documented with the option itself.
 
 `nng_socket_set()`::
 This function is untyped, and can be used to configure any arbitrary data.