fixes #845 TCP public API doc updates

15 files changed, 495 insertions, 267 deletions

diff --git a/docs/man/CMakeLists.txt b/docs/man/CMakeLists.txt
index db4e797e..ecdbf1e2 100644
--- a/docs/man/CMakeLists.txt
+++ b/docs/man/CMakeLists.txt
@@ -1,6 +1,7 @@
 #
 # Copyright 2018 Capitar IT Group BV <info@capitar.com>
 # Copyright 2018 Staysail Systems, Inc. <info@staysail.tech>
+# Copyright 2019 Devolutions <info@devolutions.net>
 #
 # This software is supplied under the terms of the MIT License, a
 # copy of which should be located in the distribution where this
@@ -293,21 +294,23 @@ if (NNG_ENABLE_DOC)
 	set(NNG_MAN3TCP
 	nng_tcp_close
 	nng_tcp_free
+	nng_tcp_getopt
 	nng_tcp_dialer_alloc
 	nng_tcp_dialer_close
 	nng_tcp_dialer_dial
 	nng_tcp_dialer_free
+	nng_tcp_dialer_getopt
+	nng_tcp_dialer_setopt
 	nng_tcp_listener_accept
 	nng_tcp_listener_alloc
 	nng_tcp_listener_close
 	nng_tcp_listener_free
+	nng_tcp_listener_getopt
 	nng_tcp_listener_listen
-	nng_tcp_peername
+	nng_tcp_listener_setopt
 	nng_tcp_recv
 	nng_tcp_send
-	nng_tcp_set_keepalive
-	nng_tcp_set_nodelay
-	nng_tcp_sockname
+	nng_tcp_setopt
 	)
 
     set(NNG_MAN3TLS
diff --git a/docs/man/libnng.3.adoc b/docs/man/libnng.3.adoc
index 5d5f5ef0..354b4b50 100644
--- a/docs/man/libnng.3.adoc
+++ b/docs/man/libnng.3.adoc
@@ -1,7 +1,8 @@
 = libnng(3)
 //
-// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech>
+// Copyright 2019 Staysail Systems, Inc. <info@staysail.tech>
 // Copyright 2018 Capitar IT Group BV <info@capitar.com>
+// Copyright 2019 Devolutions <info@devolutions.net>
 //
 // This document is supplied under the terms of the MIT License, a
 // copy of which should be located in the distribution where this
@@ -281,6 +282,9 @@ as a convenience to aid in creating portable applications.
 
 === Supplemental TCP
 
+These TCP functions are available for use with direct TCP access.
+Most applications won't need to use these.
+
 |===
 |<<nng_tcp_close.3tcp#,nng_tcp_close()>>|close TCP connection
 |<<nng_tcp_dialer_alloc.3tcp#,nng_tcp_dialer_alloc()>>|allocate TCP dialer
@@ -288,6 +292,7 @@ as a convenience to aid in creating portable applications.
 |<<nng_tcp_dialer_dial.3tcp#,nng_tcp_dialer_dial()>>|initiate outgoing TCP connection
 |<<nng_tcp_dialer_free.3tcp#,nng_tcp_dialer_free()>>|free TCP dialer
 |<<nng_tcp_free.3tcp#,nng_tcp_free()>>|free TCP connection
+|<<nng_tcp_getopt.3tcp#,nng_tcp_getopt()>>|get option from TCP connection
 |<<nng_tcp_listener_accept.3tcp#,nng_tcp_listener_accept()>>|accept incoming TCP connection
 |<<nng_tcp_listener_alloc.3tcp#,nng_tcp_listener_alloc()>>|allocate TCP listener
 |<<nng_tcp_listener_close.3tcp#,nng_tcp_listener_close()>>|close TCP listener
@@ -297,12 +302,10 @@ as a convenience to aid in creating portable applications.
 |<<nng_tcp_recv.3tcp#,nng_tcp_recv()>>|receive from TCP connection
 |<<nng_tcp_send.3tcp#,nng_tcp_send()>>|send to TCP connection
 |<<nng_tcp_sockname.3tcp#,nng_tcp_sockname()>>|get TCP local socket address
-|<<nng_tcp_set_keepalive.3tcp#,nng_tcp_set_keepalive()>>|enable or disable TCP keepalives
-|<<nng_tcp_set_nodelay.3tcp#,nng_tcp_set_nodelay()>>|disable Nagle's algorithm
+|<<nng_tcp_setopt.3tcp#,nng_tcp_setopt()>>|set option on TCP connection
+|===
 
-|
 
-|===
 === HTTP Support
 
 The library may be configured with support for HTTP, and this will
diff --git a/docs/man/nng_options.5.adoc b/docs/man/nng_options.5.adoc
index 2887719a..a1d19b5f 100644
--- a/docs/man/nng_options.5.adoc
+++ b/docs/man/nng_options.5.adoc
@@ -1,7 +1,8 @@
 = nng_options(5)
 //
-// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech>
+// Copyright 2019 Staysail Systems, Inc. <info@staysail.tech>
 // Copyright 2018 Capitar IT Group BV <info@capitar.com>
+// Copyright 2019 Devolutions <info@devolutions.net>
 //
 // This document is supplied under the terms of the MIT License, a
 // copy of which should be located in the distribution where this
@@ -47,22 +48,24 @@ nng_options - socket, dialer, listener, and pipe options
 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.
+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
+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
+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.
+Pipes (<<nng_pipe.5#,`nng_pipe`>> objects) can only retrieve option values using
+the <<nng_pipe_getopt.3#,`nng_pipe_getopt()`>> function.
+
+Other object types may have additional methods to access these options.
 
 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
@@ -80,11 +83,17 @@ description of the option.
 
 [[NNG_OPT_LOCADDR]]
 ((`NNG_OPT_LOCADDR`))::
-(`<<nng_sockaddr.5#,nng_sockaddr>>`)
+(<<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
++
+NOTE: Not all transports support this option, and some transports may support it on
 listeners but not dialers.
++
+When used on a TCP dialer, this option is used to configure the source IP
+address that will be used when initiating outgoing connections.
+The specific port number will be ignored, however, and the system will
+choose a random ephemeral port instead.
 
 [[NNG_OPT_RAW]]
 ((`NNG_OPT_RAW`))::
@@ -94,6 +103,7 @@ listeners but not dialers.
 This read-only option indicates 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
@@ -104,7 +114,7 @@ See <<nng.7#raw_mode,Raw Mode>> for more details.
 [[NNG_OPT_RECONNMINT]]
 ((`NNG_OPT_RECONNMINT`))::
 (((reconnect time, minimum)))
-(`<<nng_duration.5#,nng_duration>>`)
+(<<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
@@ -115,7 +125,7 @@ The option is irrelevant for listeners.
 ((`NNG_OPT_RECONNMAXT`))::
 (((`NNG_OPT_RECONNMAXT`)))
 (((reconnect time, maximum)))
-(`<<nng_duration.5#,nng_duration>>`)
+(<<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.
@@ -155,14 +165,14 @@ 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: Applications should never attempt to read or write to the
 returned file descriptor.
-
++
 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()>>`.
+See <<nng_aio_alloc.3#,`nng_aio_alloc()`>>.
 
 [[NNG_OPT_RECVMAXSZ]]
 ((`NNG_OPT_RECVMAXSZ`))::
@@ -177,21 +187,21 @@ 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!
++
+NOTE: Some transports may have further message size restrictions.
 
 [[NNG_OPT_RECVTIMEO]]
 ((`NNG_OPT_RECVTIMEO`))::
 (((receive, timeout)))
 (((timeout, receive)))
-(`<<nng_duration.5#,nng_duration>>`)
+(<<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>>`)
+(<<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.
@@ -205,7 +215,7 @@ 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.
@@ -223,24 +233,25 @@ 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: Applications should never attempt to read or write to the
-returned file descriptor.
-
+returned file descriptor; use should be limited to polling system calls only.
++
 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()>>`.
+See <<nng_aio_alloc.3#,`nng_aio_alloc()`>>.
 
 [[NNG_OPT_SENDTIMEO]]
 ((`NNG_OPT_SENDTIMEO`))::
 (((send, timeout)))
 (((timeout, send)))
-(`<<nng_duration.5#,nng_duration>>`)
+(<<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
@@ -253,20 +264,22 @@ return value of `NNG_ETIMEDOUT`.
 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.
+`NUL` byte.
+The value is intended for application use, and is not used for anything
+in the library itself.
 
 [[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()>>`).
+This is the maximum number of "`hops`" a message may traverse across
+a <<nng_device.3#,`nng_device()`>> forwarders.
 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 its 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
@@ -280,7 +293,7 @@ this option.
 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.
 
@@ -295,7 +308,6 @@ This read-only option is used to obtain the 16-bit number for the socket's proto
 This read-only option is used to obtain the 16-bit number of the
 peer protocol for the socket.
 
-
 [[NNG_OPT_PROTONAME]]
 ((`NNG_OPT_PROTONAME`))::
 (string)
@@ -310,17 +322,22 @@ the socket.
 [[NNG_OPT_TCP_NODELAY]]
 ((`NNG_OPT_TCP_NODELAY`))::
 (`bool`)
-This option is used to disable (or enable) the use of Nagle's algorithm
+This option is used to disable (or enable) the use of ((Nagle's algorithm))
 for TCP connections.
++
+NOTE: This setting may apply to transports that are built on top of TCP.
+See the transport documentation for each transport for details.
++
 When `true` (the default), messages are sent immediately by the underlying
 TCP stream without waiting to gather more data.
++
 When `false`, Nagle's algorithm is enabled, and the TCP stream may
 wait briefly in attempt to coalesce messages.
 Nagle's algorithm is useful on low-bandwidth connections to reduce overhead,
 but it comes at a cost to latency.
-
-NOTE: This setting may apply to transports that are built on top of TCP.
-See the transport documentation for each transport for details.
++
+When used on a dialer or a listener, the value affects how newly
+created connections will be configured.
 
 [[NNG_OPT_TCP_KEEPALIVE]]
 ((`NNG_OPT_TCP_KEEPALIVE`))::
@@ -328,15 +345,19 @@ See the transport documentation for each transport for details.
 This option is used to enable the sending of keep-alive messages on
 the underlying TCP stream.
 This option is `false` by default.
++
+NOTE: This setting may apply to transports that are built on top of TCP.
+See the transport documentation for each transport for details.
++
 When enabled, if no messages are seen for a period of time, then
 a zero length TCP message is sent with the ACK flag set in an attempt
 to tickle some traffic from the peer.
 If none is still seen (after some platform-specific number of retries and
 timeouts), then the remote peer is presumed dead, and the connection is closed.
-
-NOTE: This setting may apply to transports that are built on top of TCP.
-See the transport documentation for each transport for details.
-
++
+When used on a dialer or a listener, the value affects how newly
+created connections will be configured.
++
 TIP: This option has two purposes.
 First, it can be used to detect dead peers on an otherwise quiescent network.
 Second, it can be used to keep connection table entries in NAT and other
diff --git a/docs/man/nng_tcp.5.adoc b/docs/man/nng_tcp.5.adoc
index 10a3c2f3..7bf0a82f 100644
--- a/docs/man/nng_tcp.5.adoc
+++ b/docs/man/nng_tcp.5.adoc
@@ -2,6 +2,7 @@
 //
 // Copyright 2018 Staysail Systems, Inc. <info@staysail.tech>
 // Copyright 2018 Capitar IT Group BV <info@capitar.com>
+// Copyright 2019 Devolutions <info@devolutions.net>
 //
 // This document is supplied under the terms of the MIT License, a
 // copy of which should be located in the distribution where this
@@ -33,24 +34,37 @@ should not be confused with a pipe object created using the
 <<nng_tcp.7#,nng_tcp(7)>> transport.
 
 TIP: Most NNG applications should not use this, but instead use the
-`<<nng_tcp.7#,nng_tcp>>` transport instead.
+<<nng_tcp.7#,nng_tcp(7)>> transport instead.
 
 These objects are created either establishing an outgoing connection
-with `<<nng_tcp_dialer_dial.3tcp#,nng_tcp_dialer_dial()>>` or by
+with <<nng_tcp_dialer_dial.3tcp#,`nng_tcp_dialer_dial()`>> or by
 accepting in incoming connection with
-`<<nng_tcp_listener_accept.3tcp#,nng_tcp_listener_accept()>>`.
+<<nng_tcp_listener_accept.3tcp#,`nng_tcp_listener_accept()`>>.
 
 TCP connections are byte streams, and are "`reliable`" in that data
 will not be delivered out of order, or with portions missing.
 
-Data can be sent using `<<nng_tcp_send.3tcp#,nng_tcp_send()>>` or
-received with `<<nng_tcp_recv.3tcp#,nng_tcp_recv()>>`.
+Data can be sent using <<nng_tcp_send.3tcp#,`nng_tcp_send()`>> or
+received with <<nng_tcp_recv.3tcp#,`nng_tcp_recv()`>>.
 
 When the connection is no longer needed, it should be freed with
-`<<nng_tcp_free.3tcp#,nng_tcp_free()>>`.
+<<nng_tcp_free.3tcp#,`nng_tcp_free()`>>.
 
 TIP: It is possible to close the connection, without freeing it, by
-using `<<nng_tcp_close.3tcp#,nng_tcp_close()>>`.
+using <<nng_tcp_close.3tcp#,`nng_tcp_close()`>>.
+
+=== Options
+
+The following options are applicable to TCP connections, and may be
+accessed using the <<nng_tcp_getopt.3tcp#,`nng_tcp_getopt()`>> and
+<<nng_tcp_setopt.3tcp#,`nng_tcp_setopt()`>> functions.
+
+* <<nng_options.5#NNG_OPT_LOCADDR,`NNG_OPT_LOCADDR`>>
+* <<nng_options.5#NNG_OPT_REMADDR,`NNG_OPT_REMADDR`>>
+* <<nng_options.5#NNG_OPT_TCP_KEEPALIVE,`NNG_OPT_TCP_KEEPALIVE`>>
+* <<nng_options.5#NNG_OPT_TCP_NO_DELAY,`NNG_OPT_TCP_NODELAY`>>
+
+Other platform specific options may be available as well.
 
 == SEE ALSO
 
@@ -59,11 +73,9 @@ using `<<nng_tcp_close.3tcp#,nng_tcp_close()>>`.
 <<nng_tcp_close.3tcp#,nng_tcp_close(3tcp)>>,
 <<nng_tcp_dialer_dial.3tcp#,nng_tcp_dialer_dial(3tcp)>>,
 <<nng_tcp_free.3tcp#,nng_tcp_free(3tcp)>>,
+<<nng_tcp_getopt.3tcp#,nng_tcp_getopt(3tcp)>>,
 <<nng_tcp_listener_accept.3tcp#,nng_tcp_listener_accept(3tcp)>>,
-<<nng_tcp_peername.3tcp#,nng_tcp_peername(3tcp)>>,
 <<nng_tcp_recv.3tcp#,nng_tcp_recv(3tcp)>>,
 <<nng_tcp_send.3tcp#,nng_tcp_send(3tcp)>>,
-<<nng_tcp_sockname.3tcp#,nng_tcp_sockname(3tcp)>>,
-<<nng_tcp_set_keepalive.3tcp#,nng_tcp_set_keepalive(3tcp)>>,
-<<nng_tcp_set_nodelay.3tcp#,nng_tcp_set_nodelay(3tcp)>>,
+<<nng_tcp_setopt.3tcp#,nng_tcp_setopt(3tcp)>>,
 <<nng.7#,nng(7)>>
diff --git a/docs/man/nng_tcp_dialer_getopt.3tcp.adoc b/docs/man/nng_tcp_dialer_getopt.3tcp.adoc
new file mode 100644
index 00000000..dca43ade
--- /dev/null
+++ b/docs/man/nng_tcp_dialer_getopt.3tcp.adoc
@@ -0,0 +1,67 @@
+= nng_tcp_dialer_getopt(3tcp)
+//
+// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech>
+// Copyright 2018 Capitar IT Group BV <info@capitar.com>
+// Copyright 2019 Devolutions <info@devolutions.net>
+//
+// 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_tcp_dialer_getopt - get option from TCP dialer
+
+== SYNOPSIS
+
+[source, c]
+----
+#include <nng/nng.h>
+#include <nng/supplemental/tcp/tcp.h>
+
+int nng_tcp_getopt(nng_tcp_dialer *d, const char *name, void *data, size_t *sizep);
+----
+
+== DESCRIPTION
+
+The `nng_tcp_dialer_getopt()` is used to retrieve the value of the option _name_ for the <<nng_tcp_dialer.5#,TCP dialer>> _d_.
+The size of the buffer located at _data_ to receive the copy is passed by the
+caller at the location referenced by _sizep_.
+If this size is sufficient to hold the entire object, the object is copied into
+the buffer specified by _data_.
+In either event, the size of the source object (the amount of data copied,
+or that would have been copied if sufficient space were available) is stored
+at the location of _sizep_.
+
+=== Options
+
+The options specifically suppported for retrieval from TCP dialers are:
+
+* <<nng_options.5#NNG_OPT_LOCADDR,`NNG_OPT_LOCADDR`>>
+* <<nng_options.5#NNG_OPT_TCP_KEEPALIVE,`NNG_OPT_TCP_KEEPALIVE`>>
+* <<nng_options.5#NNG_OPT_TCP_NODELAY,`NNG_OPT_TCP_NODELAY`>>
+
+== RETURN VALUES
+
+This function returns 0 on success, and non-zero otherwise.
+
+== ERRORS
+
+[horizontal]
+`NNG_ECLOSED`:: The dialer is closed.
+`NNG_EINVAL`:: There was insufficient space to receive the object.
+	The amount of data actually needed is returned in _sizep_.
+`NNG_ENOTSUP`:: The option _name_ is not supported.
+`NNG_EWRITEONLY`:: The option _name_ may not read.
+
+== SEE ALSO
+
+[.text-left]
+<<nng_tcp_dialer_setopt.3tcp#,nng_tcp_dialer_setopt(3tcp)>>,
+<<nng_tcp_getopt.3tcp#,nng_tcp_getopt(3tcp)>>,
+<<nng_options.5#,nng_options(5)>>,
+<<nng_strerror.3#,nng_strerror(3)>>,
+<<nng_tcp.5#,nng_tcp(5)>>,
+<<nng_tcp_dialer.5#,nng_tcp_dialer(5)>>
diff --git a/docs/man/nng_tcp_dialer_setopt.3tcp.adoc b/docs/man/nng_tcp_dialer_setopt.3tcp.adoc
new file mode 100644
index 00000000..567291a7
--- /dev/null
+++ b/docs/man/nng_tcp_dialer_setopt.3tcp.adoc
@@ -0,0 +1,62 @@
+= nng_tcp_dialer_setopt(3tcp)
+//
+// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech>
+// Copyright 2018 Capitar IT Group BV <info@capitar.com>
+// Copyright 2019 Devolutions <info@devolutions.net>
+//
+// 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_tcp_dialer_setopt - set option on TCP dialer
+
+== SYNOPSIS
+
+[source, c]
+----
+#include <nng/nng.h>
+#include <nng/supplemental/tcp/tcp.h>
+
+int nng_tcp_dialer_setopt(nng_tcp_dialer *d, const char *name, const void *data, size_t size);
+----
+
+== DESCRIPTION
+
+The `nng_tcp_dialer_setopt()` is used to set the option _name_ for the
+<<nng_tcp_dialer.5#,TCP dialer>> _d_.
+The value to set is copied from _data_, which should be _size_ bytes
+in length.
+
+=== Options
+
+The options specifically suppported for modification on TCP dialers are:
+
+* <<nng_options.5#NNG_OPT_TCP_LOCADDR,`NNG_OPT_LOCADDR`>>
+* <<nng_options.5#NNG_OPT_TCP_KEEPALIVE,`NNG_OPT_TCP_KEEPALIVE`>>
+* <<nng_options.5#NNG_OPT_TCP_NODELAY,`NNG_OPT_TCP_NODELAY`>>
+
+== RETURN VALUES
+
+This function returns 0 on success, and non-zero otherwise.
+
+== ERRORS
+
+[horizontal]
+`NNG_ECLOSED`:: The dialer is closed.
+`NNG_EINVAL`:: Either _data_ or _size_ are invalid.
+`NNG_ENOTSUP`:: The option _name_ is not supported.
+`NNG_EREADONLY`:: The option _name_ may not be modified.
+
+== SEE ALSO
+
+[.text-left]
+<<nng_tcp_dialer_getopt.3tcp#,nng_tcp_dialer_getopt(3tcp)>>,
+<<nng_tcp_setopt.3tcp#,nng_tcp_setopt(3tcp)>>,
+<<nng_options.5#,nng_options(5)>>,
+<<nng_strerror.3#,nng_strerror(3)>>,
+<<nng_tcp.5#,nng_tcp(5)>>,
+<<nng_tcp_dialer.5#,nng_tcp_dialer(5)>>
diff --git a/docs/man/nng_tcp_getopt.3tcp.adoc b/docs/man/nng_tcp_getopt.3tcp.adoc
new file mode 100644
index 00000000..db08598b
--- /dev/null
+++ b/docs/man/nng_tcp_getopt.3tcp.adoc
@@ -0,0 +1,67 @@
+= nng_tcp_getopt(3tcp)
+//
+// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech>
+// Copyright 2018 Capitar IT Group BV <info@capitar.com>
+// Copyright 2019 Devolutions <info@devolutions.net>
+//
+// 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_tcp_getopt - get option from TCP connection
+
+== SYNOPSIS
+
+[source, c]
+----
+#include <nng/nng.h>
+#include <nng/supplemental/tcp/tcp.h>
+
+int nng_tcp_getopt(nng_tcp *conn, const char *name, void *data, size_t *sizep);
+----
+
+== DESCRIPTION
+
+The `nng_tcp_getopt()` is used to retrieve the value of the option _name_ for
+the <<nng_tcp.5#,TCP connection>> _conn_.
+The size of the buffer located at _data_ to receive the copy is passed by the
+caller at the location referenced by _sizep_.
+If this size is sufficient to hold the entire object, the object is copied into
+the buffer specified by _data_.
+In either event, the size of the source object (the amount of data copied,
+or that would have been copied if sufficient space were available) is stored
+at the location of _sizep_.
+
+=== Options
+
+The options specifically suppported for retrieval from TCP connections are:
+
+* <<nng_options.5#NNG_OPT_LOCADDR,`NNG_OPT_LOCADDR`>>
+* <<nng_options.5#NNG_OPT_REMADDR,`NNG_OPT_REMADDR`>>
+* <<nng_options.5#NNG_OPT_TCP_KEEPALIVE,`NNG_OPT_TCP_KEEPALIVE`>>
+* <<nng_options.5#NNG_OPT_TCP_NODELAY,`NNG_OPT_TCP_NODELAY`>>
+
+== RETURN VALUES
+
+This function returns 0 on success, and non-zero otherwise.
+
+== ERRORS
+
+[horizontal]
+`NNG_ECLOSED`:: The connection _conn_ is closed.
+`NNG_EINVAL`:: There was insufficient space to receive the object.
+	The amount of data actually needed is returned in _sizep_.
+`NNG_ENOTSUP`:: The option _name_ is not supported.
+`NNG_EWRITEONLY`:: The option _name_ may not read.
+
+== SEE ALSO
+
+[.text-left]
+<<nng_tcp_setopt.3tcp#,nng_tcp_setopt(3tcp)>>,
+<<nng_options.5#,nng_options(5)>>,
+<<nng_strerror.3#,nng_strerror(3)>>,
+<<nng_tcp.5#,nng_tcp(5)>>
diff --git a/docs/man/nng_tcp_listener_getopt.3tcp.adoc b/docs/man/nng_tcp_listener_getopt.3tcp.adoc
new file mode 100644
index 00000000..8f39c8bd
--- /dev/null
+++ b/docs/man/nng_tcp_listener_getopt.3tcp.adoc
@@ -0,0 +1,67 @@
+= nng_tcp_listener_getopt(3tcp)
+//
+// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech>
+// Copyright 2018 Capitar IT Group BV <info@capitar.com>
+// Copyright 2019 Devolutions <info@devolutions.net>
+//
+// 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_tcp_listener_getopt - get option from TCP listener
+
+== SYNOPSIS
+
+[source, c]
+----
+#include <nng/nng.h>
+#include <nng/supplemental/tcp/tcp.h>
+
+int nng_tcp_listener_getopt(nng_tcp_listener *l, const char *name, void *data, size_t *sizep);
+----
+
+== DESCRIPTION
+
+The `nng_tcp_listener_getopt()` is used to retrieve the value of the option _name_ for the <<nng_tcp_listener.5#,TCP listener>> _l_.
+The size of the buffer located at _data_ to receive the copy is passed by the
+caller at the location referenced by _sizep_.
+If this size is sufficient to hold the entire object, the object is copied into
+the buffer specified by _data_.
+In either event, the size of the source object (the amount of data copied,
+or that would have been copied if sufficient space were available) is stored
+at the location of _sizep_.
+
+=== Options
+
+The options specifically suppported for retrieval from TCP listeners are:
+
+* <<nng_options.5#NNG_OPT_LOCADDR,`NNG_OPT_LOCADDR`>>
+* <<nng_options.5#NNG_OPT_TCP_KEEPALIVE,`NNG_OPT_TCP_KEEPALIVE`>>
+* <<nng_options.5#NNG_OPT_TCP_NODELAY,`NNG_OPT_TCP_NODELAY`>>
+
+== RETURN VALUES
+
+This function returns 0 on success, and non-zero otherwise.
+
+== ERRORS
+
+[horizontal]
+`NNG_ECLOSED`:: The dialer is closed.
+`NNG_EINVAL`:: There was insufficient space to receive the object.
+	The amount of data actually needed is returned in _sizep_.
+`NNG_ENOTSUP`:: The option _name_ is not supported.
+`NNG_EWRITEONLY`:: The option _name_ may not read.
+
+== SEE ALSO
+
+[.text-left]
+<<nng_tcp_listener_setopt.3tcp#,nng_tcp_listener_setopt(3tcp)>>,
+<<nng_tcp_getopt.3tcp#,nng_tcp_getopt(3tcp)>>,
+<<nng_options.5#,nng_options(5)>>,
+<<nng_strerror.3#,nng_strerror(3)>>,
+<<nng_tcp.5#,nng_tcp(5)>>,
+<<nng_tcp_listener.5#,nng_tcp_listener(5)>>
diff --git a/docs/man/nng_tcp_listener_listen.3tcp.adoc b/docs/man/nng_tcp_listener_listen.3tcp.adoc
index 5ff9ea80..a50caf38 100644
--- a/docs/man/nng_tcp_listener_listen.3tcp.adoc
+++ b/docs/man/nng_tcp_listener_listen.3tcp.adoc
@@ -2,6 +2,7 @@
 //
 // Copyright 2018 Staysail Systems, Inc. <info@staysail.tech>
 // Copyright 2018 Capitar IT Group BV <info@capitar.com>
+// Copyright 2019 Devolutions <info@devolutions.net>
 //
 // This document is supplied under the terms of the MIT License, a
 // copy of which should be located in the distribution where this
@@ -20,7 +21,7 @@ nng_tcp_listener_listen - bind listener to TCP port
 #include <nng/nng.h>
 #include <nng/supplemental/tcp/tcp.h>
 
-int nng_tcp_listener_listen(nng_tcp_listener l, nng_sockaddr *sa);
+int nng_tcp_listener_listen(nng_tcp_listener l, const nng_sockaddr *sa);
 ----
 
 == DESCRIPTION
@@ -40,7 +41,10 @@ that all interfaces on the system should be bound.
 
 The TCP port number may also be zero.  In this case the system will
 choose a free TCP port at random, and use it.
-The _sa_ will be updated with the port chosen.
+
+The chosen port number may be retrieved using the
+<<nng_options.5#,`NNG_OPT_LOCADDR`>> option with the
+<<nng_tcp_listener_getopt.3tcp#,`nng_tcp_listener_getopt()`>> function.
 
 == RETURN VALUES
 
@@ -62,5 +66,6 @@ This function returns 0 on success, and non-zero otherwise.
 <<nng_tcp_listener_alloc.3tcp#,nng_tcp_listener_alloc(3tcp)>>,
 <<nng_tcp_listener_close.3tcp#,nng_tcp_listener_close(3tcp)>>,
 <<nng_tcp_listener_free.3tcp#,nng_tcp_listener_free(3tcp)>>,
+<<nng_tcp_listener_getopt.3tcp#,nng_tcp_listener_getopt(3tcp)>>,
 <<nng_sockaddr.5#,nng_sockaddr(5)>>,
 <<nng_tcp_listener.5#,nng_tcp_listener(5)>>
diff --git a/docs/man/nng_tcp_listener_setopt.3tcp.adoc b/docs/man/nng_tcp_listener_setopt.3tcp.adoc
new file mode 100644
index 00000000..4cf1297a
--- /dev/null
+++ b/docs/man/nng_tcp_listener_setopt.3tcp.adoc
@@ -0,0 +1,62 @@
+= nng_tcp_listener_setopt(3tcp)
+//
+// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech>
+// Copyright 2018 Capitar IT Group BV <info@capitar.com>
+// Copyright 2019 Devolutions <info@devolutions.net>
+//
+// 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_tcp_listener_setopt - set option on TCP listener
+
+== SYNOPSIS
+
+[source, c]
+----
+#include <nng/nng.h>
+#include <nng/supplemental/tcp/tcp.h>
+
+int nng_tcp_listener_setopt(nng_tcp_listener *l, const char *name, const void *data, size_t size);
+----
+
+== DESCRIPTION
+
+The `nng_tcp_listener_setopt()` is used to set the option _name_ for the
+<<nng_tcp_listener.5#,TCP listener>> _l_.
+The value to set is copied from _data_, which should be _size_ bytes
+in length.
+
+=== Options
+
+The options specifically suppported for modification on TCP listeners are:
+
+* <<nng_options.5#NNG_OPT_TCP_LOCADDR,`NNG_OPT_LOCADDR`>>
+* <<nng_options.5#NNG_OPT_TCP_KEEPALIVE,`NNG_OPT_TCP_KEEPALIVE`>>
+* <<nng_options.5#NNG_OPT_TCP_NODELAY,`NNG_OPT_TCP_NODELAY`>>
+
+== RETURN VALUES
+
+This function returns 0 on success, and non-zero otherwise.
+
+== ERRORS
+
+[horizontal]
+`NNG_ECLOSED`:: The listener is closed.
+`NNG_EINVAL`:: Either _data_ or _size_ are invalid.
+`NNG_ENOTSUP`:: The option _name_ is not supported.
+`NNG_EREADONLY`:: The option _name_ may not be modified.
+
+== SEE ALSO
+
+[.text-left]
+<<nng_tcp_listener_getopt.3tcp#,nng_tcp_listener_getopt(3tcp)>>,
+<<nng_tcp_setopt.3tcp#,nng_tcp_setopt(3tcp)>>,
+<<nng_options.5#,nng_options(5)>>,
+<<nng_strerror.3#,nng_strerror(3)>>,
+<<nng_tcp.5#,nng_tcp(5)>>,
+<<nng_tcp_listener.5#,nng_tcp_listener(5)>>
diff --git a/docs/man/nng_tcp_peername.3tcp.adoc b/docs/man/nng_tcp_peername.3tcp.adoc
deleted file mode 100644
index c5f5ece6..00000000
--- a/docs/man/nng_tcp_peername.3tcp.adoc
+++ /dev/null
@@ -1,45 +0,0 @@
-= nng_tcp_peername(3tcp)
-//
-// 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_tcp_peername - get TCP peer socket address
-
-== SYNOPSIS
-
-[source, c]
-----
-#include <nng/nng.h>
-#include <nng/supplemental/tcp/tcp.h>
-
-int nng_tcp_peername(nng_tcp *conn, nng_sockaddr *sa);
-----
-
-== DESCRIPTION
-
-The `nng_tcp_peername()` is retrieves the TCP address of the remote
-peer on the connection _conn_, and stores it in _sa_.
-
-== RETURN VALUES
-
-This function returns 0 on success, and non-zero otherwise.
-
-== ERRORS
-
-[horizontal]
-`NNG_ECLOSED`:: The connection _conn_ is closed.
-
-== SEE ALSO
-
-[.text-left]
-<<nng_tcp_sockname.3tcp#,nng_tcp_sockname(3tcp)>>,
-<<nng_strerror.3#,nng_strerror(3)>>,
-<<nng_tcp.5#,nng_tcp(5)>>
diff --git a/docs/man/nng_tcp_set_keepalive.3tcp.adoc b/docs/man/nng_tcp_set_keepalive.3tcp.adoc
deleted file mode 100644
index 8118861a..00000000
--- a/docs/man/nng_tcp_set_keepalive.3tcp.adoc
+++ /dev/null
@@ -1,55 +0,0 @@
-= nng_tcp_set_keepalive(3tcp)
-//
-// 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_tcp_set_keepalive - enable or disable TCP keepalives
-
-== SYNOPSIS
-
-[source, c]
-----
-#include <nng/nng.h>
-#include <nng/supplemental/tcp/tcp.h>
-
-int nng_tcp_set_keepalive(nng_tcp *conn, bool keepalive);
-----
-
-== DESCRIPTION
-
-The `nng_tcp_set_keepalive()` is used to enable or disable ((TCP keepalives))
-on the connection named by _conn_, depending on the value of _keepalive_.
-
-Different platforms have varying degress of support, with different thresholds
-for the interval between keep alive messages, and the duration required for
-a remote peer to be assumed to be offline.
-
-TIP: Keepalives can help keep a connection active, and prevent firewalls or
-other network equipment from discarding routing information as "`stale`",
-but enabling this means interruptions in connectivity will cause a
-connection to fail, which might otherwise be able to recover.
-Keepalives can also prevent a system from going to sleep properly.
-
-== RETURN VALUES
-
-This function returns 0 on success, and non-zero otherwise.
-
-== ERRORS
-
-[horizontal]
-`NNG_ECLOSED`:: The connection _conn_ is closed.
-
-== SEE ALSO
-
-[.text-left]
-<<nng_tcp_recv.3tcp#,nng_tcp_recv(3tcp)>>,
-<<nng_strerror.3#,nng_strerror(3)>>,
-<<nng_tcp.5#,nng_tcp(5)>>
diff --git a/docs/man/nng_tcp_set_nodelay.3tcp.adoc b/docs/man/nng_tcp_set_nodelay.3tcp.adoc
deleted file mode 100644
index 207bd5ca..00000000
--- a/docs/man/nng_tcp_set_nodelay.3tcp.adoc
+++ /dev/null
@@ -1,56 +0,0 @@
-= nng_tcp_set_nodelay(3tcp)
-//
-// 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_tcp_set_nodelay - disable Nagle's algorithm
-
-== SYNOPSIS
-
-[source, c]
-----
-#include <nng/nng.h>
-#include <nng/supplemental/tcp/tcp.h>
-
-int nng_tcp_set_nodelay(nng_tcp *conn, bool nodelay);
-----
-
-== DESCRIPTION
-
-The `nng_tcp_set_nodelay()` is used to disable (or enable) the use of
-((Nagle's algorithm)) on the TCP connection _conn_.
-
-The default setting is platform dependent.
-
-By setting _nodelay_ to `true`, Nagle's algorithm is disabled.
-This is normally the preferred setting for latency sensitive protocols.
-
-Setting the value to `false` can cause messages to be deferred before being
-sent over the network, in order to allow additional data to accumulate.
-This is reduces overhead associated with each message by allowing overheads
-such as packet headers to amortized across more data, giving better network
-efficiency, but comes at a penalty to latency.
-
-== RETURN VALUES
-
-This function returns 0 on success, and non-zero otherwise.
-
-== ERRORS
-
-[horizontal]
-`NNG_ECLOSED`:: The connection _conn_ is closed.
-
-== SEE ALSO
-
-[.text-left]
-<<nng_tcp_send.3tcp#,nng_tcp_send(3tcp)>>,
-<<nng_strerror.3#,nng_strerror(3)>>,
-<<nng_tcp.5#,nng_tcp(5)>>
diff --git a/docs/man/nng_tcp_setopt.3tcp.adoc b/docs/man/nng_tcp_setopt.3tcp.adoc
new file mode 100644
index 00000000..35b6597c
--- /dev/null
+++ b/docs/man/nng_tcp_setopt.3tcp.adoc
@@ -0,0 +1,60 @@
+= nng_tcp_setopt(3tcp)
+//
+// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech>
+// Copyright 2018 Capitar IT Group BV <info@capitar.com>
+// Copyright 2019 Devolutions <info@devolutions.net>
+//
+// 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_tcp_setopt - set option on TCP connection
+
+== SYNOPSIS
+
+[source, c]
+----
+#include <nng/nng.h>
+#include <nng/supplemental/tcp/tcp.h>
+
+int nng_tcp_setopt(nng_tcp *conn, const char *name, const void *data, size_t size);
+----
+
+== DESCRIPTION
+
+The `nng_tcp_setopt()` is used to set the option _name_ for the
+<<nng_tcp5.#,TCP connection>> _conn_.
+The value to set is copied from _data_, which should be _size_ bytes
+in length.
+
+=== Options
+
+The options specifically suppported for modification on TCP
+connections are:
+
+* <<nng_options.5#NNG_OPT_TCP_KEEPALIVE,`NNG_OPT_TCP_KEEPALIVE`>>
+* <<nng_options.5#NNG_OPT_TCP_NODELAY,`NNG_OPT_TCP_NODELAY`>>
+
+== RETURN VALUES
+
+This function returns 0 on success, and non-zero otherwise.
+
+== ERRORS
+
+[horizontal]
+`NNG_ECLOSED`:: The connection _conn_ is closed.
+`NNG_EINVAL`:: Either _data_ or _size_ are invalid.
+`NNG_ENOTSUP`:: The option _name_ is not supported.
+`NNG_EREADONLY`:: The option _name_ may not be modified.
+
+== SEE ALSO
+
+[.text-left]
+<<nng_tcp_getopt.3tcp#,nng_tcp_getopt(3tcp)>>,
+<<nng_options.5#,nng_options(5)>>,
+<<nng_strerror.3#,nng_strerror(3)>>,
+<<nng_tcp.5#,nng_tcp(5)>>
diff --git a/docs/man/nng_tcp_sockname.3tcp.adoc b/docs/man/nng_tcp_sockname.3tcp.adoc
deleted file mode 100644
index 9d847079..00000000
--- a/docs/man/nng_tcp_sockname.3tcp.adoc
+++ /dev/null
@@ -1,45 +0,0 @@
-= nng_tcp_sockname(3tcp)
-//
-// 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_tcp_sockname - get TCP local socket address
-
-== SYNOPSIS
-
-[source, c]
-----
-#include <nng/nng.h>
-#include <nng/supplemental/tcp/tcp.h>
-
-int nng_tcp_sockname(nng_tcp *conn, nng_sockaddr *sa);
-----
-
-== DESCRIPTION
-
-The `nng_tcp_sockname()` is retrieves the local TCP address associated with
-the connection _conn_, and stores it in _sa_.
-
-== RETURN VALUES
-
-This function returns 0 on success, and non-zero otherwise.
-
-== ERRORS
-
-[horizontal]
-`NNG_ECLOSED`:: The connection _conn_ is closed.
-
-== SEE ALSO
-
-[.text-left]
-<<nng_tcp_peername.3tcp#,nng_tcp_peername(3tcp)>>,
-<<nng_strerror.3#,nng_strerror(3)>>,
-<<nng_tcp.5#,nng_tcp(5)>>