'\" t
.\"     Title: nn_poll
.\"    Author: [see the "AUTHOR(S)" section]
.\" Generator: Asciidoctor 2.0.26
.\"      Date: 2021-02-08
.\"    Manual: NNG Reference Manual
.\"    Source: \ \&
.\"  Language: English
.\"
.TH "NN_POLL" "3compat" "2021-02-08" "\ \&" "NNG Reference Manual"
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.ss \n[.ss] 0
.nh
.ad l
.de URL
\fI\\$2\fP <\\$1>\\$3
..
.als MTO URL
.if \n[.g] \{\
.  mso www.tmac
.  am URL
.    ad l
.  .
.  am MTO
.    ad l
.  .
.  LINKSTYLE blue R < >
.\}
.SH "NAME"
nn_poll \- poll sockets (compatible API)
.SH "SYNOPSIS"
.sp
.if n .RS 4
.nf
.fam 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);
.fam
.fi
.if n .RE
.SH "DESCRIPTION"
.sp
The \f(CRnn_poll()\fP function polls a group of sockets for readiness to send or receive.
.if n .sp
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
.B Note
.ps -1
.br
.sp
This function is provided for API
compatibility with legacy \fIlibnanomsg\fP.
Consider using the relevant modern API instead.
.sp .5v
.RE
.sp
The array of \fInfds\fP sockets to poll for are passed into \fIpfds\fP.
Each member of this array is initialized with the \f(CRfd\fP field set to
the socket, and the \f(CRevents\fP field set to a mask that can contain either or both
of the flags \f(CRNN_POLLIN\fP and \f(CRNN_POLLOUT\fP.
.sp
The flag \f(CRNN_POLLIN\fP indicates that a socket is ready for receiving without
blocking (a message is available on the socket), and the flag \f(CRNN_POLLOUT\fP
indicates that a socket is ready for sending without blocking.
.sp
Upon success, the function returns the number of updates the \f(CRrevents\fP
field of each member of the \fIpfds\fP array, setting it to indicate
whether the requested status is true or not.
.if n .sp
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
.B Note
.ps -1
.br
.sp
The \f(CRrevents\fP field will only have a flag set if the corresponding
flag was also set in the \f(CRevents\fP field.
.sp .5v
.RE
.sp
If the \fItimeout\fP 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 \f(CRETIMEDOUT\fP.
.sp
If the \fItimeout\fP is zero, then this function will return immediately,
after updating the current status of the sockets.
.sp
If the \fItimeout\fP is \-1, then the function waits forever, or until one of the
requested events occurs.
.if n .sp
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
.B Important
.ps -1
.br
.sp
This function is only suitable for use with sockets obtained with the
\f(CRnn_socket()\fP function, and is not compatible
with file descriptors obtained via any other means.
This includes file descriptors obtained using the \f(CRNN_SNDFD\fP or \f(CRNN_RCVFD\fP
options with \f(CRnn_getsockopt()\fP
.sp .5v
.RE
.if n .sp
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
.B Note
.ps -1
.br
.sp
This function is significantly less efficient than other polling
or asynchronous I/O mechanisms, and is provided for API compatibility only.
It\(cqs use is discouraged.
.sp .5v
.RE
.if n .sp
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
.B Note
.ps -1
.br
.sp
This function is \fBnot\fP supported on systems other than POSIX derived
platforms and Windows.
.sp .5v
.RE
.SH "RETURN VALUES"
.sp
This function returns the number of sockets with events on success, or \-1 on error.
.SH "ERRORS"
.sp
\f(CRENOMEM\fP
.RS 4
Insufficient memory available.
.RE
.sp
\f(CREBADF\fP
.RS 4
One of the sockets is not open.
.RE
.sp
\f(CRETIMEDOUT\fP
.RS 4
Operation timed out.
.RE
.sp
\f(CRENOTSUP\fP
.RS 4
This function is not supported on this platform.
.RE
.SH "SEE ALSO"
.sp
nn_errno(3compat),
nn_recv(3compat),
nn_send(3compat),
nn_socket(3compat),
nn_compat(3compat),
nng(7)