1 files changed, 311 insertions, 0 deletions
diff --git a/docs/man/nng_options.5.adoc b/docs/man/nng_options.5.adoc
new file mode 100644
index 00000000..f07194d1
--- /dev/null
+++ b/docs/man/nng_options.5.adoc
@@ -0,0 +1,311 @@
+= nng_options(5)
+//
+// 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
+
+nng_options - socket, dialer, listener, and pipe options
+
+== SYNOPSIS
+
+[source, c]
+----
+#include <nng/nng.h>
+
+#define NNG_OPT_SOCKNAME   "socket-name"
+#define NNG_OPT_RAW        "raw"
+#define NNG_OPT_LINGER     "linger"
+#define NNG_OPT_RECVBUF    "recv-buffer"
+#define NNG_OPT_SENDBUF    "send-buffer"
+#define NNG_OPT_RECVFD     "recv-fd"
+#define NNG_OPT_SENDFD     "send-fd"
+#define NNG_OPT_RECVTIMEO  "recv-timeout"
+#define NNG_OPT_SENDTIMEO  "send-timeout"
+#define NNG_OPT_LOCADDR    "local-address"
+#define NNG_OPT_REMADDR    "remote-address"
+#define NNG_OPT_URL        "url"
+#define NNG_OPT_MAXTTL     "ttl-max"
+#define NNG_OPT_RECVMAXSZ  "recv-size-max"
+#define NNG_OPT_RECONNMINT "reconnect-time-min"
+#define NNG_OPT_RECONNMAXT "reconnect-time-max"
+----
+
+== DESCRIPTION
+
+This page documents the various standard options that can be set or
+retrieved on objects in the _nng_ library.
+
+Sockets (<<nng_socket.5#,`nng_socket`>> objects) use the functions
+<<nng_getopt.3#,`nng_getopt()`>>
+and <<nng_setopt.3#,`nng_setopt()`>> to set and retrieve option values.
+
+Dialers (<<nng_dialer.5#,`nng_dialer`>> objects) use the functions
+<<nng_dialer_getopt.3#,`nng_dialer_getopt()`>> and
+<<nng_dialer_setopt.3#,`nng_dialer_setopt()`>> to set and retrieve option
+values.
+
+Listeners (<<nng_listener.5#,`nng_listener`>> objects) use the functions
+<<nng_listener_getopt.3#,`nng_listener_getopt()`>>
+and <<nng_listener_setopt.3#,`nng_listener_setopt()`>> to set and
+retrieve option values.
+
+Pipes (<<nng_pipe.5#,`nng_pipe`>> objects) can only retrieve option values using
+the <<nng_pipe_getopt.3#,`nng_pipe_getopt()`>> function.
+
+In addition to the options listed here, transports and protocols will generally
+have some of their own options, which will be documented with the transport
+or protocol.
+
+=== Options
+
+In the following list of options, the name of the option is supplied,
+along with the data type of the underlying value.
+Some options are only meaningful or supported in certain contexts; for
+example there is no single meaningful address for a socket, since sockets
+can have multiple dialers and endpoints associated with them.
+An attempt has been made to include details about such restrictions in the
+description of the option.
+
+[[NNG_OPT_LINGER]]
+((`NNG_OPT_LINGER`))::
+(((lingering)))
+(`<<nng_duration.5#,nng_duration>>`)
+This is the linger time of the socket in milliseconds.
+When this value is non-zero, then the system will
+attempt to defer closing until it has undelivered data, or until the specified
+timeout has expired.
+
+NOTE: Not all transports support lingering, and
+so closing a socket or exiting the application can still result in the loss
+of undelivered messages.
+
+[[NNG_OPT_LOCADDR]]
+((`NNG_OPT_LOCADDR`))::
+(`<<nng_sockaddr.5#,nng_sockaddr>>`)
+This read-only option may be used on listeners, dialers and connected pipes, and
+represents the local address used for communication.
+Not all transports support this option, and some transports may support it
+listeners but not dialers.
+
+[[NNG_OPT_RAW]]
+((`NNG_OPT_RAW`))::
+(((raw mode)))
+(((cooked mode)))
+(`bool`)
+This option determines whether the socket is in "`raw`" mode.
+If `true`, the socket is in "`raw`" mode, and if `false` the socket is
+in "`cooked`" mode.
+Raw mode sockets generally do not have any protocol-specific semantics applied
+to them; instead the application is expected to perform such semantics itself.
+(For example, in "`cooked`" mode a <<nng_rep.7#,_rep_>> socket would
+automatically copy message headers from a received message to the corresponding
+reply, whereas in "`raw`" mode this is not done.)
+
+[[NNG_OPT_RECONNMINT]]
+((`NNG_OPT_RECONNMINT`))::
+(((reconnect time, minimum)))
+(`<<nng_duration.5#,nng_duration>>`)
+This is the minimum amount of time (milliseconds) to wait before attempting
+to establish a connection after a previous attempt has failed.
+This can be set on a socket, but it can also be overridden on an individual
+dialer.
+The option is irrelevant for listeners.
+
+[[NNG_OPT_RECONNMAXT]]
+((`NNG_OPT_RECONNMAXT`))::
+(((`NNG_OPT_RECONNMAXT`)))
+(((reconnect time, maximum)))
+(`<<nng_duration.5#,nng_duration>>`)
+This is the maximum amount of time
+(milliseconds) to wait before attempting to establish a connection after
+a previous attempt has failed.
+If this is non-zero, then the time between successive connection attempts
+will start at the value of `NNG_OPT_RECONNMINT`,
+and grow exponentially, until it reaches this value.
+If this value is zero, then no exponential
+backoff between connection attempts is done, and each attempt will wait
+the time specified by `NNG_OPT_RECONNMINT`.
+This can be set on a socket, but it can also be overridden on an individual
+dialer.
+The option is irrelevant for listeners.
+
+[[NNG_OPT_RECVBUF]]
+((`NNG_OPT_RECVBUF`))::
+(((buffer, receive)))
+(((receive, buffer)))
+(`int`)
+This is the depth of the socket's receive buffer as a number of messages.
+Messages received by a transport may be buffered until the application
+has accepted them for delivery.
+
+[[NNG_OPT_RECVFD]]
+((`NNG_OPT_RECVFD`))::
+(((poll)))
+(((select)))
+(((receive, polling)))
+(`int`)
+This read-only option is used to obtain an integer file descriptor suitable
+for use with
+http://pubs.opengroup.org/onlinepubs/7908799/xsh/poll.html[`poll()`],
+http://pubs.opengroup.org/onlinepubs/7908799/xsh/select.html[`select()`],
+(or on Windows systems
+https://msdn.microsoft.com/en-us/library/windows/desktop/ms741669(v=vs.85).aspx[`WSAPoll()`])
+and similar functions.
+This descriptor will be *readable* when a message is available for receiving
+on the socket.
+When no message is ready for receiving, then this file descriptor will *not*
+be readable.
+
+IMPORTANT: Appplications should never attempt to read or write to the
+returned file descriptor.
+Furthermore, applications should not attempt to use the actual socket (of
+type <<nng_socket.5#,`nng_socket`>>) with polling functions,
+since it is merely an internal
+identifier and will not necessarily referency any operting system object or
+handle.
+
+TIP: While this option may help applications integrate into existing polling
+loops, it is more efficient, and often easier, to use the asynchronous I/O
+objects instead.  See <<nng_aio_alloc.3#,`nng_aio_alloc()`>>.
+
+[[NNG_OPT_RECVMAXSZ]]
+((`NNG_OPT_RECVMAXSZ`))::
+(((receive, maximum size)))
+(`size_t`)
+This is the maximum message size that the will be accepted from a remote peer.
+If a peer attempts to send a message larger than this, then the message
+will be discarded.
+If the value of this is zero, then no limit on message sizes is enforced.
+This option exists to prevent certain kinds of denial-of-service attacks,
+where a malicious agent can claim to want to send an extraordinarily
+large message, without sending any data.
+This option can be set for the socket, but may be overridden for on a
+per-dialer or per-listener basis.
+
+NOTE: Some transports may have further message size restrictions!
+
+[[NNG_OPT_RECVTIMEO]]
+((`NNG_OPT_RECVTIMEO`))::
+(((receive, timeout)))
+(((timeout, receive)))
+(`<<nng_duration.5#,nng_duration>>`)
+This is the socket receive timeout in milliseconds.
+When no message is available for receiving at the socket for this period of
+time, receive operations will fail with a return value of `NNG_ETIMEDOUT`.
+
+[[NNG_OPT_REMADDR]]
+((`NNG_OPT_REMADDR`))::
+(`<<nng_sockaddr.5#,nng_sockaddr>>`)
+This read-only option may be used on dialers and connected pipes, and
+represents the address of a remote peer.
+Not all transports support this option.
+
+[[NNG_OPT_SENDBUF]]
+((`NNG_OPT_SENDBUF`))::
+(((send, buffer)))
+(((buffer, send)))
+(`int`)
+This is the depth of the socket send buffer as a number of messages.
+Messages sent by an application may be buffered by the socket until a
+transport is ready to accept them for delivery.
+This value must be an integer between 0 and 8192, inclusive.
+
+NOTE: Not all protocols support buffering sent messages;
+generally multicast protocols like <<nng_pub.7#,_pub_>> will
+simply discard messages when they cannot be delivered immediately.
+
+[[NNG_OPT_SENDFD]]
+((`NNG_OPT_SENDFD`))::
+(((poll)))
+(((select)))
+(((send, polling)))
+(`int`)
+This read-only option is used to obtain an integer file descriptor suitable
+for use with
+http://pubs.opengroup.org/onlinepubs/7908799/xsh/poll.html[`poll()`],
+http://pubs.opengroup.org/onlinepubs/7908799/xsh/select.html[`select()`],
+(or on Windows systems
+https://msdn.microsoft.com/en-us/library/windows/desktop/ms741669(v=vs.85).aspx[`WSAPoll()`])
+and similar functions.
+This descriptor will be *readable* when the socket is able to accept a
+message for sending without blocking.
+When the socket is no longer able to accept such messages without blocking,
+the descriptor will *not* be readable.
+
+IMPORTANT: Appplications should never attempt to read or write to the
+returned file descriptor.
+Furthermore, applications should not attempt to use the actual socket (of
+type <<nng_socket.5#,`nng_socket`>>) with polling functions,
+since it is merely an internal
+identifier and will not necessarily referency any operting system object or
+handle.
+
+TIP: While this option may help applications integrate into existing polling
+loops, it is more efficient, and often easier, to use the asynchronous I/O
+objects instead.  See <<nng_aio_alloc.3#,`nng_aio_alloc`()>>.
+
+[[NNG_OPT_SENDTIMEO]]
+((`NNG_OPT_SENDTIMEO`))::
+(((send, timeout)))
+(((timeout, send)))
+(`<<nng_duration.5#,nng_duration>>`)
+This is the socket send timeout in milliseconds.
+When a message cannot be queued for delivery by the socket for this period of
+time (such as if send buffers are full), the operation will fail with a
+return value of `NNG_ETIMEDOUT`.
+
+[[NNG_OPT_SOCKNAME]]
+((`NNG_OPT_SOCKNAME`))::
+(((name, socket)))
+(string)
+This the socket name.
+By default this is a string corresponding to the value of the socket.
+The string must fit within 64-bytes, including the terminating
+`NUL` byte, but it can be changed for other application uses.
+
+[[NNG_OPT_MAXTTL]]
+((`NNG_OPT_MAXTTL`))::
+(`int`)
+(((time-to-live)))
+This is the maximum number of "`hops`" a message may traverse (see
+<<nng_device.3#,`nng_device()`>>).
+The intention here is to prevent ((forwarding loops)) in device chains.
+When this is supported, it can have a value between 1 and 255, inclusive.
+
+NOTE: Not all protocols support this option.
+Those that do generally have a default value of 8.
+
+TIP: Each node along a forwarding path may have it's own value for the
+maximum time-to-live, and performs its own checks before forwarding a message.
+Therefore it is helpful if all nodes in the topology use the same value for
+this option.
+
+[[NNG_OPT_URL]]
+((`NNG_OPT_URL`))::
+(((URI)))
+(((URL)))
+(string)
+This read-only option is used to obtain the URL with which a listener
+or dialer was configured.
+Accordingly it can only be used with dialers, listeners, and pipes.
+
+NOTE: Some transports will canonify URLs before returning them to the
+application.
+
+== SEE ALSO
+
+<<nng_dialer_getopt.3#,nng_dialer_getopt(3)>>,
+<<nng_dialer_setopt.3#,nng_dialer_setopt(3)>>,
+<<nng_getopt.3#,nng_getopt(3)>>,
+<<nng_listener_getopt.3#,nng_listener_getopt(3)>>,
+<<nng_listener_setopt.3#,nng_listener_setopt(3)>>,
+<<nng_pipe_getopt.3#,nng_pipe_getopt(3)>>,
+<<nng_setopt.3#,nng_setopt(3)>>,
+<<nng.7#,nng(7)>>