fixes #344 nn_poll() legacy API missing

This includes the test from legacy libnanomsg and a man page.

We have refactored the message queue notification system so
that it uses nni_pollable, leading we hope to a more consistent
system, and reducing the code size and complexity.

We also fixed the size of the NN_RCVFD and NN_SNDFD so that they
are a SOCKET on Windows systems, rather than an integer.  This
addresses 64-bit compilation problems.

1 files changed, 101 insertions, 0 deletions

diff --git a/docs/man/nn_poll.3compat.adoc b/docs/man/nn_poll.3compat.adoc
new file mode 100644
index 00000000..0a1f02e6
--- /dev/null
+++ b/docs/man/nn_poll.3compat.adoc
@@ -0,0 +1,101 @@
+= nn_poll(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_poll - poll sockets (compatible API)
+
+== SYNOPSIS
+
+[source, 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.
+
+NOTE: This function is provided for API
+<<nng_compat.3compat#,compatibility>> with legacy _libnanomsg_.
+Consider using the relevant <<libnng.3#,modern API>> instead.
+
+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 avaiable 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.
+
+WARNING: This function is only suitable for use with sockets obtained with the
+`<<nn_socket.3compat#,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 `<<nn_getsockopt.3compat#,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
+
+<<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)>>