pollbunch(3C) pollbunch(3C)
NAME
pollbunch, pollwhich - multiplex input/output: more powerful version
of the poll(2) system call
SYNOPSIS
#include <stropts.h>
#include <poll.h>
int pollbunch(int cmd, struct nppollfd *fds);
int pollwhich(struct nppollfd *fds, sizet nfds, int timeout);
DESCRIPTION
pollbunch and pollwhich offer users a powerful mechanism for multi-
plexing input/output via a set of file descriptors that reference open
files. pollbunch/pollwhich is to be recommended over poll(2) for
applications with a large number of files to be multiplexed with rela-
tively low individual event rates.
This new mechanism offers a more efficient event status query than
poll(2). With poll(2), the entire list of file descriptors must be
transferred as an argument each time, even if this list is rarely
modified and even then few changes made. The same size list is
returned by poll(2) as an event, even if it only contains a few files
with "active" events. The application must then find out the location
of these file descriptors in the list by reading through it in
sequence.
The division of the poll(2) system call into the two system calls
pollbunch and pollwhich separates the administrative part from the
actual event status query, and by using the asynchrony of the events
allows the synchronous proportion of time during the actual event
status query to be limited to the file descriptors for which an event
already occurred. Only these file descriptors are returned as an
event. This reduces the copying time between kernel and application
and avoids the long, sequential program runs through all specified
file descriptors both in the kernel and the application. This results
in better response times in the application and an off-loading of the
CPU.
The event status event list also supplies the events in the chronolog-
ical order in which they occurred. This means that special processing
on the part of the application to make sure that no file descriptors
are discriminated against is unnecessary.
Page 1 Reliant UNIX 5.44 Printed 11/98
pollbunch(3C) pollbunch(3C)
The nppollfd structure is used to transfer file descriptors and
events following poll(2) and contains the following:
int fd; /* file descriptor */
short events; /* requested or returned events */
unsigned short userref; /* transparent user argument */
fd specifies an open file descriptor and the events field is a bitmask
constructed by an ORing of any combination of the following event
flags, as in poll(2):
POLLIN
Data other than high priority can be read without blocking. This
option is also set for STREAMS if the message is of zero length.
POLLRDNORM
Normal data (priority = 0) can be read without blocking. This
option is also set for STREAMS if the message is of zero length.
POLLRDBAND
Data with a non-zero priority can be read without blocking. This
option is also set for STREAMS if the message is of zero length.
POLLPRI
High priority data can be read without blocking. This option is
also set for STREAMS if the message is of zero length.
POLLOUT
Normal data can be written without blocking.
POLLWRNORM
Like POLLOUT.
POLLWRBAND
Data with a non-zero priority class can be written. This event
only checks classes that have been written at least once.
POLLMSG
An MSIG message or MPCSIG message containing a ASIGPOLL signal
reached the top of the stream head queue.
POLLERR
There is an error message on the stream or device. This flag is
only valid in the events bitmask in pollwhich; it is not used in
the events field for pollbunch.
POLLHUP
A hangup occurred in the stream. This event and POLLOUT are mutu-
ally exclusive; a stream can never be writable if a hangup
occurred. However this event and POLLIN or POLLPRI are not mutu-
ally exclusive. This flag is only valid in the events bitmask for
pollwhich; it is not used in the events field for pollbunch.
Page 2 Reliant UNIX 5.44 Printed 11/98
pollbunch(3C) pollbunch(3C)
POLLNVAL
The specified fd value does not belong to an open file. This flag
is only valid in the events field for pollwhich; it is not used
in the events field for pollbunch.
The layout of the events field is different for pollbunch and for
pollwhich.
POLLBUNCH
pollbunch is for the construction and manipulation of a list of
relevant file descriptors and their respective events within a kernel.
Using a pollbunch, a single file descriptor can be inserted or
deleted, or its events can be modified. The respective action is
specified by cmd. fds is a pointer for the nppollfd structure con-
taining the file descriptor and its events:
Permitted values for cmd are:
NPBADD
Incorporates the fd file descriptor with the events into the list
of relevant file descriptors. This means that consequent asyn-
chronous events for this file descriptor are marked and displayed
by pollwhich. The contents of userref in the nppollfd structure
are transferred transparently and saved within this file descrip-
tor. The nppollfd structure is unchanged when you return from
pollbunch.
NPBREM
Deletes the fd file descriptor from the list of relevant file
descriptors. This means that no more consequent events are noted
for this file descriptor and the pollwhich file descriptor is no
longer displayed. The events and userref fields in the nppollfd
structure are not evaluated. The nppollfd structure is unchanged
when you return from pollbunch.
NPBMODIFY
Changes the events for the existing fd file descriptor. The
events value from the nppollfd structure overwrites the value in
the kernel. The userref field in the nppollfd structure is not
evaluated. The nppollfd structure is unchanged when you return
from pollbunch.
Page 3 Reliant UNIX 5.44 Printed 11/98
pollbunch(3C) pollbunch(3C)
pollbunch is unsuccessful if one or more of the following occurs:
EAGAIN Indicates that an internal data structure was unsuccessful.
The request should nevertheless be attempted again.
EBADF fd is not a valid file descriptor in the nppollfd struc-
ture.
EEXIST fd in the nppollfd structure (NPBADD) specifies a file
descriptor that is already contained in the list of
relevant file descriptors.
EFAULT An argument is a pointer to a storage space outside the
indicated address area.
EINVAL cmd contains an invalid action.
events in the nppollfd structure (NPBADD, NPBMODIFY)
either contain no events or invalid events.
ENOENT fd in the nppollfd structure (NPBREM, NPBMODIFY)
specifies a file descriptor that is not contained in the
list of relevant file descriptors.
RESULT
The value 0 is returned after the successful termination of pollbunch.
Otherwise -1 is returned and errno is set to display the error.
POLLWHICH
pollwhich supplies the file descriptors in which one or more events
occurred. The results of the pollwhich query are saved in the events
field in the nppollfd structure. Bits are set in the events bitmask
to display which of the requested events are true.
pollwhch displays the maximum number of nppollfd structures in the
fds vector as were specified by nfds. fds points to an address book
with a size of at least nfds nppollfd structures.
If a number of file descriptors are displayed in fds, the sequence of
the nppollfd structure corresponds to the chronological sequence in
which each event occurred. If a number of events were specified for a
file descriptor and some of them are parallel, the position of the
corresponding nppollfd structure within fds is determined by the time
when the first event occurred for this file descriptor.
The options POLLHUP, POLLERR, and POLLNVAL which display events are
always set in the events field if the conditions displays by you are
true, this also happens if they were not in the events field in
pollbunch.
pollwhich only considers those file descriptors that were previously
specified by pollbunch.
Page 4 Reliant UNIX 5.44 Printed 11/98
pollbunch(3C) pollbunch(3C)
The userref field contains the value that was specified in the corre-
sponding pollbunch.
If none of the defined events occur in one of the selected file
descriptors, pollwhich waits at least timeout milliseconds for an
error to occur in one of the selected file descriptors. On a computer
where the timing facility is not exact to the millisecond, timeout is
rounded up to the next permitted value available in the system. If the
value of timeout is 0, pollwhich is returned immediately. If the value
of timeout is equal to INFTIM (or -1), pollwhich causes a block until
a queried event occurs, or until the call is terminated. pollwhich is
not affected by the ONDELAY and ONONBLOCK flags.
pollwhich is unsuccessful if one or more of the following occurs:
EAGAIN Indicates that an internal data structure was unsuccessful.
The request should nevertheless be attempted again.
EFAULT An argument points to a storage space outside the indi-
cated address area.
EINTR A signal was intercepted during a pollwhich system call.
EINVAL The nfds argument is less than 0 or greater than OPENMAX.
ENOENT No list of relevant file descriptors exists. pollbunch was
probably not executed previous to this.
RESULT
A nonnegative result is returned when pollwhich is terminated success-
fully. A positive value displays the total number of valid nppollfd
structures (i.e. that can be evaluated). All further structures (up to
nfds) then contain undefined (or the old) values.
0 shows that the call has been timed out and no file descriptor was
selected.
If the process is unsuccessful, -1 is returned and errno is set to
display the error.
SEE ALSO
getmsg(2), getrlimit(2), poll(2), putmsg(2), read(2), write(2).
Programmer's Guide: STREAMS.
Page 5 Reliant UNIX 5.44 Printed 11/98