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.

3 files changed, 108 insertions, 3 deletions

diff --git a/docs/man/nn_getsockopt.3compat.adoc b/docs/man/nn_getsockopt.3compat.adoc
index 04c024bc..f4988093 100644
--- a/docs/man/nn_getsockopt.3compat.adoc
+++ b/docs/man/nn_getsockopt.3compat.adoc
@@ -148,15 +148,19 @@ 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`.
 
 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`::
+`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`.
 
 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.
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)>>
diff --git a/docs/man/nng_compat.3compat.adoc b/docs/man/nng_compat.3compat.adoc
index 5493e41f..9029fb05 100644
--- a/docs/man/nng_compat.3compat.adoc
+++ b/docs/man/nng_compat.3compat.adoc
@@ -63,7 +63,7 @@ ifndef::backend-pdf[]
 `<<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_poll.3compat#,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
@@ -89,7 +89,7 @@ ifdef::backend-pdf[]
 |`<<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_poll.3compat#,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