poll(7)poll(7)NAME
poll, devpoll.h - Device driver for a fast poll on many file descrip‐
tors
SYNOPSIS
#include <sys/devpoll.h>
DESCRIPTION
The /dev/poll driver supports the monitoring of one or more sets of
file descriptors. Access to the /dev/poll driver is supported through
the open(), write(), and ioctl() functions. By using open(), write(),
and ioctl() calls with the /dev/poll driver, an application can poll
large numbers of file descriptors more efficiently than by using poll()
and select() calls.
Creating a Poll Set
Applications create a set of file descriptors to be monitored by open‐
ing the /dev/poll driver and then writing an array of pollfd structures
to the driver. The open() call on the driver returns the file descrip‐
tor that identifies the poll set. To monitor multiple sets of file
descriptors, the application must open the driver multiple times to
retrieve different poll set descriptors.
Each entry in the array written to the driver is a pollfd structure,
which is defined in sys/poll.h:
struct pollfd {
int fd;
short events;
short revents; }
In this structure: Specifies the file descriptor being polled. Speci‐
fies the events to be monitored for this file descriptor. Flags that
can be specified for the events field are the same as those used with
the poll() system call. See poll(2) for information about these flags.
The /dev/poll driver supports one additional flag, POLLREMOVE,
which is described in Removing a File Descriptor From a Poll
Set.
If the buffer array written to the driver contains more than one
pollfd entry with the same fd value, the last pollfd entry for
that fd will be used for the value of events. If a previous
write operation created a pollfd entry that contains the same fd
value as an entry written by a new write operation, the events
value from the new write operation overwrites the old events
value. Not used for poll set creation.
This field is used with the ioctl() function's DP_POLL request.
For more information, see Monitoring Events for Poll Set Members
(DP_POLL Ioctl).
Removing a File Descriptor From a Poll Set
To remove a file descriptor from a poll set, the application writes to
the driver a pollfd entry in which fd is set to the file descriptor
being removed and events is set to POLLREMOVE.
Monitoring Events for Poll Set Members (DP_POLL Ioctl)
Applications retrieve events for file descriptors in a poll set by
using an ioctl() call that contains the following arguments: The file
descriptor for the poll set (returned when the driver was opened).
DP_POLL A pointer to the dvpoll structure
The dvpoll structure is defined in <sys/devpoll.h> as follows:
struct dvpoll {
struct pollfd * dp_fds;
int dp_nfds;
int dp_timeout; }
In this structure: Points to an array of returned pollfd structures as
described in Creating a Poll Set. Specifies the number of pollfd
structures to be returned.
The application can set the dp_nfds value lower than the number
of file descriptors in the poll set when there is a need to
limit the number of file descriptors for which information is
gathered. The number of miliseconds to wait before returning if
none of the events being monitored for the file descriptors in
the poll set have occurred.
If the application sets dp_timeout to -1, the ioctl() call
blocks until an event occurs or the call in interrupted. If the
application sets dp_timeout to 0, the call returns immediately.
The ioctl() call with a DP_POLL request returns the following: Success.
This value is the number of valid pollfd entries that are returned into
the array pointed to by dp_fds. For each valid entry in this array:
Indicates the file descriptor polled. Indicates the events being moni‐
tored by the application for that file descriptor. Indicates which of
those events, if any, occurred. See poll(2) for descriptions of flag
values that can be returned to this field.
The contents of the rest of the buffer are undefined. The call
timed out. In this case, the content of the array pointed to by
dp_fds is not modified. An error occurred. In this case, errno
is set to indicate the error.
Querying a Poll Set for a File Descriptor (DP_ISPOLLED Ioctl)
To determine if a file descriptor is already a member of a poll set,
applications call ioctl() with DP_ISPOLLED as the request argument. The
fildes and arg arguments are the same as for the DP_POLL request as
described in Monitoring Events for Poll Set Members (DP_POLL Ioctl).
Before the call is made, the application sets the fd field of the
pollfd entry in the array pointed to by arg to the value of the file
descriptor being queried.
An ioctl() call with a DP_ISPOLLED request returns the following: The
file descriptor is a member of the poll set. In this case, the events
field of the pollfd entry is modified to indicate the events being mon‐
itored for that file descriptor. The file descriptor is not a member
of the poll set. In this case, the pollfd entry for the file descriptor
is not modified. An error occurred. In this case, errno is set to
indicate the error.
RESTRICTIONS
The poll() and select() functions cannot be used with the /dev/poll
driver.
EXAMPLES
The following code fragment shows how to create a poll set and query
events that occurred for its members:
{
...
/*
* open the driver
*/
if ((dfd = open("/dev/poll", O_RDWR)) < 0) {
exit(-1);
}
pollfd = (struct pollfd* )malloc(sizeof(struct pollfd) *
MAXBUF);
if (pollfd == NULL) {
close(dfd);
exit(-1);
}
/*
* initialize buffer
*/
for (i = 0; i < MAXBUF; i++) {
pollfd[i].fd = fds[i];
pollfd[i].events = POLLIN;
pollfd[i].revents = 0;
}
if (write(dfd, &pollfd[0], sizeof(struct pollfd) * MAXBUF)
!=
sizeof(struct pollfd) * MAXBUF) {
perror("failed to write all pollfds");
close (dfd);
free(pollfd);
exit(-1);
}
/*
* read from the /dev/poll driver
*/
dopoll.dp_timeout = -1;
dopoll.dp_nfds = MAXBUF;
dopoll.dp_fds = pollfd;
result = ioctl(dfd, DP_POLL, &dopoll);
if (result < 0) {
perror("/dev/poll ioctl DP_POLL failed");
close (dfd);
free(pollfd);
exit(-1);
}
for (i = 0; i < result; i++) {
read(dopoll.dp_fds[i].fd, rbuf, STRLEN);
}
... } The following code fragment shows how to determine
if a file descriptor is a member of a poll set and how to remove
the file descriptor from the set:
... main(argc,argv ) char **argv[]; int argc; {
int fid;
int fid2;
struct pollfd upoll;
int i;
int nfid;
int error;
struct dvpoll dvp;
fid = open( "/dev/poll", O_RDWR, 0);
fid2 = open( "/dev/poll", O_RDWR, 0);
for (i=0; i< 512; i++) {
nfid = open( "/dev/null", O_RDWR, 0);
upoll.fd=nfid;
upoll.events=POLLNORM;
if (write(fid, &upoll, sizeof(struct pollfd)) < 0)
perror("write");
if (write(fid2, &upoll, sizeof(struct pollfd)) < 0)
perror("write");
}
upoll.fd= 400;
upoll.events= 888;
upoll.revents= 999;
error = ioctl(fid , DP_ISPOLLED, &upoll);
printf("%d %d %d %d\n", error, upoll.fd, upoll.events,
upoll.revents);
upoll.fd=400;
upoll.events=POLLREMOVE;
if (write(fid, &upoll, sizeof(struct pollfd)) < 0)
perror("write");
. . .
close(fid); }
ERRORS
For error information, see the reference pages for the system calls
discussed in this reference page.
FILES
Device special file for the fast poll driver.
SEE ALSO
Functions: ioctl(2), open(2), poll(2), select(2), write(2)poll(7)