From 2e6f76636e2adbc5e2bc4659a0639d83eb3f2d59 Mon Sep 17 00:00:00 2001
From: Garrett D'Amore <garrett@damore.org>
Date: Sat, 17 Mar 2018 17:21:43 -0700
Subject: fixes #287 remove NNG_OPT_DOMAIN, NNG_OPT_PROTOCOL, and
 NNG_OPT_TRANSPORT

While here we documented that certain options are not supported in the
compatibility layer.
---
 docs/man/nng_compat.3compat.adoc | 45 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 45 insertions(+)

(limited to 'docs/man/nng_compat.3compat.adoc')

diff --git a/docs/man/nng_compat.3compat.adoc b/docs/man/nng_compat.3compat.adoc
index cc6271f4..a0ac64c2 100644
--- a/docs/man/nng_compat.3compat.adoc
+++ b/docs/man/nng_compat.3compat.adoc
@@ -79,6 +79,51 @@ supplied here later.
 In the meantime it can be found online at the
 http://nanomsg.org[nanomsg site].
 
+There are a few caveats, that should be kept in mind.
+
+NOTE: Socket numbers can be quite large.
+The legacy _libnanomsg_ attempted to reuse socket numbers, like
+file descriptors in UNIX systems.
+The _nng_ library avoids this to prevent accidental reuse or
+collision after a descriptor is closed.
+Consequently, socket numbers can become quite large, and should
+probably not be used for array indices.
+
+NOTE: The following options (`nn_getsockopt`) are unsupported:
+`NN_PROTOCOL`, `NN_SNDPRIO`, `NN_RCVPRIO`, `NN_IPV4ONLY`.
+Some of these will probably be added back in the future when
+the relevant support is added to _nng_.
+
+NOTE: Statistics (`nn_get_statistic`) are unsupported.
+The plan is to support statistics in the native _nng_ API, but
+we think there is no need for this in a compatibility layer.
+Hence, this function returns `ENOTSUP`.
+
+NOTE: Some transports can support longer URLs than legacy _libnanomsg_ can.
+It is a good idea to use short pathnames in URLs if interoperability
+is a concern.
+
+NOTE: Some transports are unusable from this mode.
+In particular, this legacy API offers no way to configure
+TLS parameters that are required for use.
+
+NOTE: ABI versioning is not supported.
+We don't offer the `NN_VERSION_` macros.  Sorry.
+
+NOTE: Runtime symbol information is not implemented.
+Specifically, there is no `nn_symbol()` function yet.
+(This may be addressed later if there is a need.)
+
+IMPORTANT: The `nn_term()` function is destructive and should be avoided.
+This function closes down all sockets, and really there is no good
+reason to ever use it.
+Removal from existing code is advised.
+(Keep track of sockets and close them explicitly if necessary.)
+
+IMPORTANT: It *is* possible at present to intermix sockets between the new and
+the old APIs, but this is not a guaranteed feature, and should only
+be used temporarily to facilitate transitioning code to the new APIs.
+
 // === Common Functions
 //
 // The following common functions exist in _libnng_.
-- 
cgit v1.2.3-70-g09d2

