Compat pages converted.

21 files changed, 1133 insertions, 0 deletions

diff --git a/docs/ref/compat/nn_allocmsg.adoc b/docs/ref/compat/nn_allocmsg.adoc
new file mode 100644
index 00000000..273f17e6
--- /dev/null
+++ b/docs/ref/compat/nn_allocmsg.adoc
@@ -0,0 +1,40 @@
+## nn_allocmsg
+
+Allocate message (compatible API).
+
+### Synopsis
+
+```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 to 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.
+
+The value of _type_ *must* be zero.
+
+The returned message must be disposed of by either xref:nn_freemsg.adoc[`nn_freemsg`] or xref:nn_send.adoc[`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
+
+xref:nn_errno.adoc[nn_errno],
+xref:nn_freemsg.adoc[nn_freemsg],
+xref:nn_reallocmsg.adoc[nn_reallocmsg],
+xref:nn_send.adoc[nn_send]
diff --git a/docs/ref/compat/nn_bind.adoc b/docs/ref/compat/nn_bind.adoc
new file mode 100644
index 00000000..49438bd3
--- /dev/null
+++ b/docs/ref/compat/nn_bind.adoc
@@ -0,0 +1,41 @@
+## nn_bind
+
+Accept connections from remote peers (compatible API).
+
+### Synopsis
+
+```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 identifier for this socket's association with the _url_ is returned to the caller on success.
+This identfier can be used with xref:nn_shutdown.adoc[`nn_shutdown`] to remove the association later.
+
+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.
+
+### 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
+
+xref:nn_connect.adoc[nn_connect],
+xref:nn_errno.adoc[nn_errno],
+xref:nn_shutdown.adoc[nn_shutdown],
+xref:nn_socket.adoc[nn_socket]
diff --git a/docs/ref/compat/nn_close.adoc b/docs/ref/compat/nn_close.adoc
new file mode 100644
index 00000000..b44045ae
--- /dev/null
+++ b/docs/ref/compat/nn_close.adoc
@@ -0,0 +1,32 @@
+## 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`.
+
+### 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
+
+xref:nn_errno.adoc[nn_errno],
+xref:nn_socket.adoc[nn_socket]
\ No newline at end of file
diff --git a/docs/ref/compat/nn_cmsg.adoc b/docs/ref/compat/nn_cmsg.adoc
new file mode 100644
index 00000000..82b48966
--- /dev/null
+++ b/docs/ref/compat/nn_cmsg.adoc
@@ -0,0 +1,55 @@
+## 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 xref:nn_sendmsg.adoc[`nn_sendmsg`] or received by xref:nn_recvmsg.adoc[`nn_recvmsg`].
+
+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 evaluates 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
+
+xref:nn_recvmsg.adoc[nn_recvmsg],
+xref:nn_sendmsg.adoc[nn_sendmsg]
diff --git a/docs/ref/compat/nn_connect.adoc b/docs/ref/compat/nn_connect.adoc
new file mode 100644
index 00000000..7f7d7856
--- /dev/null
+++ b/docs/ref/compat/nn_connect.adoc
@@ -0,0 +1,40 @@
+## nn_connect
+
+Connect to remote peer (compatible API).
+
+### Synopsis
+
+```c
+#include <nanomsg/nn.h>
+
+int nn_connect(int sock, const char *url)
+```
+
+### Description
+
+The `nn_connect` function arranges for the socket _sock_ to initiate connection to a peer at the address specified by _url_.
+An identifier for this socket's association with the _url_ is returned to the caller on success.
+This identifier can be used with xref:nn_shutdown.adoc[`nn_shutdown`] to remove the association later.
+
+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.
+
+### 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
+
+xref:nn_bind.adoc[nn_bind],
+xref:nn_errno.adoc[nn_errno],
+xref:nn_shutdown.adoc[nn_shutdown],
+xref:nn_socket.adoc[nn_socket]
diff --git a/docs/ref/compat/nn_device.adoc b/docs/ref/compat/nn_device.adoc
new file mode 100644
index 00000000..6f760d1a
--- /dev/null
+++ b/docs/ref/compat/nn_device.adoc
@@ -0,0 +1,34 @@
+## 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.
+
+The two sockets must be compatible, and must be raw mode sockets.
+
+### Return Values
+
+This function blocks forever, and will return -1 only when one of the sockets is closed or an error occurs.
+
+### Errors
+
+[horizontal]
+`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
+
+xref:nn_errno.adoc[nn_errno],
+xref:nn_socket.adoc[nn_socket]
diff --git a/docs/ref/compat/nn_errno.adoc b/docs/ref/compat/nn_errno.adoc
new file mode 100644
index 00000000..04defc84
--- /dev/null
+++ b/docs/ref/compat/nn_errno.adoc
@@ -0,0 +1,55 @@
+## nn_errno
+
+Return most recent error (compatible API).
+
+### Synopsis
+
+```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.
+
+IMPORTANT: The error numbers returned from this function includes errors caused by system functions, which overlap the usual `errno` variable.
+However, the values returned may include numeric values that are not defined by the system, but are unique to _libnanomsg_.
+
+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
+
+xref:nn_strerror.adoc[nn_strerror]
diff --git a/docs/ref/compat/nn_freemsg.adoc b/docs/ref/compat/nn_freemsg.adoc
new file mode 100644
index 00000000..0feb3491
--- /dev/null
+++ b/docs/ref/compat/nn_freemsg.adoc
@@ -0,0 +1,26 @@
+## 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 xref:nn_allocmsg.adoc[`nn_allocmsg`] or similar functions.
+
+### Return Values
+
+This function always returns 0.
+
+### See Also
+
+xref:nn_allocmsg.adoc[nn_allocmsg],
+xref:nn_freemsg.adoc[nn_freemsg],
+xref:nn_errno.adoc[nn_errno]
diff --git a/docs/ref/compat/nn_get_statistic.adoc b/docs/ref/compat/nn_get_statistic.adoc
new file mode 100644
index 00000000..c0b31757
--- /dev/null
+++ b/docs/ref/compat/nn_get_statistic.adoc
@@ -0,0 +1,19 @@
+## nn_get_statistic
+
+Get statistic (stub).
+
+### Synopsis
+
+```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.
+
+### Return Values
+
+Zero.
diff --git a/docs/ref/compat/nn_getsockopt.adoc b/docs/ref/compat/nn_getsockopt.adoc
new file mode 100644
index 00000000..f8b29abe
--- /dev/null
+++ b/docs/ref/compat/nn_getsockopt.adoc
@@ -0,0 +1,165 @@
+## nn_getsockopt
+
+Get socket option (compatible API).
+
+### Synopsis
+
+```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_.
+
+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.footnote:[In _NNG_ buffers are sized as a count of messages rather than bytes.
+Accordingly this value is the queue depth multiplied by 1024
+(representing an estimate that the average message size is 1kB).
+Applications that have unusual message sizes may wish to adjust the value used here.]
+
+`NN_RCVBUF`::
+Receive buffer size in bytes.
+The same caveats for `NN_SNDBUF` apply here as well.
+
+`NN_SNDTIMEO`::
+Send time-out in milliseconds.
+Send operations will fail with `ETIMEDOUT` if no message can be received
+after this many milliseconds have transpired since the operation was started.
+A value of -1 means that no timeout is applied.
+
+`NN_RCVTIMEO`::
+Receive time-out in milliseconds.
+Receive operations will fail with `ETIMEDOUT` if no message can be received after this many milliseconds have transpired since the operation was started.
+A value of -1 means that no timeout is applied.
+
+`NN_RCVMAXSIZE`::
+Maximum receive size in bytes.
+The socket will discard messages larger than this on receive.
+The default, 1MB, is intended to prevent denial-of-service attacks.
+The value -1 removes any limit.
+
+`NN_RECONNECT_IVL`::
+Reconnect interval in milliseconds.
+After an outgoing connection is closed or fails, the socket will automatically attempt to reconnect after this many milliseconds.
+This is the starting value for the time, and is used in the first reconnection attempt after a successful connection is made.
+The default is 100.
+
+`NN_RECONNECT_IVL_MAX`::
+Maximum reconnect interval in milliseconds.
+Subsequent reconnection attempts after a failed attempt are made at exponentially increasing intervals (back-off), but the interval is
+capped by this value.
+If this value is smaller than `NN_RECONNECT_IVL`, then no exponential back-off is performed, and each reconnect interval will be determined solely by `NN_RECONNECT_IVL`.
+The default is zero.
+
+`NN_LINGER`::
+This option is always zero and exists only for compatibility.footnote:[This option was unreliable in early releases of _libnanomsg_, and is unsupported in _NNG_ and recent _libnanomsg_ releases.
+Applications needing assurance of message delivery should either include an
+explicit notification (automatic with the `NN_REQ` protocol) or allow
+sufficient time for the socket to drain before closing the socket or exiting.]
+
+
+`NN_SNDPRIO`::
+This option is not implemented at this time.
+
+`NN_RCVPRIO`::
+This option is not implemented at this time.
+
+`NN_IPV4ONLY`::
+This option is not implemented at this time.
+
+`NN_SOCKET_NAME`::
+This option is a string, and represents the socket name.
+It can be changed to help with identifying different sockets with their different application-specific purposes.
+
+`NN_MAXTTL`::
+Maximum number of times a message may traverse devices or proxies.
+This value, if positive, provides some protection against forwarding loops in xref:nng_device.adoc[device] chains.footnote:[Not all protocols offer this protection, so care should still be used in configuring device forwarding.]
+
+`NN_DOMAIN`::
+This option of type `int` represents either the value `AF_SP` or `AF_SP_RAW`, corresponding to the value that the socket was created with.
+
+`NN_PROTOCOL`::
+This option option of type `int` contains the numeric protocol number that the socket is used with.
+
+`NN_RCVFD`::
+This option returns a file descriptor suitable for use in with `poll` or `select` (or other system-specific polling functions).
+This descriptor will be readable when a message is available for receiving at the socket.
+This option is of type `int` on all systems except Windows, where it is of type `SOCKET`.
+
+`NN_SNDFD`::
+This option returns a file descriptor suitable for use in with `poll` or `select` (or other system-specific polling functions).
+This descriptor will be readable when the socket is able to accept a message for sending.
+This option is of type `int` on all systems except Windows, where it is of type `SOCKET`.
+
+The following option is available for `NN_REQ` sockets using the `NN_REQ` level:
+
+`NN_REQ_RESEND_IVL`::
+Request retry interval in milliseconds.
+If an `NN_REQ` socket does not receive a reply to a request within this period of time, the socket will automatically resend the request.
+The default value is 60000 (one minute).
+
+The following option is available for `NN_SURVEYOR` sockets using the `NN_SURVEYOR` level:
+
+`NN_SURVEYOR_DEADLINE`::
+Survey deadline in milliseconds for `NN_SURVEYOR` sockets.
+After sending a survey message, the socket will only accept responses from respondents for this long.
+Any responses arriving after this expires are silently discarded.
+
+In addition, the following transport specific options are offered:
+
+`NN_IPC_SEC_ATTR`::
+This `NN_IPC` option is not supported at this time.
+
+`NN_IPC_OUTBUFSZ`::
+This `NN_IPC` option is not supported at this time.
+
+`NN_IPC_INBUFSZE`::
+This `NN_IPC` option is not supported at this time.
+
+`NN_TCP_NODELAY`::
+This `NN_TCP` option is not supported at this time.
+
+`NN_WS_MSG_TYPE`::
+This `NN_WS` option is not supported, as _NNG_ only supports binary messages.
+
+### 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
+
+xref:nng_socket.adoc[nng_socket],
+xref:nn_close.adoc[nn_close],
+xref:nn_errno.adoc[nn_errno],
+xref:nn_getsockopt.adoc[nn_getsockopt]
diff --git a/docs/ref/compat/nn_poll.adoc b/docs/ref/compat/nn_poll.adoc
new file mode 100644
index 00000000..889c6eaa
--- /dev/null
+++ b/docs/ref/compat/nn_poll.adoc
@@ -0,0 +1,68 @@
+## nn_poll
+
+Poll sockets (compatible API).
+
+### Synopsis
+
+```c
+#include <nanomsg/nn.h>
+
+#define NN_POLLIN  1
+#define NN_POLLOUT 2
+
+struct nn_pollfd {
+    int      fd;
+    uint16_t events;
+    uint16_t revents;
+};
+
+int nn_poll(struct nn_pollfd *pfds, int npfd, int timeout);
+```
+
+### Description
+
+The `nn_poll` function polls a group of sockets for readiness to send or receive.
+
+The array of _nfds_ sockets to poll for are passed into _pfds_.
+Each member of this array is initialized with the `fd` field set to the socket, and the `events` field set to a mask that can contain either or both of the flags `NN_POLLIN` and `NN_POLLOUT`.
+
+The flag `NN_POLLIN` indicates that a socket is ready for receiving without blocking (a message is available on the socket), and the flag `NN_POLLOUT` indicates that a socket is ready for sending without blocking.
+
+Upon success, the function returns the number of updates the `revents` field of each member of the _pfds_ array, setting it to indicate whether the requested status is true or not.
+
+NOTE: The `revents` field will only have a flag set if the corresponding flag was also set in the `events` field.
+
+If the _timeout_ field is positive, then this function will wait for up the that many milliseconds.
+If none of the requested events occurs before that timeout occurs, then the function will return -1 and set the error to `ETIMEDOUT`.
+
+If the _timeout_ is zero, then this function will return immediately, after updating the current status of the sockets.
+
+If the _timeout_ is -1, then the function waits forever, or until one of the requested events occurs.
+
+IMPORTANT: This function is only suitable for use with sockets obtained with the xref:nn_socket.adoc[`nn_socket`] function, and is not compatible with file descriptors obtained via any other means.
+This includes file descriptors obtained using the `NN_SNDFD` or `NN_RCVFD`
+options with xref:nn_getsockopt.adoc[`nn_getsockopt`]
+
+NOTE: This function is significantly less efficient than other polling or asynchronous I/O mechanisms, and is provided for API compatibility only.
+It's use is discouraged.
+
+NOTE: This function is *not* supported on systems other than POSIX derived platforms and Windows.
+
+### Return Values
+
+This function returns the number of sockets with events on success, or -1 on error.
+
+### Errors
+
+[horizontal]
+`ENOMEM`:: Insufficient memory available.
+`EBADF`:: One of the sockets is not open.
+`ETIMEDOUT`:: Operation timed out.
+`ENOTSUP`:: This function is not supported on this platform.
+
+### See Also
+
+xref:nn_errno.adoc[nn_errno],
+xref:nn_recv.adoc[nn_recv],
+xref:nn_send.adoc[nn_send],
+xref:nn_socket.adoc[nn_socket]
diff --git a/docs/ref/compat/nn_reallocmsg.adoc b/docs/ref/compat/nn_reallocmsg.adoc
new file mode 100644
index 00000000..7a1cb0ad
--- /dev/null
+++ b/docs/ref/compat/nn_reallocmsg.adoc
@@ -0,0 +1,36 @@
+## nn_reallocmsg
+
+Reallocate message (compatible API).
+
+### Synopsis
+
+```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_.
+
+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 returnedto 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
+
+xref:nn_allocmsg.adoc[nn_allocmsg],
+xref:nn_freemsg.adoc[nn_freemsg],
+xref:nn_errno.adoc[nn_errno]
diff --git a/docs/ref/compat/nn_recv.adoc b/docs/ref/compat/nn_recv.adoc
new file mode 100644
index 00000000..00329399
--- /dev/null
+++ b/docs/ref/compat/nn_recv.adoc
@@ -0,0 +1,44 @@
+## nn_recv
+
+Receive data (compatible API).
+
+### Synopsis
+
+```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.
+
+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 xref:nn_allocmsg.adoc[`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 takes responsibility for the final disposition of the message.
+
+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
+
+xref:nn_errno.adoc[nn_errno],
+xref:nn_recvmsg.adoc[nn_recvmsg],
+xref:nn_send.adoc[nn_send],
+xref:nn_socket.adoc[nn_socket]
\ No newline at end of file
diff --git a/docs/ref/compat/nn_recvmsg.adoc b/docs/ref/compat/nn_recvmsg.adoc
new file mode 100644
index 00000000..20918cbd
--- /dev/null
+++ b/docs/ref/compat/nn_recvmsg.adoc
@@ -0,0 +1,68 @@
+## nn_recvmsg
+
+Receive message (compatible API).
+
+### Synopsis
+
+```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 header described by _hdr_ using the socket _sock_.
+
+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:
+
+```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 xref:nn_freemsg.adoc[`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 currently only useful to obtain the message headers used with raw mode sockets.
+In all other circumstances these fields should be zero.
+Details about this structure are covered in xref:nn_cmsg.adoc[`nn_cmsg`].
+
+### 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
+
+xref:nn_cmsg.adoc[nn_cmsg],
+xref:nn_errno.adoc[nn_errno],
+xref:nn_recv.adoc[nn_recv],
+xref:nn_send.adoc[nn_send],
+xref:nn_socket.adoc[nn_socket]
diff --git a/docs/ref/compat/nn_send.adoc b/docs/ref/compat/nn_send.adoc
new file mode 100644
index 00000000..9cacd1d7
--- /dev/null
+++ b/docs/ref/compat/nn_send.adoc
@@ -0,0 +1,46 @@
+## nn_send
+
+Send data (compatible API).
+
+### Synopsis
+
+```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_.
+
+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 xref:nn_allocmsg.adoc[`nn_allocmsg`] or xref:nn_recvmsg.adoc[`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
+
+xref:nn_errno.adoc[nn_errno],
+xref:nn_recv.adoc[nn_recv],
+xref:nn_sendmsg.adoc[nn_sendmsg],
+xref:nn_socket.adoc[nn_socket]
\ No newline at end of file
diff --git a/docs/ref/compat/nn_sendmsg.adoc b/docs/ref/compat/nn_sendmsg.adoc
new file mode 100644
index 00000000..f3f3ebea
--- /dev/null
+++ b/docs/ref/compat/nn_sendmsg.adoc
@@ -0,0 +1,71 @@
+## nn_sendmsg
+
+Send message (compatible API).
+
+### Synopsis
+
+```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_.
+
+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:
+
+```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 xref:nn_allocmsg.adoc[`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 only useful to provide the message headers used with raw mode sockets.
+In all other circumstances these fields should be zero.
+Details about this structure are covered in xref:nn_cmsg.adoc[`nn_cmsg`].
+
+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
+
+xref:nn_cmsg.adoc[nn_cmsg],
+xref:nn_errno.adoc[nn_errno],
+xref:nn_recv.adoc[nn_recv],
+xref:nn_send.adoc[nn_send],
+xref:nn_socket.adoc[nn_socket]
diff --git a/docs/ref/compat/nn_setsockopt.adoc b/docs/ref/compat/nn_setsockopt.adoc
new file mode 100644
index 00000000..ddce6558
--- /dev/null
+++ b/docs/ref/compat/nn_setsockopt.adoc
@@ -0,0 +1,155 @@
+## nn_setsockopt
+
+Set socket option (compatible API).
+
+### Synopsis
+
+```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.
+
+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.footnote:[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 rounded 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 valueused here accordingly.]
+
+`NN_RCVBUF`::
+Receive buffer size in bytes. The same caveats for `NN_SNDBUF` apply here as well.
+
+`NN_SNDTIMEO`::
+Send time-out in milliseconds.
+Send operations will fail with `ETIMEDOUT` if no message can be received after this many milliseconds have transpired since the operation was started.
+A value of -1 means that no timeout is applied.
+
+`NN_RCVTIMEO`::
+Receive time-out in milliseconds.
+Receive operations will fail with `ETIMEDOUT` if no message can be received after this many milliseconds have transpired since the operation was started.
+A value of -1 means that no timeout is applied.
+
+`NN_RCVMAXSIZE`::
+Maximum receive size in bytes.
+The socket will discard messages larger than this on receive.
+The default, 1MB, is intended to prevent denial-of-service attacks.
+The value -1 removes any limit.
+
+`NN_RECONNECT_IVL`::
+Reconnect interval in milliseconds.
+After an outgoing connection is closed or fails, the socket will automatically attempt to reconnect after this many milliseconds.
+This is the starting value for the time, and is used in the first reconnection attempt after a successful connection is made.
+The default is 100.
+
+`NN_RECONNECT_IVL_MAX`::
+Maximum reconnect interval in milliseconds.
+Subsequent reconnection attempts after a failed attempt are made at exponentially increasing intervals (back-off), but the interval is capped by this value.
+If this value is smaller than `NN_RECONNECT_IVL`, then no exponential back-off is performed, and each reconnect interval will be determined solely by `NN_RECONNECT_IVL`.
+The default is zero.
+
+`NN_LINGER`::
+This option is ignored, and exists only for compatibility.footnote:[This option was unreliable in early releases of _libnanomsg_, and
+is unsupported in _NNG_ and recent _libnanomsg_ releases.
+Applications needing assurance of message delivery should either include an
+explicit notification (automatic with the `NN_REQ` protocol) or allow
+sufficient time for the socket to drain before closing the socket or exiting.]
+
+`NN_SNDPRIO`::
+This option is not implemented at this time.
+
+`NN_RCVPRIO`::
+This option is not implemented at this time.
+
+`NN_IPV4ONLY`::
+This option is not implemented at this time.
+
+`NN_SOCKET_NAME`::
+This option is a string, and represents the socket name.
+It can be changed to help with identifying different sockets with their different application-specific purposes.
+
+`NN_MAXTTL`::
+Maximum number of times a message may traverse devices or proxies.
+This value, if positive, provides some protection against forwarding loops in xref:nn_device.adoc[device] chains.
+
+NOTE: Not all protocols offer this protection, so care should still be used in configuring device forwarding.
+
+The following option is available for `NN_REQ` sockets using the `NN_REQ` level:
+
+`NN_REQ_RESEND_IVL`::
+Request retry interval in milliseconds.
+If an `NN_REQ` socket does not receive a reply to a request within this period of time, the socket will automatically resend the request.
+The default value is 60000 (one minute).
+
+The following options are available for `NN_SUB` sockets using the `NN_SUB` level:
+
+`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.
+
+The following option is available for `NN_SURVEYOR` sockets using the `NN_SURVEYOR` level:
+
+`NN_SURVEYOR_DEADLINE`::
+Survey deadline in milliseconds for `NN_SURVEYOR` sockets.
+After sending a survey message, the socket will only accept responses from respondents for this long.
+Any responses arriving after this expires are silently discarded.
+
+In addition, the following transport specific options are offered:
+
+`NN_IPC_SEC_ATTR`::
+This `NN_IPC` option is not supported at this time.
+
+`NN_IPC_OUTBUFSZ`::
+This `NN_IPC` option is not supported at this time.
+
+`NN_IPC_INBUFSZE`::
+This `NN_IPC` option is not supported at this time.
+
+`NN_TCP_NODELAY`::
+This `NN_TCP` option is not supported at this time.
+
+`NN_WS_MSG_TYPE`::
+This `NN_WS` option is not supported at this time.
+
+### 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
+
+xref:nng_socket.adoc[nng_socket],
+xref:nn_close.adoc[nn_close],
+xref:nn_errno.adoc[nn_errno],
+xref:nn_getsockopt.adoc[nn_getsockopt]
\ No newline at end of file
diff --git a/docs/ref/compat/nn_shutdown.adoc b/docs/ref/compat/nn_shutdown.adoc
new file mode 100644
index 00000000..cb3f1c63
--- /dev/null
+++ b/docs/ref/compat/nn_shutdown.adoc
@@ -0,0 +1,34 @@
+## nn_shutdown
+
+Shut down endpoint (compatible API).
+
+### Synopsis
+
+```c
+#include <nanomsg/nn.h>
+
+int nn_shutdown(int sock, int ep)
+```
+
+### Description
+
+The `nn_shutdown` shuts down the endpoint _ep_, which is either a listener or a dialer, 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.
+
+### 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
+
+xref:nn_bind.adoc[nn_bind],
+xref:nn_connect.adoc[nn_connect],
+xref:nn_errno.adoc[nn_errno],
+xref:nn_socket.adoc[nn_socket]
\ No newline at end of file
diff --git a/docs/ref/compat/nn_socket.adoc b/docs/ref/compat/nn_socket.adoc
new file mode 100644
index 00000000..d5e88652
--- /dev/null
+++ b/docs/ref/compat/nn_socket.adoc
@@ -0,0 +1,54 @@
+## nn_socket
+
+Create socket (compatible API).
+
+### Synopsis
+
+```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.
+
+The address family _af_ can be one of two values:
+
+[horizontal]
+`AF_SP`:: Normal socket.
+`AF_SP_RAW`:: Raw mode socket.
+
+The protocol indicates the protocol to be used when creating the socket.
+The following protocols are defined:
+
+[horizontal]
+`NN_PAIR`:: xref:nng_pair.adoc[Pair] protocol.
+`NN_PUB`:: xref:nng_pub.adoc[Publisher] protocol.
+`NN_SUB`:: xref:nng_sub.adoc[Subscriber] protocol.
+`NN_REQ`:: xref:nng_req.adoc[Requestor] protocol.
+`NN_REP`:: xref:nng_rep.adoc[Replier] protocol.
+`NN_PUSH`:: xref:nng_push.adoc[Push] protocol.
+`NN_PULL`:: xref:nng_pull.adoc[Pull] protocol.
+`NN_SURVEYOR`:: xref:nng_surveyor.adoc[Surveyor] protocol.
+`NN_RESPONDENT`:: xref:nng_respondent.adoc[Respondent] protocol.
+`NN_BUS`:: xref:nng_bus.adoc[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
+
+xref:nng_socket.adoc[nng_socket],
+xref:nn_close.adoc[nn_close],
+xref:nn_errno.adoc[nn_errno]
\ No newline at end of file
diff --git a/docs/ref/compat/nn_strerror.adoc b/docs/ref/compat/nn_strerror.adoc
new file mode 100644
index 00000000..74cc832f
--- /dev/null
+++ b/docs/ref/compat/nn_strerror.adoc
@@ -0,0 +1,24 @@
+## 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_.
+
+### Return Values
+
+This function returns the message corresponding to _err_.
+
+### See Also
+
+xref:nn_errno.adoc[nn_errno]
\ No newline at end of file
diff --git a/docs/ref/compat/nn_term.adoc b/docs/ref/compat/nn_term.adoc
new file mode 100644
index 00000000..45ffa702
--- /dev/null
+++ b/docs/ref/compat/nn_term.adoc
@@ -0,0 +1,26 @@
+## nn_term
+
+Terminate library (compatible API).
+
+### Synopsis
+
+```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`.
+
+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.
+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.
+
+### See Also
+
+xref:nn_errno.adoc[nn_errno],
+xref:nn_socket.adoc[nn_socket]
\ No newline at end of file