fixes #303 Flesh out compatible API docs

1 files changed, 202 insertions, 0 deletions

diff --git a/docs/man/nn_setsockopt.3compat.adoc b/docs/man/nn_setsockopt.3compat.adoc
new file mode 100644
index 00000000..af4539b5
--- /dev/null
+++ b/docs/man/nn_setsockopt.3compat.adoc
@@ -0,0 +1,202 @@
+= nn_setsockopt(3compat)
+//
+// Copyright 2018 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
+// copy of which should be located in the distribution where this
+// file was obtained (LICENSE.txt).  A copy of the license may also be
+// found online at https://opensource.org/licenses/MIT.
+//
+
+== NAME
+
+nn_setsockopt - set socket option (compatible API)
+
+== SYNOPSIS
+
+[source,c]
+----
+#include <nanomsg/nn.h>
+
+int nn_setsockopt(int sock, int level, int option, const void *val, size_t sz);
+----
+
+== DESCRIPTION
+
+The `nn_setsockopt()` function sets a socket option on socket _sock_,
+affecting the behavior of the socket.
+The option set is determined by the _level_ and _option_.
+The value of the option is set by _val_, and _sz_, which are pointers to
+the actual value and the size of the value, respectively.
+
+NOTE: This function is provided for API
+<<nng_compat.3compat#,compatibility>> with legacy _libnanomsg_.
+Consider using the relevant <<libnng.3#,modern API>> instead.
+
+The _level_ determines whether the option is a generic socket option,
+or is transport-specific.
+The values possible for level are as follows:
+
+[horizontal]
+`NN_SOL_SOCKET`:: Generic socket option
+`NN_IPC`:: Transport specific option for IPC.
+`NN_TCP`:: Transport specific option for TCP.
+`NN_WS`:: Transport specific option for WebSocket.
+
+The following generic socket options are possible (all are of type `int` and
+thus size 4, unless otherwise indicated.)
+
+`NN_SNDBUF`::
+Send buffer size in bytes.
+
+NOTE: In _nng_ buffers are sized as a count of messages rather than
+bytes, and so an attempt to estimate a conversion based upon a predetermined
+message size of 1kB is made.
+The value supplied is rouned up to the nearest value divisible by 1024, and
+then divided by 1024 to convert to a message count.
+Applications that have unusual message sizes may wish to adjust the value
+used here accordingly.
+
+`NN_RCVBUF`::
+Receive buffer size in bytes.
+
+NOTE: The same caveats for `NN_SNDBUF` apply here as well.
+
+`NN_SNDTIMEO`::
+Send time-out in milliseconds.
+Send operations will fail with `ETIMEDOUT` if no message can be received
+after this many milliseconds have transpired since the operation was started.
+A value of -1 means that no timeout is applied.
+
+`NN_RCVTIMEO`::
+Receive time-out in milliseconds.
+Receive operations will fail with `ETIMEDOUT` if no message can be received
+after this many milliseconds have transpired since the operation was started.
+A value of -1 means that no timeout is applied.
+
+`NN_RCVMAXSIZE`::
+Maximum receive size in bytes.
+The socket will discard messages larger than this on receive.
+The default, 1MB, is intended to prevent denial-of-service attacks.
+The value -1 removes any limit.
+
+`NN_RECONNECT_IVL`::
+Reconnect interval in milliseconds.
+After an outgoing connection is closed or fails, the socket will
+automatically attempt to reconnect after this many milliseconds.
+This is the starting value for the time, and is used in the first
+reconnection attempt after a successful connection is made.
+The default is 100.
+
+`NN_RECONNECT_IVL_MAX`::
+Maximum reconnect interval in milliseconds.
+Subsequent reconnection attempts after a failed attempt are made at
+exponentially increasing intervals (backoff), but the interval is
+capped by this value.
+If this value is smaller than `NN_RECONNECT_IVL`, then no exponential
+backoff is performed, and each reconnect interval will be determined
+solely by `NN_RECONNECT_IVL`.
+The default is zero.
+
+`NN_LINGER`::
+This option is ignored, and exists only for compatibility.
+
+NOTE: This option was unreliable in early releases of _libnanomsg_, and
+is unsupported in _nng_ and recent _libnanomsg_ releases.
+Applications needing assurance of message delivery should either include an
+explicit notification (automatic with the `NN_REQ` protocol) or allow
+sufficient time for the socket to drain before closing the socket or exiting.
+
+`NN_SNDPRIO`:: 
+This option is not implemented at this time.
+
+`NN_RCVPRIO`::
+This option is not implemented at this time.
+
+`NN_IPV4ONLY`::
+This option is not implemented at this time.
+
+`NN_SOCKET_NAME`::
+This option is a string, and represents the socket name.
+It can be changed to help with identifying different sockets with
+their different application-specific purposes.
+
+`NN_MAXTTL`::
+Maximum "`hops`" through proxies and devices a message may go through.
+This value, if positive, provides some protection against forwarding loops in
+<<nng_device.3#,device>> chains.
+
+NOTE: Not all protocols offer this protection, so care should still be used
+in configuring device forwarding.
+
+// NN_DOMAIN is readonly.
+// NN_PROTOCOL is not supported.
+// NN_RCVFD is read-only.
+// NN_SNDFD is read-only.
+
+`NN_REQ_RESEND_IVL`::
+Request retry interval in milliseconds.
+If an `NN_REQ` socket does not receive a reply to a request within this
+period of time, the socket will automatically resend the request.
+The default value is 60000 (one minute).
+
+`NN_SUB_SUBSCRIBE`::
+Subscription topic, for `NN_SUB` sockets.
+This sets a subscription topic.
+When a message from a publisher arrives, it is compared against all
+subscriptions.
+If the first _sz_ bytes of the message are not identical to _val_,
+then the message is silently discarded.
+
+TIP: To receive all messages, subscribe to an empty topic (_sz_ equal to zero).
+
+`NN_SUB_UNSUBSCRIBE`::
+Removes a subscription topic that was earlier established.
+
+`NN_SURVEYOR_DEADLINE`::
+Survey deadline in milliseconds for `NN_SURVEYOR` sockets.
+After sending a survey message, the socket will only accept responses
+from respondents for this long.
+Any responses arriving after this expires are silently discarded.
+
+In addition, the following transport specific options are offered:
+
+`NN_IPC_SEC_ATTR`::
+This `NN_IPC` option is not supported at this time.
+
+`NN_IPC_OUTBUFSZ`::
+This `NN_IPC` option is not supported at this time.
+
+`NN_IPC_INBUFSZE`::
+This `NN_IPC` option is not supported at this time.
+
+`NN_TCP_NODELAY`::
+This `NN_TCP` option is not supported at this time.
+
+`NN_WS_MSG_TYPE`::
+This `NN_WS` option is not supported, as _nng_ only supports binary messages
+in this implementation.
+
+== RETURN VALUES
+
+This function returns zero on success, and -1 on failure.
+
+== ERRORS
+
+[horizontal]
+`EBADF`:: The socket _sock_ is not an open socket.
+`ENOMEM`:: Insufficient memory is available.
+`ENOPROTOOPT`:: The level and/or option is invalid.
+`EINVAL`:: The option, or the value passed, is invalid.
+`ETERM`:: The library is shutting down.
+`EACCES`:: The option cannot be changed.
+
+== SEE ALSO
+
+<<nng_socket.5#,nng_socket(5)>>,
+<<nn_close.3compat#,nn_close(3compat)>>,
+<<nn_errno.3compat#,nn_errno(3compat)>>,
+<<nn_getsockopt.3compat#,nn_getsockopt(3compat)>>,
+<<nng_compat.3compat#,nng_compat(3compat)>>,
+<<nng.7#,nng(7)>>