103 lines
3.3 KiB
Text
103 lines
3.3 KiB
Text
|
= 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
|
||
|
|
xref:nng_compat.3compat.adoc[compatibility] with legacy _libnanomsg_.
|
||
|
|
Consider using the relevant xref:libnng.3.adoc[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 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.3compat.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.3compat.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
|
||
|
|
|
||
|
|
[.text-left]
|
||
|
|
xref:nn_errno.3compat.adoc[nn_errno(3compat)],
|
||
|
|
xref:nn_recv.3compat.adoc[nn_recv(3compat)],
|
||
|
|
xref:nn_send.3compat.adoc[nn_send(3compat)],
|
||
|
|
xref:nn_socket.3compat.adoc[nn_socket(3compat)],
|
||
|
|
xref:nng_compat.3compat.adoc[nn_compat(3compat)],
|
||
|
|
xref:nng.7.adoc[nng(7)]
|