 |
Index for
Section 7 |
|
 |
Alphabetical
listing for P |
|
 |
Bottom of
page |
|
poll(7)
NAME
poll, devpoll.h - Device driver for a fast poll on many file descriptors
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 opening
the /dev/poll driver and then writing an array of pollfd structures to the
driver. The open() call on the driver returns the file descriptor 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:
fd Specifies the file descriptor being polled.
events Specifies 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.
revents 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:
filedes The file descriptor for the poll set (returned when the driver was
opened).
request DP_POLL
arg 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:
dp_fds Points to an array of returned pollfd structures as described in
Creating a Poll Set.
dp_nfds 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.
dp_timeout
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:
>0 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:
fd Indicates the file descriptor polled.
events Indicates the events being monitored by the application for
that file descriptor.
revents 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.
0 The call timed out. In this case, the content of the array pointed to
by dp_fds is not modified.
-1 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:
1 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 monitored for that file descriptor.
0 The file descriptor is not a member of the poll set. In this case,
the pollfd entry for the file descriptor is not modified.
-1 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
1. 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);
}
...
}
2. 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
/dev/poll
Device special file for the fast poll driver.
SEE ALSO
Functions: ioctl(2), open(2), poll(2), select(2), write(2)
|
Index for
Section 7 |
|
|
Alphabetical
listing for P |
|
 |
Top of
page |
|