poll(7)poll(7)NAMEpoll - device for high speed poll on file descriptors
SYNOPSIS
#include <stropts.h>
#include <poll.h>
#include <sys/devpoll.h>
DESCRIPTION
/dev/poll is a pseudo device that allows users to efficiently monitor
large numbers of file descriptors. /dev/poll works similarly to the poll
system call and to the Sun Solaris version of the device except as noted
below. File descriptors to be polled are registered and scanned with the
write and ioctl system calls respectively.
Registration of file descriptors is done by writing an array of pollfd
structures to the /dev/poll device. These structures are handled the
same as in poll and contain the following fields:
int fd; /* file descriptor */
short events; /* requested events */
short revents; /* returned events */
The array of passed pollfds are scanned serially and cached within the
/dev/poll device. If a previously cached pollfd is found referencing the
same file descriptor their events fields are logically OR'd together.
Users wishing to maintain separate sets of registered pollfd structures
should open separate instances of the /dev/poll device. The write call
returns the number of bytes written or -1 and an error code. Following a
pollfd's registration, the device watches for the events specified in the
structure's events field to occur to the file descriptor specified in the
structure's fd field.
Event notification is received through the ioctl system call using the
DP_POLL command with a pointer to a dvpoll structure as its argument.
The dvpoll structure has the following fields:
struct pollfd * dp_fds; /* pollfd array */
nfds_t dp_nfds; /* Number of pollfds at dp_fds */
int dp_timeout; /* Time-out in milliseconds */
dp_fds is an array to which up to dp_nfds pollfds with active events will
be copied by the device. Each copied pollfd's revents field will include
those events in the events field that are active. Each pollfd's fd field
will be set to the file descriptor that it was monitoring, and its events
field will be set to the events that it's watching for. If no active
events are found, the call will block for the length of time in
dp_timeout. If dp_timeout is 0 then the call will immediately return.
If dp_timeout is -1 then the call will block until a registered event
does become active. If dp_timeout is greater than 0 then it will block
for that many milliseconds unless an event becomes active. The ioctl
Page 1
poll(7)poll(7)
will return either the number of pollfds received, or -1 if an error
occurred.
A user can unregister pollfds from the device's poll set by adding the
POLLREMOVE flag to the events field of a pollfd and writing it to the
device. Users wishing to remove flags from the events field of a
registered pollfd should write two pollfds to the device; the first
should remove the pollfd with the POLLREMOVE flag and the second should
re-add the pollfd with the new set of desired flags.
When a monitored file descriptor is closed, all /dev/poll instances that
had pollfds registered to monitor it will stop monitoring the file. The
pollfds will remain cached in the /dev/poll device and can be removed
with the POLLREMOVE flag as described above. If a new file or socket is
opened with a file descriptor that is the same as a previously closed
file or socket that had a registered pollfd that is still cached in a
/dev/poll instance, the registered pollfd will not monitor the new file
or socket. If a pollfd is written to one of these /dev/poll instances to
monitor this new file or socket, it will overwrite the no longer used
previous pollfd.
Users may use the DP_REMOVE ioctl command on a /dev/poll instance to
direct the device to try to remove cached pollfds from the device
instance whenever the file descriptor that they are watching is closed.
The device instance will only attempt this while doing other work and it
may not always be successful.
Users may use the DP_ISPOLLED ioctl command with a pollfd as the argument
to check if the file descriptor specified in the pollfds fd field is part
of the poll set for the /dev/poll instance queried. The ioctl returns 1
if the file descriptor is part of the poll set, and returns the currently
polled events in the pollfd's revents field. The call returns 0 if the
file descriptor is not being polled and -1 if there was an error.
When a program with an open instance of /dev/poll issues the fork system
call to create a child process, or sproc to create a child with a non-
shared file descriptor table, any attempts by the child to write or use
ioctl on the instance will fail with the EACCES error code. It is
suggested that child processes close the instance and open a new one.
When the last open reference to an instance is closed, all cached pollfds
will be removed as well.
NOTES
In the Sun Solaris version of /dev/poll, when a file descriptor is closed
that has /dev/poll pollfds monitoring it, and a new file is opened with
the same file descriptor, the pollfds will switch to monitor the new
file. The IRIX version is different in that the pollfds will not switch
to monitor the new file descriptor. They will remain dormant in their
/dev/poll instances until they are overwritten with new pollfds
referencing the file descriptor or they are removed with POLLREMOVE.
Page 2
poll(7)poll(7)HISTORY
The /dev/poll device was added in IRIX 6.5.15.
SEE ALSOfork(2), ioctl(2), poll(2), sproc(2), write(2).
Page 3
