'\" t
.\"     Title: nn_poll
.\"    Author: [see the "AUTHOR(S)" section]
.\" Generator: Asciidoctor 2.0.20
.\"      Date: 2024-02-21
.\"    Manual: nanomsg 1.2.1
.\"    Source: \ \&
.\"  Language: English
.\"
.TH "NN_POLL" "3" "2024-02-21" "\ \&" "nanomsg 1.2.1"
.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 a set of SP sockets for readability and/or writability
.SH "SYNOPSIS"
.sp
\fB#include <nanomsg/nn.h>\fP
.sp
\fBint nn_poll (struct nn_pollfd *fds, int nfds, int timeout);\fP
.SH "DESCRIPTION"
.sp
The function checks a set of SP socket and reports whether it\(cqs possible to
send a message to the socket and/or receive a message from each socket.
.sp
\fIfds\fP argument is an array of nn_pollfd structures with \fInfds\fP argument
specifying the size of the array:
.sp
.if n .RS 4
.nf
.fam C
struct nn_pollfd {
    int fd;
    short events;
    short revents;
};
.fam
.fi
.if n .RE
.sp
Each entry in the array represents an SP socket to check. \fIevents\fP field
specifies which events to check for. The value is a bitwise combination of
the following values:
.sp
\fBNN_POLLIN\fP
.RS 4
Check whether at least one message can be received from the \fIfd\fP socket without
blocking.
.RE
.sp
\fBNN_POLLOUT\fP
.RS 4
Check whether at least one message can be sent to the \fIfd\fP socket without
blocking.
.RE
.sp
After the function returns, \fIrevents\fP field contains bitwise combination of
NN_POLLIN and NN_POLLOUT according to whether the socket is readable or
writable.
.sp
\fItimeout\fP parameter specifies how long (in milliseconds) should the function
block if there are no events to report.
.SH "RETURN VALUE"
.sp
Upon successful completion, the number of nn_pollfds structures with events
signaled is returned. In case of timeout, return value is 0. In case of error,
\-1 is returned and \fIerrno\fP is set the one of the values below.
.SH "ERRORS"
.sp
\fBEBADF\fP
.RS 4
Some of the provided sockets are invalid.
.RE
.sp
\fBEINTR\fP
.RS 4
The operation was interrupted by delivery of a signal before the message was
sent.
.RE
.sp
\fBETERM\fP
.RS 4
The library is terminating.
.RE
.SH "NOTE"
.sp
nn_poll is a convenience function. You can achieve same behaviour by using
NN_RCVFD and NN_SNDFD socket options. However, using the socket options
allows for usage that\(cqs not possible with nn_poll, such as simultaneous polling
for both SP and OS\-level sockets, integration of SP sockets with external event
loops etc.
.SH "EXAMPLE"
.sp
.if n .RS 4
.nf
.fam C
struct nn_pollfd pfd [2];
pfd [0].fd = s1;
pfd [0].events = NN_POLLIN | NN_POLLOUT;
pfd [1].fd = s2;
pfd [1].events = NN_POLLIN;
rc = nn_poll (pfd, 2, 2000);
if (rc == 0) {
    printf ("Timeout!");
    exit (1);
}
if (rc == \-1) {
    printf ("Error!");
    exit (1);
}
if (pfd [0].revents & NN_POLLIN) {
    printf ("Message can be received from s1!");
    exit (1);
}
.fam
.fi
.if n .RE
.SH "SEE ALSO"
.sp
nn_socket(3)
nn_getsockopt(3)
nanomsg(7)
.SH "AUTHORS"
.sp
.MTO "sustrik\(at250bpm.com" "Martin Sustrik" ""