fixes #303 Flesh out compatible API docs

23 files changed, 1673 insertions, 44 deletions

diff --git a/docs/man/man3compat.desc b/docs/man/man3compat.desc
index f9075ddd..a1141850 100644
--- a/docs/man/man3compat.desc
+++ b/docs/man/man3compat.desc
@@ -1 +1,3 @@
 This section documents the _nanomsg_ 1.0 libary compatible functions.
+The functions in this section not be used except to aid in transitioning
+from the older _libnanomsg_ library.
\ No newline at end of file
diff --git a/docs/man/nn_allocmsg.3compat.adoc b/docs/man/nn_allocmsg.3compat.adoc
new file mode 100644
index 00000000..943ecf4b
--- /dev/null
+++ b/docs/man/nn_allocmsg.3compat.adoc
@@ -0,0 +1,66 @@
+= nn_allocmsg(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_allocmsg - allocate message (compatible API)
+
+== SYNOPSIS
+
+[source,c]
+----
+#include <nanomsg/nn.h>
+
+void *nn_allocmsg(size_t size, int type);
+----
+
+== DESCRIPTION
+
+The `nn_allocmsg()` allocates a message structure of size _size_, and is
+primarily used to support zero-copy send operations, making use of the
+`NNG_MSG` special size indicator.
+The value returned is a pointer ot the start of the message payload buffer.
+
+The value of _size_ must be positive, and small enough to hold reasonable
+message data plus book-keeping information.
+
+NOTE: This function is provided for API
+<<nng_compat.3compat#,compatibility>> with legacy _libnanomsg_.
+Consider using the relevant <<libnng.3#,modern API>> instead.
+
+The value of _type_ *must* be zero.
+(This argument was reserved to support different kinds of memory spaces
+for RDMA devices, but this was never developed in the legacy API.)
+
+The returned message must be disposed of by either
+`<<nn_freemsg.3compat#,nn_freemsg()>>` or
+`<<nn_send.3compat#,nn_send()>>` when the caller is finished with it.
+
+== RETURN VALUES
+
+This function returns a pointer to message buffer space, or `NULL`
+on failure.
+
+== ERRORS
+
+[horizontal]
+`ENOMEM`:: Insufficient memory is available.
+`EINVAL`:: An invalid _size_ or _type_ was specified.
+`ETERM`:: The library is shutting down.
+
+== SEE ALSO
+
+<<nn_errno.3compat#,nn_errno(3compat)>>,
+<<nn_freemsg.3compat#,nn_freemsg(3compat)>>,
+<<nn_reallocmsg.3compat#,nn_reallocmsg(3compat)>>,
+<<nn_send.3compat#,nn_send(3compat)>>,
+<<nng_compat.3compat#,nng_compat(3compat)>>,
+<<nng.7#,nng(7)>>
diff --git a/docs/man/nn_bind.3compat.adoc b/docs/man/nn_bind.3compat.adoc
new file mode 100644
index 00000000..79ff2c04
--- /dev/null
+++ b/docs/man/nn_bind.3compat.adoc
@@ -0,0 +1,66 @@
+= nn_bind(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_bind - accept connections from remote peers (compatible API)
+
+== SYNOPSIS
+
+[source, c]
+----
+#include <nanomsg/nn.h>
+
+int nn_bind(int sock, const char *url)
+----
+
+== DESCRIPTION
+
+The `nn_bind()` function arranges for the socket _sock_ to
+accept connections at the address specified by _url_.
+An "`endpoint identifier`" for this socket's association with the _url_ is
+returned to the caller on success.
+This ID can be used with `<<nn_shutdown.3compat#,nn_shutdown()>>`` to
+"`unbind`" the socket from the address at _url_.
+
+NOTE: This function is provided for API
+<<nng_compat.3compat#,compatibility>> with legacy _libnanomsg_.
+Consider using the relevant <<libnng.3#,modern API>> instead.
+
+NOTE: The bind operation is performed asynchronously, and may not have
+completed before this function returns control to the caller.
+
+IMPORTANT: Only transports supported by legacy _libnanomsg_ may be
+used with this function.
+In particular, only the schemes `tcp://`, `ipc://`, `inproc://`, and `ws://` are
+supported with this function.
+(Use the <<libnng.3#,modern API>> to use other schemes.)
+
+== RETURN VALUES
+
+This function returns a positive identifier on success, and -1 on error.
+
+== ERRORS
+
+[horizontal]
+`EADDRINUSE`:: The address specified by _url_ is already in use.
+`EADDRNOTAVAIL`:: The address specified by _url_ is not available.
+`EBADF`:: The socket _sock_ is not open.
+`EINVAL`:: An invalid _url_ was supplied.
+
+== SEE ALSO
+
+<<nn_connect.3compat#,nn_connect(3compat)>>,
+<<nn_errno.3compat#,nn_errno(3compat)>>,
+<<nn_shutdown.3compat#,nn_shutdown(3compat)>>,
+<<nn_socket.3compat#,nn_socket(3compat)>>,
+<<nng_compat.3compat#,nn_compat(3compat)>>,
+<<nng.7#,nng(7)>>
diff --git a/docs/man/nn_close.3compat.adoc b/docs/man/nn_close.3compat.adoc
new file mode 100644
index 00000000..40edef52
--- /dev/null
+++ b/docs/man/nn_close.3compat.adoc
@@ -0,0 +1,50 @@
+= nn_close(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_close - close socket (compatible API)
+
+== SYNOPSIS
+
+[source,c]
+----
+#include <nanomsg/nn.h>
+
+int nn_close(int sock);
+----
+
+== DESCRIPTION
+
+The `nn_close()` function closes the socket _sock_.
+Any operations that are currently in progress will be terminated, and will
+fail with error `EBADF`.
+
+NOTE: This function is provided for API
+<<nng_compat.3compat#,compatibility>> with legacy _libnanomsg_.
+Consider using the relevant <<libnng.3#,modern API>> instead.
+
+== RETURN VALUES
+
+This function returns zero on success, and -1 on failure.
+
+== ERRORS
+
+[horizontal]
+`EBADF`:: The socket is not open.
+`ETERM`:: The library is shutting down.
+
+== SEE ALSO
+
+<<nn_errno.3compat#,nn_errno(3compat)>>,
+<<nn_socket.3compat#,nn_socket(3compat)>>,
+<<nng_compat.3compat#,nng_compat(3compat)>>,
+<<nng.7#,nng(7)>>
diff --git a/docs/man/nn_cmsg.3compat.adoc b/docs/man/nn_cmsg.3compat.adoc
new file mode 100644
index 00000000..c5347a12
--- /dev/null
+++ b/docs/man/nn_cmsg.3compat.adoc
@@ -0,0 +1,77 @@
+= nn_cmsg(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_cmsg - message control data (compatible API)
+
+== SYNOPSIS
+
+[source,c]
+----
+#include <nanomsg/nn.h>
+
+struct nn_cmsghdr {
+    size_t cmsg_len;
+    int    cmsg_level;
+    int    cmsg_type;
+};
+----
+
+== DESCRIPTION
+
+The `nn_cmsghdr` structure describes a block of control data that is
+associated with a message either sent by `<<nn_sendmsg.3compat#,nn_sendmsg()>>`
+or received by `<<nn_recvmsg.3compat#,nn_recvmsg()>>`.
+
+NOTE: This structure and supporting macros are provided for API
+<<nng_compat.3compat#,compatibility>> with legacy _libnanomsg_.
+Consider using the relevant <<libnng.3#,modern API>> instead.
+
+Each header is followed by `cmsg_len` bytes of data, plus any padding required
+to align the structure.
+
+The only defined ancillary data at this time is the protocol headers used by
+the protocols.
+This uses `cmsg_level` set to `PROTO_SP` and the `cmsg_type` set to
+`SP_HDR`.
+The actual data for this will vary from depending on the protocol used.
+
+Convenience macros are provided to make working with these fields easier.
+
+`struct nn_cmsghdr *NN_CMSG_FIRSTHDR(struct nn_msghdr *__hdr__)`::
+This macro returns the first `struct nn_cmsghdr` header in _hdr_.
+
+`struct nn_cmsghdr *NN_CMSG_NXTHDR(struct nn_msghdr *__hdr__, struct nn_cmsghdr *__ch__)`::
+This macro returns a pointer to the next `struct nn_cmsghdr` in _hdr_ after _ch_.
+
+`void *NN_CMSG_DATA(struct nn_cmsghdr *__ch__)`::
+This macro returns a pointer to the header-specific data for _ch_.
+
+`size_t NN_CMSG_ALIGN(size_t __len__)`::
+This macro returns the length specified by _len_, plus any padding required to
+provide the necessary alignment for another structure.
+
+`size_t NN_CMSG_SPACE(size_t __len__)`::
+This macro returns the amount of space required for a header, with _len_
+bytes of following data, and any necessary padding.
+
+`size_t NN_CMSG_LEN(size_t __len__)`::
+This macro evalutes to the length of the header (including alignment),
+and the associated data of length _len_, but without any trailing padding
+to align for another header.
+
+== SEE ALSO
+
+<<nn_recvmsg.3compat#,nn_recvmsg(3compat)>>,
+<<nn_sendmsg.3compat#,nn_sendmsg(3compat)>>,
+<<nng_compat.3compat#,nng_compat(3compat)>>,
+<<nng.7#,nng(7)>>
diff --git a/docs/man/nn_connect.3compat.adoc b/docs/man/nn_connect.3compat.adoc
new file mode 100644
index 00000000..add14060
--- /dev/null
+++ b/docs/man/nn_connect.3compat.adoc
@@ -0,0 +1,65 @@
+= nn_connect(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_connect - connect to remote peer (compatible API)
+
+== SYNOPSIS
+
+[source, c]
+----
+#include <nanomsg/nn.h>
+
+int nn_connect(int sock, const char *url)
+----
+
+== DESCRIPTION
+
+The `nn_connect()` function arranges for the socket _sock_ to
+inititate connection to a peer at the address specified by _url_.
+An "`endpoint identifier`" for this socket's association with the _url_ is
+returned to the caller on success.
+This ID can be used with `<<nn_shutdown.3compat#,nn_shutdown()>>`` to
+"`unbind`" the socket from the address at _url_.
+
+NOTE: This function is provided for API
+<<nng_compat.3compat#,compatibility>> with legacy _libnanomsg_.
+Consider using the relevant <<libnng.3#,modern API>> instead.
+
+NOTE: The connect operation is performed asynchronously, and may not have
+completed before this function returns control to the caller.
+
+IMPORTANT: Only transports supported by legacy _libnanomsg_ may be
+used with this function.
+In particular, only the schemes `tcp://`, `ipc://`, `inproc://`, and `ws://` are
+supported with this function.
+(Use the <<libnng.3#,modern API>> to use other schemes.)
+
+== RETURN VALUES
+
+This function returns a positive identifier success, and -1 on error.
+
+== ERRORS
+
+[horizontal]
+`ECONNREFUSED`:: The connection attempt was refused.
+`EBADF`:: The socket _sock_ is not open.
+`EINVAL`:: An invalid _url_ was supplied.
+
+== SEE ALSO
+
+<<nn_bind.3compat#,nn_bind(3compat)>>,
+<<nn_errno.3compat#,nn_errno(3compat)>>,
+<<nn_shutdown.3compat#,nn_shutdown(3compat)>>,
+<<nn_socket.3compat#,nn_socket(3compat)>>,
+<<nng_compat.3compat#,nn_compat(3compat)>>,
+<<nng.7#,nng(7)>>
diff --git a/docs/man/nn_device.3compat.adoc b/docs/man/nn_device.3compat.adoc
new file mode 100644
index 00000000..945396dc
--- /dev/null
+++ b/docs/man/nn_device.3compat.adoc
@@ -0,0 +1,57 @@
+= nn_device(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_device - create forwarding device (compatible API)
+
+== SYNOPSIS
+
+[source,c]
+----
+#include <nanomsg/nn.h>
+
+int nn_device(int sock1, int sock2);
+----
+
+== DESCRIPTION
+
+The `nn_device()` function is used to create a forwarder, where messages
+received on one of the two sockets _sock1_ and _sock2_ are forwarded to
+the other.
+
+NOTE: This function is provided for API
+<<nng_compat.3compat#,compatibility>> with legacy _libnanomsg_.
+Consider using the relevant <<libnng.3#,modern API>> instead.
+
+The two sockets must be compatible, and must be <<nng.7#raw_mode,raw mode>>
+sockets.
+More detail about devices and how they can be used is available in the
+new style <<nng_device.3#,nng_device()>> documentation.
+
+== RETURN VALUES
+
+This function blocks forever, and will return -1 only when
+one of the sockets is closed or an error occurs.
+
+== ERRORS
+
+[horizonal]
+`EBADF`:: One of the two sockets is invalid or not open, or has
+`EINVAL`:: The sockets are not compatible with each other, or not both raw.
+`ENOMEM`:: Insufficient memory is available.
+
+== SEE ALSO
+
+<<nn_errno.3compat#,nn_errno(3compat)>>,
+<<nn_socket.3compat#,nn_socket(3compat)>>,
+<<nng_compat.3compat#,nng_compat(3compat)>>,
+<<nng.7#,nng(7)>>
diff --git a/docs/man/nn_errno.3compat.adoc b/docs/man/nn_errno.3compat.adoc
new file mode 100644
index 00000000..316a419e
--- /dev/null
+++ b/docs/man/nn_errno.3compat.adoc
@@ -0,0 +1,78 @@
+= nn_errno(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_errno - return most recent error (compatible API)
+
+== SYNOPSIS
+
+[source,c]
+----
+#include <nanomsg/nn.h>
+
+int nn_errno(void);
+----
+
+== DESCRIPTION
+
+The `nn_errno()` function returns the error number corresponding to the
+most recent failed operation by the calling thread.
+
+NOTE: This function is provided for API
+<<nng_compat.3compat#,compatibility>> with legacy _libnanomsg_.
+Consider using the relevant <<libnng.3#,modern API>> instead.
+
+IMPORTANT: The error numbers returned from this function may include
+errors caused by system functions, which overlap the usual `errno` variable,
+and this function simply returns the value of `errno`. 
+However, the values returned may include numeric values that are not
+defined by the system, but are unique to _libnanomsg_, such as `EFSM`.
+
+This library implements the following error numbers, in addition to any others
+that might be set for `errno` by the underlying system:
+
+
+== RETURN VALUES
+
+This function returns the value of `errno`.
+If no operation has failed, then this will be zero.
+
+== ERRORS
+
+[horizontal]
+`EINTR`:: Operation interrupted.
+`ENOMEM`:: Insufficient memory.
+`EINVAL`:: Invalid argument.
+`EBUSY`:: Resource is busy.
+`ETIMEDOUT`:: Operation timed out.
+`ECONNREFUSED`:: Connection refused by peer.
+`EBADF`:: Invalid or closed socket.
+`EAGAIN`:: Operation would block.
+`ENOTSUP`:: Protocol or option not supported.
+`EADDRINUSE`:: Requested address is already in use.
+`EFSM`:: Protocol state incorrect.
+`EPROTO`:: Protocol error.
+`EHOSTUNREACH`:: Remote peer is unreachable.
+`EADDRNOTAVAIL`:: Requested address is not available.
+`EACCES`:: Permission denied.
+`EMSGSIZE`:: Message is too large.
+`ECONNABORTED`:: Connection attempt aborted.
+`ECONNRESET`:: Connection reset by peer.
+`EEXIST`:: Resource already exists.
+`EMFILE`:: Too many open files.
+`ENOSPC`:: Insufficient persistent storage.
+
+== SEE ALSO
+
+<<nn_strerror.3compat#,nn_strerror(3compat)>>,
+<<nng_compat.3compat#,nng_compat(3compat)>>,
+<<nng.7#,nng(7)>>
diff --git a/docs/man/nn_freemsg.3compat.adoc b/docs/man/nn_freemsg.3compat.adoc
new file mode 100644
index 00000000..d23d9f0a
--- /dev/null
+++ b/docs/man/nn_freemsg.3compat.adoc
@@ -0,0 +1,48 @@
+= nn_freemsg(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_freemsg - free message (compatible API)
+
+== SYNOPSIS
+
+[source,c]
+----
+#include <nanomsg/nn.h>
+
+int nn_freemsg(void *msg);
+----
+
+== DESCRIPTION
+
+The `nn_freemsg()` deallocates a message previously allocated with
+`<<nn_allocmsg.3compat#,nn_allocmsg()>>`` or similar functions.
+
+NOTE: This function is provided for API
+<<nng_compat.3compat#,compatibility>> with legacy _libnanomsg_.
+Consider using the relevant <<libnng.3#,modern API>> instead.
+
+== RETURN VALUES
+
+This function always returns 0.
+
+== ERRORS
+
+None.
+
+== SEE ALSO
+
+<<nn_allocmsg.3compat#,nn_allocmsg(3compat)>>,
+<<nn_freemsg.3compat#,nn_freemsg(3compat)>>,
+<<nn_errno.3compat#,nn_errno(3compat)>>,
+<<nng_compat.3compat#,nng_compat(3compat)>>,
+<<nng.7#,nng(7)>>
diff --git a/docs/man/nn_get_statistic.3compat.adoc b/docs/man/nn_get_statistic.3compat.adoc
new file mode 100644
index 00000000..a8129f8d
--- /dev/null
+++ b/docs/man/nn_get_statistic.3compat.adoc
@@ -0,0 +1,45 @@
+= nn_get_statistic(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_get_statistic - get statistic (stub)
+
+== SYNOPSIS
+
+[source,c]
+----
+#include <nanomsg/nn.h>
+
+uint64_t nn_get_statistic(int sock, int stat);
+----
+
+== DESCRIPTION
+
+The `nn_get_statistic()` function exists only as a stub, and always returns
+zero.
+
+NOTE: This function is provided for API
+<<nng_compat.3compat#,compatibility>> with legacy _libnanomsg_.
+Consider using the relevant <<libnng.3#,modern API>> instead.
+
+== RETURN VALUES
+
+Zero.
+
+== ERRORS
+
+None.
+
+== SEE ALSO
+
+<<nng_compat.3compat#,nng_compat(3compat)>>,
+<<nng.7#,nng(7)>>
diff --git a/docs/man/nn_getsockopt.3compat.adoc b/docs/man/nn_getsockopt.3compat.adoc
new file mode 100644
index 00000000..73ab2dee
--- /dev/null
+++ b/docs/man/nn_getsockopt.3compat.adoc
@@ -0,0 +1,216 @@
+= 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
+<<nng_compat.3compat#,compatibility>> with legacy _libnanomsg_.
+Consider using the relevant <<libnng.3#,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 _nng_ 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 (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 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 "`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`::
+This contains either the value `AF_SP` or `AF_SP_RAW`, corresponding
+to the value that the socket was created with.
+
+`NN_PROTOCOL`::
+This option is not supported at this time.
+
+`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.
+
+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_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 the socket is able to accept a message
+for sending.
+
+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_.
+
+`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_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)>>
diff --git a/docs/man/nn_reallocmsg.3compat.adoc b/docs/man/nn_reallocmsg.3compat.adoc
new file mode 100644
index 00000000..c7a186ae
--- /dev/null
+++ b/docs/man/nn_reallocmsg.3compat.adoc
@@ -0,0 +1,58 @@
+= nn_reallocmsg(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_reallocmsg - reallocate message (compatible API)
+
+== SYNOPSIS
+
+[source,c]
+----
+#include <nanomsg/nn.h>
+
+void *nn_reallocmsg(void *old, size_t size);
+----
+
+== DESCRIPTION
+
+The `nn_reallocmsg()` reallocates the message _old_, making it of size _size_.
+
+NOTE: This function is provided for API
+<<nng_compat.3compat#,compatibility>> with legacy _libnanomsg_.
+Consider using the relevant <<libnng.3#,modern API>> instead.
+
+On success, the contents of _old_ are copied into the new message
+(truncating if appropriate), then _old_ is deallocated, and a pointer
+to the new message payload is returned.
+
+On failure, the _old_ message is unchanged, and the value `NULL` is returned
+to the caller.
+
+== RETURN VALUES
+
+This function returns a pointer to message buffer space, or `NULL`
+on failure.
+
+== ERRORS
+
+[horizontal]
+`ENOMEM`:: Insufficient memory is available.
+`EINVAL`:: An invalid _size_ was specified.
+`ETERM`:: The library is shutting down.
+
+== SEE ALSO
+
+<<nn_allocmsg.3compat#,nn_allocmsg(3compat)>>,
+<<nn_freemsg.3compat#,nn_freemsg(3compat)>>,
+<<nn_errno.3compat#,nn_errno(3compat)>>,
+<<nng_compat.3compat#,nng_compat(3compat)>>,
+<<nng.7#,nng(7)>>
diff --git a/docs/man/nn_recv.3compat.adoc b/docs/man/nn_recv.3compat.adoc
new file mode 100644
index 00000000..8b873f8f
--- /dev/null
+++ b/docs/man/nn_recv.3compat.adoc
@@ -0,0 +1,74 @@
+= nn_recv(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_send - receive data (compatible API)
+
+== SYNOPSIS
+
+[source, c]
+----
+#include <nanomsg/nn.h>
+
+int nn_recv(int sock, void *data, size_t size, int flags)
+----
+
+== DESCRIPTION
+
+The `nn_recv()` function receives a message from the socket _sock_.
+The message body must fit within _size_ bytes, and will be stored
+at the location specified by _data_, unless _size_ is the
+special value `NN_MSG`, indicating a zero-copy operation.
+
+NOTE: This function is provided for API
+<<nng_compat.3compat#,compatibility>> with legacy _libnanomsg_.
+Consider using the relevant <<libnng.3#,modern API>> instead.
+
+If _size_ has the special value `NN_MSG`, then a zero-copy operation
+is performed.
+In this case, instead of copying the message data into the address
+specified by _data_, a new message large enough to hold the message data
+will be allocated (as if by the
+function `<<nn_allocmsg.3compat#,nn_allocmsg()>>`), and the message
+payload will be stored accordingly.
+In this case, the value stored at _data_ will not be message data,
+but a pointer to the message itself.
+In this case, on success, the caller shall take responsibility for
+the final disposition of the message (such as by sending it to
+another peer using `<<nn_send.3compat#,nn_send()>>`) or
+`<<nn_freemsg.3compat#,nn_freemsg()>>`.
+
+The _flags_ field may contain the special flag `NN_DONTWAIT`.
+In this case, if the no message is available for immediate receipt,
+the operation shall not block, but instead will fail with the error `EAGAIN`.
+
+== RETURN VALUES
+
+This function returns the number of bytes sent on success, and -1 on error.
+
+== ERRORS
+
+[horizontal]
+`EAGAIN`:: The operation would block.
+`EBADF`:: The socket _sock_ is not open.
+`EFSM`:: The socket cannot receive in this state.
+`ENOTSUP`:: This protocol cannot receive.
+`ETIMEDOUT`:: Operation timed out.
+
+== SEE ALSO
+
+<<nn_errno.3compat#,nn_errno(3compat)>>,
+<<nn_recvmsg.3compat#,nn_recvmsg(3compat)>>,
+<<nn_send.3compat#,nn_send(3compat)>>,
+<<nn_socket.3compat#,nn_socket(3compat)>>,
+<<nng_compat.3compat#,nn_compat(3compat)>>,
+<<nng.7#,nng(7)>>
diff --git a/docs/man/nn_recvmsg.3compat.adoc b/docs/man/nn_recvmsg.3compat.adoc
new file mode 100644
index 00000000..f9683d50
--- /dev/null
+++ b/docs/man/nn_recvmsg.3compat.adoc
@@ -0,0 +1,98 @@
+= nn_recvmsg(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_recvmsg - receive message (compatible API)
+
+== SYNOPSIS
+
+[source, c]
+----
+#include <nanomsg/nn.h>
+
+int nn_recvmsg(int sock, struct nn_msghdr *hdr, int flags);
+----
+
+== DESCRIPTION
+
+The `nn_recvmsg()` function receives a message into the heade described by
+_hdr_ using the socket _sock_.
+
+NOTE: This function is provided for API
+<<nng_compat.3compat#,compatibility>> with legacy _libnanomsg_.
+Consider using the relevant <<libnng.3#,modern API>> instead.
+
+The _flags_ field may contain the special flag `NN_DONTWAIT`.
+In this case, if no message is ready for receiving on _sock_,
+the operation shall not block, but instead will fail with the error `EAGAIN`.
+
+The _hdr_ points to a structure of type `struct nn_msghdr`, which has the
+following definition:
+
+[source, c]
+----
+struct nn_iovec {
+    void * iov_base;
+    size_t iov_len;
+};
+
+struct nn_msghdr {
+    struct nn_iovec *msg_iov;
+    int              msg_iovlen;
+    void *           msg_control;
+    size_t           msg_controllen;
+};
+----
+
+The `msg_iov` is an array of scatter items, permitting the message
+to be spread into different memory blocks.
+There are `msg_iovlen` elements in this array, each of which
+has the base address (`iov_base`) and length (`iov_len`) indicated.
+
+The last member of this array may have the `iov_len` field set to `NN_MSG`,
+in which case the function shall allocate a message buffer, and store the
+pointer to it at the address indicated by `iov_base`.
+This can help save an extra copy operation.
+The buffer should be deallocated by `<<nn_freemsg.3compat#,nn_freemsg()>>`
+or similar when it is no longer needed.
+
+The values of `msg_control` and `msg_controllen` describe a buffer
+of ancillary data associated with the message.
+This is currenly only useful to obtain the message headers
+used with <<nng.7#raw_mode,raw mode>> sockets.
+In all other circumstances these fields should be zero.
+Details about this structure are covered in
+`<<nn_cmsg.3compat#,nn_cmsg(3compat)>>`.
+
+== RETURN VALUES
+
+This function returns the number of bytes received on success, and -1 on error.
+
+== ERRORS
+
+[horizontal]
+`EAGAIN`:: The operation would block.
+`EBADF`:: The socket _sock_ is not open.
+`EFSM`:: The socket cannot receive in this state.
+`EINVAL`:: The _hdr_ is invalid.
+`ENOTSUP`:: This protocol cannot receive.
+`ETIMEDOUT`:: Operation timed out.
+
+== SEE ALSO
+
+<<nn_cmsg.3compat#,nn_cmsg(3compat)>>,
+<<nn_errno.3compat#,nn_errno(3compat)>>,
+<<nn_recv.3compat#,nn_recv(3compat)>>,
+<<nn_send.3compat#,nn_send(3compat)>>,
+<<nn_socket.3compat#,nn_socket(3compat)>>,
+<<nng_compat.3compat#,nn_compat(3compat)>>,
+<<nng.7#,nng(7)>>
diff --git a/docs/man/nn_send.3compat.adoc b/docs/man/nn_send.3compat.adoc
new file mode 100644
index 00000000..181d8c7f
--- /dev/null
+++ b/docs/man/nn_send.3compat.adoc
@@ -0,0 +1,73 @@
+= nn_send(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_send - send data (compatible API)
+
+== SYNOPSIS
+
+[source, c]
+----
+#include <nanomsg/nn.h>
+
+int nn_send(int sock, const void *data, size_t size, int flags)
+----
+
+== DESCRIPTION
+
+The `nn_send()` function creates a message containing _data_ (of size _size_),
+and sends using the socket _sock_.
+
+NOTE: This function is provided for API
+<<nng_compat.3compat#,compatibility>> with legacy _libnanomsg_.
+Consider using the relevant <<libnng.3#,modern API>> instead.
+
+If _size_ has the special value `NN_MSG`, then a zero-copy operation
+is performed.
+In this case, _data_ points not to the message content itself, but instead
+is a pointer to the pointer, an extra level of pointer indirection.
+The message must have been previously allocated by
+`<<nn_allocmsg.3compat#,nn_allocmsg()>>` or
+`<<nn_recvmsg.3compat#,nn_recvmsg()>>`, using the same `NN_MSG` size.
+In this case, the "`ownership``" of the message shall remain with
+the caller, unless the function returns 0, indicating that the
+function has taken responsibility for delivering or disposing of the
+message.
+
+The _flags_ field may contain the special flag `NN_DONTWAIT`.
+In this case, if the socket is unable to accept more data for sending,
+the operation shall not block, but instead will fail with the error `EAGAIN`.
+
+NOTE: The send operation is performed asynchronously, and may not have
+completed before this function returns control to the caller.
+
+== RETURN VALUES
+
+This function returns the number of bytes sent on success, and -1 on error.
+
+== ERRORS
+
+[horizontal]
+`EAGAIN`:: The operation would block.
+`EBADF`:: The socket _sock_ is not open.
+`EFSM`:: The socket cannot send in this state.
+`ENOTSUP`:: This protocol cannot send.
+`ETIMEDOUT`:: Operation timed out.
+
+== SEE ALSO
+
+<<nn_errno.3compat#,nn_errno(3compat)>>,
+<<nn_recv.3compat#,nn_recv(3compat)>>,
+<<nn_sendmsg.3compat#,nn_sendmsg(3compat)>>,
+<<nn_socket.3compat#,nn_socket(3compat)>>,
+<<nng_compat.3compat#,nn_compat(3compat)>>,
+<<nng.7#,nng(7)>>
diff --git a/docs/man/nn_sendmsg.3compat.adoc b/docs/man/nn_sendmsg.3compat.adoc
new file mode 100644
index 00000000..71a69c14
--- /dev/null
+++ b/docs/man/nn_sendmsg.3compat.adoc
@@ -0,0 +1,106 @@
+= nn_sendmsg(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_sendmsg - send message (compatible API)
+
+== SYNOPSIS
+
+[source, c]
+----
+#include <nanomsg/nn.h>
+
+int nn_sendmsg(int sock, const struct nn_msghdr *hdr, int flags);
+----
+
+== DESCRIPTION
+
+The `nn_sendmsg()` function sends the message described by _hdr_ using the
+socket _sock_.
+
+NOTE: This function is provided for API
+<<nng_compat.3compat#,compatibility>> with legacy _libnanomsg_.
+Consider using the relevant <<libnng.3#,modern API>> instead.
+
+The _flags_ field may contain the special flag `NN_DONTWAIT`.
+In this case, if the socket is unable to accept more data for sending,
+the operation shall not block, but instead will fail with the error `EAGAIN`.
+
+The _hdr_ points to a structure of type `struct nn_msghdr`, which has the
+following definition:
+
+[source, c]
+----
+struct nn_iovec {
+    void * iov_base;
+    size_t iov_len;
+};
+
+struct nn_msghdr {
+    struct nn_iovec *msg_iov;
+    int              msg_iovlen;
+    void *           msg_control;
+    size_t           msg_controllen;
+};
+----
+
+The `msg_iov` is an array of gather items, permitting the message
+to be spread into different memory blocks.
+There are `msg_iovlen` elements in this array, each of which
+has the base address (`iov_base`) and length (`iov_len`) indicated.
+
+For buffers allocated for zero copy
+(such as by `<<nn_allocmsg.3compat#,nn_allocmsg()>>`), the value
+of `iov_base` should be the address of the pointer to the buffer,
+rather than the address of the buffer itself. 
+In this case, the value of `iov_len` should be `NN_MSG`,
+as the length is inferred from the allocated message.
+If the `msg_iovlen` field is `NN_MSG`, then this function will free
+the associated buffer after it is done with it, if it returns successfully.
+(If the function returns with an error, then the caller retains ownership
+of the associated buffer and may retry the operation or free the buffer
+at its choice.)
+
+The values of `msg_control` and `msg_controllen` describe a buffer
+of ancillary data to send the message.
+This is currenly only useful to provide the message headers
+used with <<nng.7#raw_mode,raw mode>> sockets.
+In all other circumstances these fields should be zero.
+Details about this structure are covered in
+`<<nn_cmsg.3compat#,nn_cmsg(3compat)>>`.
+
+NOTE: The send operation is performed asynchronously, and may not have
+completed before this function returns control to the caller.
+
+== RETURN VALUES
+
+This function returns the number of bytes sent on success, and -1 on error.
+
+== ERRORS
+
+[horizontal]
+`EAGAIN`:: The operation would block.
+`EBADF`:: The socket _sock_ is not open.
+`EFSM`:: The socket cannot send in this state.
+`EINVAL`:: The _hdr_ is invalid.
+`ENOTSUP`:: This protocol cannot send.
+`ETIMEDOUT`:: Operation timed out.
+
+== SEE ALSO
+
+<<nn_cmsg.3compat#,nn_cmsg(3compat)>>,
+<<nn_errno.3compat#,nn_errno(3compat)>>,
+<<nn_recv.3compat#,nn_recv(3compat)>>,
+<<nn_send.3compat#,nn_send(3compat)>>,
+<<nn_socket.3compat#,nn_socket(3compat)>>,
+<<nng_compat.3compat#,nn_compat(3compat)>>,
+<<nng.7#,nng(7)>>
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)>>
diff --git a/docs/man/nn_shutdown.3compat.adoc b/docs/man/nn_shutdown.3compat.adoc
new file mode 100644
index 00000000..2de6b1f0
--- /dev/null
+++ b/docs/man/nn_shutdown.3compat.adoc
@@ -0,0 +1,54 @@
+= nn_shutdown(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_shutdown - shut down endpoint (compatible API)
+
+== SYNOPSIS
+
+[source, c]
+----
+#include <nanomsg/nn.h>
+
+int nn_shutdown(int sock, int ep)
+----
+
+== DESCRIPTION
+
+The `nn_shutdown()` shuts down the "`endpoint`"  _ep_ on the socket _sock_.
+This will stop the socket from either accepting new connections, or establishing
+old ones.
+Additionally, any established connections associated with _ep_ will be
+closed.
+
+NOTE: This function is provided for API
+<<nng_compat.3compat#,compatibility>> with legacy _libnanomsg_.
+Consider using the relevant <<libnng.3#,modern API>> instead.
+
+== RETURN VALUES
+
+This function returns zero on success, and -1 on error.
+
+== ERRORS
+
+[horizontal]
+`EBADF`:: The socket _sock_ is not open.
+`EINVAL`:: An invalid _ep_ was supplied.
+
+== SEE ALSO
+
+<<nn_bind.3compat#,nn_bind(3compat)>>,
+<<nn_connect.3compat#,nn_connect(3compat)>>,
+<<nn_errno.3compat#,nn_errno(3compat)>>,
+<<nn_socket.3compat#,nn_socket(3compat)>>,
+<<nng_compat.3compat#,nn_compat(3compat)>>,
+<<nng.7#,nng(7)>>
diff --git a/docs/man/nn_socket.3compat.adoc b/docs/man/nn_socket.3compat.adoc
new file mode 100644
index 00000000..33bb1626
--- /dev/null
+++ b/docs/man/nn_socket.3compat.adoc
@@ -0,0 +1,77 @@
+= nn_socket(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_socket - create socket (compatible API)
+
+== SYNOPSIS
+
+[source,c]
+----
+#include <nanomsg/nn.h>
+
+int nn_socket(int af, int proto);
+----
+
+== DESCRIPTION
+
+The `nn_socket()` function creates socket using the address family _af_ and
+protocol _proto_ and returns it.
+
+NOTE: This function is provided for API
+<<nng_compat.3compat#,compatibility>> with legacy _libnanomsg_.
+Consider using the relevant <<libnng.3#,modern API>> instead.
+
+IMPORTANT: Mixing the compatibility API and the modern API is not supported
+on a given socket.
+
+NOTE: Some protocols, transports, and features are only available in the modern API.
+
+The address family _af_ can be one of two values:
+
+[horizontal]
+`AF_SP`:: Normal socket.
+`AF_SP_RAW`:: <<nng.7#raw_mode,"`Raw mode`">> socket.
+
+The protocol indicates the protocol to be used when creating the socket.
+The following protocols are defined:
+
+[horizontal]
+`NN_PAIR`:: <<nng_pair.7#,Pair>> protocol.
+`NN_PUB`:: <<nng_pub.7#,Publisher>> protocol.
+`NN_SUB`:: <<nng_sub.7#,Subscriber>> protocol.
+`NN_REQ`:: <<nng_req.7#,Requestor>> protocol.
+`NN_REP`:: <<nng_rep.7#,Replier>> protocol.
+`NN_PUSH`:: <<nng_push.7#,Push>> protocol.
+`NN_PULL`:: <<nng_pull.7#,Pull>> protocol.
+`NN_SURVEYOR`:: <<nng_surveyor.7#,Surveyor>> protocol.
+`NN_RESPONDENT`:: <<nng_respondent.7#,Respondent>> protocol.
+`NN_BUS`:: <<nng_bus.7#,Bus>> protocol.
+
+== RETURN VALUES
+
+This function returns a valid socket number on success, and -1 on failure.
+
+== ERRORS
+
+[horizontal]
+`ENOMEM`:: Insufficient memory is available.
+`ENOTSUP`:: The protocol is not supported.
+`ETERM`:: The library is shutting down.
+
+== SEE ALSO
+
+<<nng_socket.5#,nng_socket(5)>>,
+<<nn_close.3compat#,nn_close(3compat)>>,
+<<nn_errno.3compat#,nn_errno(3compat)>>,
+<<nng_compat.3compat#,nng_compat(3compat)>>,
+<<nng.7#,nng(7)>>
diff --git a/docs/man/nn_strerror.3compat.adoc b/docs/man/nn_strerror.3compat.adoc
new file mode 100644
index 00000000..090a012a
--- /dev/null
+++ b/docs/man/nn_strerror.3compat.adoc
@@ -0,0 +1,46 @@
+= nn_errno(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_strerror - return message for error (compatible API)
+
+== SYNOPSIS
+
+[source,c]
+----
+#include <nanomsg/nn.h>
+
+const char *nn_strerror(int err);
+----
+
+== DESCRIPTION
+
+The `nn_strerror()` function returns a human readable message corresponding
+to the given error number _err_.
+
+NOTE: This function is provided for API
+<<nng_compat.3compat#,compatibility>> with legacy _libnanomsg_.
+Consider using the relevant <<libnng.3#,modern API>> instead.
+
+== RETURN VALUES
+
+This function returns the message corresponding to _err_.
+
+== ERRORS
+
+None.
+
+== SEE ALSO
+
+<<nn_errno.3compat#,nn_errno(3compat)>>,
+<<nng_compat.3compat#,nng_compat(3compat)>>,
+<<nng.7#,nng(7)>>
diff --git a/docs/man/nn_term.3compat.adoc b/docs/man/nn_term.3compat.adoc
new file mode 100644
index 00000000..e61a40ed
--- /dev/null
+++ b/docs/man/nn_term.3compat.adoc
@@ -0,0 +1,58 @@
+= nn_term(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_term - terminate library (compatible API)
+
+== SYNOPSIS
+
+[source,c]
+----
+#include <nanomsg/nn.h>
+
+void nn_term(void);
+----
+
+== DESCRIPTION
+
+The `nn_term()` function closes any open sockets, and frees all resources
+allocated by the library.
+Any operations that are currently in progress will be terminated, and will
+fail with error `EBADF` or `ETERM`.
+
+NOTE: This function is provided for API
+<<nng_compat.3compat#,compatibility>> with legacy _libnanomsg_.
+Consider using the relevant <<libnng.3#,modern API>> instead.
+
+IMPORTANT: This function is not thread-safe, and is not suitable for use
+in library calls.
+The intended purpose of this is to clean up at application termination; for
+example by registering this function with `atexit()`.
+This can help prevent false leak reports caused when memory checkers notice
+global resources allocated by the library.
+Libraries should never use this function, but should explicitly close their
+own sockets directly.
+
+== RETURN VALUES
+
+None.
+
+== ERRORS
+
+None.
+
+== SEE ALSO
+
+<<nn_errno.3compat#,nn_errno(3compat)>>,
+<<nn_socket.3compat#,nn_socket(3compat)>>,
+<<nng_compat.3compat#,nng_compat(3compat)>>,
+<<nng.7#,nng(7)>>
diff --git a/docs/man/nng_compat.3compat.adoc b/docs/man/nng_compat.3compat.adoc
index a0ac64c2..5493e41f 100644
--- a/docs/man/nng_compat.3compat.adoc
+++ b/docs/man/nng_compat.3compat.adoc
@@ -27,9 +27,9 @@ most _nanomsg_ 1.0 applications.
 
 IMPORTANT: This is intended to faciliate converting legacy applications to
 use the _nng_ library.
-New applications shoud not use the newer <<nng.7#,_nng_>> API instead.
+New applications should use the newer <<nng.7#,_nng_>> API instead.
 
-Applications making use of this ((compatibility layer)) take care
+Applications making use of this ((compatibility layer)) must take care
 to link with <<libnng.3#,_libnng_>> instead of _libnn_.
 
 NOTE: Some capabilities, protocols, and transports, will not be accessible
@@ -50,34 +50,59 @@ used in compilation.
 
 The following functions are provided:
 
+// For PDF, we don't have horizontal lists, so we have to conditionalize
+// this and use tables there -- it looks ugly otherwise.
+ifndef::backend-pdf[]
+[horizontal]
+`<<nn_socket.3compat#,nn_socket()>>`:: create socket
+`<<nn_getsockopt.3compat#,nn_getsockopt()>>`:: get socket option
+`<<nn_setsockopt.3compat#,nn_setsockopt()>>`:: set socket option
+`<<nn_bind.3compat#,nn_bind()>>`:: accept connections from remote peers
+`<<nn_connect.3compat#,nn_connect()>>`:: connect to remote peer
+`<<nn_send.3compat#,nn_send()>>`:: send data
+`<<nn_recv.3compat#,nn_recv()>>`:: receive data
+`<<nn_shutdown.3compat#,nn_shutdown()>>`:: shut down endpoint
+`<<nn_close.3compat#,nn_close()>>`:: close socket
+//`nn_poll()`:: poll sockets
+`<<nn_device.3compat#,nn_device()>>`:: create forwarding device
+`<<nn_recvmsg.3compat#,nn_recvmsg()>>`:: receive message
+`<<nn_sendmsg.3compat#,nn_sendmsg()>>`:: send message
+`<<nn_cmsg.3compat#,nn_cmsg()>>`:: message control data
+`<<nn_get_statistic.3compat#,nn_get_statistic()>>`:: get statistic (stub)
+`<<nn_allocmsg.3compat#,nn_allocmsg()>>`:: allocate message
+`<<nn_reallocmsg.3compat#,nn_reallocmsg()>>`:: reallocate message
+`<<nn_freemsg.3compat#,nn_freemsg()>>`:: free message
+`<<nn_errno.3compat#,nn_errno()>>`:: return most recent error
+`<<nn_strerror.3compat#,nn_strerror()>>`:: return message for error
+`<<nn_term.3compat#,nn_term()>>`:: terminate library
+endif::[]
+ifdef::backend-pdf[]
 // Add links for the following as they are written.
+[.hdlist,width=90%, grid=rows,cols="1,2", align="center"]
 |===
-|`nn_socket()`|create a socket
-|`nn_getsockopt()`|get socket option
-|`nn_setsockopt()`|set socket option
-|`nn_bind()`|accept connections from remote peers
-|`nn_connect()`|connect to remote peer
-|`nn_send()`|send data
-|`nn_recv()`|receive data
-|`nn_shutdown()`|shut down endpoint
-|`nn_close()`|close socket
-|`nn_poll()`|poll sockets
-|`nn_device()`|create forwarding device
-|`nn_recvmsg()`|receive message
-|`nn_sendmsg()`|send message
-|`nn_get_statistic()`|get statistic (stub)
-|`nn_allocmsg()`|allocate message
-|`nn_reallocmsg()`|reallocate message
-|`nn_freemsg()`|free message
-|`nn_errno()`|return most recent error
-|`nn_strerror()`|return message for error
-|`nn_term()`|terminate library
+|`<<nn_socket.3compat#,nn_socket()`>>|create socket
+|`<<nn_getsockopt.3compat#,nn_getsockopt()>>`|get socket option
+|`<<nn_setsockopt.3compat#,nn_setsockopt()>>`|set socket option
+|`<<nn_bind.3compat#,nn_bind()>>`|accept connections from remote peers
+|`<<nn_connect.3compat#,nn_connect()>>`|connect to remote peer
+|`<<nn_send.3compat#,nn_send()>>`|send data
+|`<<nn_recv.3compat#,nn_recv()>>`|receive data
+|`<<nn_shutdown.3compat#,nn_shutdown()>>`|shut down endpoint
+|`<<nn_close.3compat#,nn_close()>>`|close socket
+//|`nn_poll()`|poll sockets
+|`<<nn_device.3compat#,nn_device()>>`|create forwarding device
+|`<<nn_recvmsg.3compat#,nn_recvmsg()>>`|receive message
+|`<<nn_sendmsg.3compat#,nn_sendmsg()>>`|send message
+|`<<nn_cmsg.3compat#,nn_cmsg()>>`|message control data
+|`<<nn_get_statistic.3compat#,nn_get_statistic()>>`|get statistic (stub)
+|`<<nn_allocmsg.3compat#,nn_allocmsg()>>`|allocate message
+|`<<nn_reallocmsg.3compat#,nn_reallocmsg()>>`|reallocate message
+|`<<nn_freemsg.3compat#,nn_freemsg()>>`|free message
+|`<<nn_errno.3compat#,nn_errno()>>`|return most recent error
+|`<<nn_strerror.3compat#,nn_strerror()>>`|return message for error
+|`<<nn_term.3compat#,nn_term()>>`|terminate library
 |===
-
-NOTE: Documentation for the compatibility functions will be
-supplied here later.
-In the meantime it can be found online at the
-http://nanomsg.org[nanomsg site].
+endif::[]
 
 There are a few caveats, that should be kept in mind.
 
@@ -94,10 +119,8 @@ NOTE: The following options (`nn_getsockopt`) are unsupported:
 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: Access to statistics using this legacy API
+(`<<nn_get_statistic.3compat#,nn_get_statistic()>>`) is unsupported.
 
 NOTE: Some transports can support longer URLs than legacy _libnanomsg_ can.
 It is a good idea to use short pathnames in URLs if interoperability
@@ -124,18 +147,7 @@ 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_.
-//
-// |===
-// |<<nng_alloc.3#,nng_alloc()>>|allocate memory
-// |<<nng_free.3#,nng_free()>>|free memory
-// |<<nng_strerror.3#,nng_strerror()>>|return an error description
-// |<<nng_version.3#,nng_version()>>|report library version
-// |===
-//
-
 == SEE ALSO
 
+<<libnng.3#,libnng(3)>>,
 <<nng.7#,nng(7)>>
diff --git a/docs/man/nng_device.3.adoc b/docs/man/nng_device.3.adoc
index 09717e21..aaf71af6 100644
--- a/docs/man/nng_device.3.adoc
+++ b/docs/man/nng_device.3.adoc
@@ -97,7 +97,8 @@ the requestor, if reliable delivery is needed.
 
 == RETURN VALUES
 
-This function returns 0 on success, and non-zero otherwise.
+This function continues running, and only returns an appropriate error when
+one occurs, or if one of the sockets is closed.
 
 == ERRORS