finished proto open pages

1 files changed, 228 insertions, 0 deletions

diff --git a/docs/reference/src/compat/nn_getsockopt.3compat.adoc b/docs/reference/src/compat/nn_getsockopt.3compat.adoc
new file mode 100644
index 00000000..0c476cca
--- /dev/null
+++ b/docs/reference/src/compat/nn_getsockopt.3compat.adoc
@@ -0,0 +1,228 @@
+= nn_getsockopt(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_getsockopt - get socket option (compatible API)
+
+== SYNOPSIS
+
+[source,c]
+----
+#include <nanomsg/nn.h>
+
+int nn_getsockopt(int sock, int level, int option, void *val, size_t *szp);
+----
+
+== DESCRIPTION
+
+The `nn_getsockopt()` function gets a socket option on socket _sock_.
+The option retrieved is determined by the _level_ and _option_.
+
+NOTE: This function is provided for API
+xref:nng_compat.3compat.adoc[compatibility] with legacy _libnanomsg_.
+Consider using the relevant xref:libnng.3.adoc[modern API] instead.
+
+The value pointed to by _szp_ must be initialized to the size of the buffer
+pointed to by _val_.
+No more than this many bytes of the option will be copied into the destination
+buffer on success.
+On success, the value pointed to by _szp_ will be updated with the actual
+size of the option.
+
+TIP: To determine the size to receive an option, first call this function
+with _val_ set to `NULL` and the value addressed by _szp_ initialized to zero.
+
+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; accordingly this value is the queue depth multiplied by 1024
+(representing an estimate that the average message size is 1kB).
+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 (back-off), but the interval is
+capped by this value.
+If this value is smaller than `NN_RECONNECT_IVL`, then no exponential
+back-off is performed, and each reconnect interval will be determined
+solely by `NN_RECONNECT_IVL`.
+The default is zero.
+
+`NN_LINGER`::
+This option is always zero 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 number of times a message may traverse devices or proxies.
+This value, if positive, provides some protection against forwarding loops in
+xref:nng_device.3.adoc[device] chains.
+
+NOTE: Not all protocols offer this protection, so care should still be used
+in configuring device forwarding.
+
+`NN_DOMAIN`::
+This option of type `int` represents either the value `AF_SP` or `AF_SP_RAW`,
+corresponding to the value that the socket was created with.
+
+`NN_PROTOCOL`::
+This option option of type `int` contains the numeric protocol number
+that the socket is used with.
+
+`NN_RCVFD`::
+This option returns a file descriptor suitable for use in with `poll()` or
+`select()` (or other system-specific polling functions).
+This descriptor will be readable when a message is available for receiving
+at the socket.
+This option is of type `int` on all systems except Windows, where it is of
+type `SOCKET`.
+
+NOTE: The file descriptor should not be read or written by the application,
+and is not the same as any underlying descriptor used for network sockets.
+
+`NN_SNDFD`::
+This option returns a file descriptor suitable for use in with `poll()` or
+`select()` (or other system-specific polling functions).
+This descriptor will be readable when the socket is able to accept a message
+for sending.
+This option is of type `int` on all systems except Windows, where it is of
+type `SOCKET`.
+
+NOTE: The file descriptor should not be read or written by the application,
+and is not the same as any underlying descriptor used for network sockets.
+Furthermore, the file descriptor should only be polled for _readability_.
+
+The following option is available for `NN_REQ` sockets
+using the `NN_REQ` level:
+
+`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).
+
+The following option is available for `NN_SURVEYOR` sockets
+using the `NN_SURVEYOR` level:
+
+`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
+
+[.text-left]
+xref:nng_socket.5.adoc[nng_socket(5)],
+xref:nn_close.3compat.adoc[nn_close(3compat)],
+xref:nn_errno.3compat.adoc[nn_errno(3compat)],
+xref:nn_getsockopt.3compat.adoc[nn_getsockopt(3compat)],
+xref:nng_compat.3compat.adoc[nng_compat(3compat)],
+xref:nng.7.adoc[nng(7)]