poll(7d)

NAME | SYNOPSIS | PARAMETERS | DESCRIPTION | EXAMPLES | ERRORS | ATTRIBUTES | SEE ALSO | NOTES

NAME

poll– driver for fast poll on many file descriptors

SYNOPSIS

#include <sys/devpoll.h> 

PARAMETERS

fd

Open file descriptor that refers to the /dev/poll driver.

path

/dev/poll

buf

Array of pollfd structures.

bufsize

Size of buf in bytes.

arg

Pointer to pollcall structure.

pfd

Pointer to pollfd structure.

DESCRIPTION

The /dev/poll driver is a special driver that lets user monitor multiple sets of polled file descriptors. By using the /dev/poll driver, users can poll large number of file descriptors very efficiently. Access to /dev/poll driver is provided through open(2), write(2), and ioctl(2) system calls.

Writing an array of pollfd struct to the /dev/poll driver has the effect of adding these file descriptors to the monitored poll file descriptor set represented by the fd. Users wishing to monitor multiple file descriptor sets should open the /dev/poll driver multiple times. Each fd corresponds to one set. For each pollfd struct entry (defined in sys/poll.h):

 struct pollfd {
    int  fd;
    short events;
    short revents;
 }

The fd field specifies the file descriptor being polled. The events field indicates the interested poll events on the file descriptor. If a pollfd array contains multiple pollfd entries with same fd field, the "events" field in each pollfd entry is OR'ed. A special POLLREMOVE event in the events field of the pollfd structure will remove the fd from the monitored set. The revents field is not used. Write returns the number of bytes written successfully or -1 when write fails.

The DP_POLL ioctl is used to retrieve returned poll events occured on the polled file descriptors in the monitored set represented by fd. arg is a pointer to the devpoll structures which are defined as follows:

 struct dvpoll {
     struct pollfd* dp_fds;
     int dp_nfds;
     int dp_timeout;
 }

The dp_fds points to a buffer which is used to hold an array of returned pollfd structures. The dp_nfds field specifies the size of the buffer in terms of the number of pollfd entries it contains; dp_nfds also indicates the maximum number of file descriptors on which a user is interested in getting poll information. If there is no interested events on any of the polled file descriptors, the DP_POLL ioctl call will wait dp_timeout miliseconds before returning. If dp_timeout is 0, the ioctl call returns immediately; if dp_timeout is -1, the call blocks until an interested poll events is available or the call is interrupted. Upon return, if the ioctl call has failed, -1 is returned. The memory content pointed by dp_fds is not modified. A return value 0 means the ioctl is timed out. In this case, the memory content pointed by dp_fds is not modified. If the call is successful, it returns the number of valid pollfd entries in the array pointed by dp_fds; the contents of the rest of the buffer is undefined. For each valid pollfd entry, the fd field indicates the file desciptor on which the polled events happened. The events field is the user specified poll events. The revents field contains the events occurred. –1 is returned if the call fails.

DP_ISPOLLED ioctl allows user to query if a file descriptor is already in the monitored set represented by fd. The fd field of the pollfd structure indicates the file descriptor of interest. The DP_ISPOLLED ioctl returns 1 if the file descriptor is in the set. The events field contains the currently polled events. The revents field contains 0. The ioctl returns 0 if the file descriptor is not in the set. The pollfd structure pointed by pfd is not modified. The ioctl returns a -1 if the call fails.

EXAMPLES

---

Example 1 The following example shows how /dev/poll may be used.




{
        ...
        /*
         * open the driver
         */
        if ((wfd = open("/dev/poll", O_RDWR)) < 0) {
                exit(-1);
        }
        pollfd = (struct pollfd* )malloc(sizeof(struct pollfd) * MAXBUF);
        if (pollfd == NULL) {
                close(wfd);
                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(wfd, &pollfd[0], sizeof(struct pollfd) * MAXBUF) !=
                        sizeof(struct pollfd) * MAXBUF) {
                perror("failed to write all pollfds");
                close (wfd);
                free(pollfd);
                exit(-1);
        }
        /*
         * read from the devpoll driver
         */
        dopoll.dp_timeout = -1;
        dopoll.dp_nfds = MAXBUF;
        dopoll.dp_fds = pollfd;
        result = ioctl(wfd, DP_POLL, &dopoll);
        if (result < 0) {
                perror("/dev/poll ioctl DP_POLL failed");
                close (wfd);
                free(pollfd);
                exit(-1);
        }
        for (i = 0; i < result; i++) {
                read(dopoll.dp_fds[i].fd, rbuf, STRLEN);
        }
 ...
}

---

ERRORS

EACCES

A process does not have permission to access the content cached in /dev/poll.

EINTR

A signal was caught during the execution of the ioctl(2) function.

EFAULT

The request argument requires a data transfer to or from a buffer pointed to by arg, but arg points to an illegal address.

EINVAL

The request or arg parameter is not valid for this device.

ENXIO

The O_NONBLICK flag is set, the named file is a FIFO, the O_WRONGLY flag is set, and no process has the file open for reading; or the named file is a character special or block special file and the device associated with this special file does not exist.

ATTRIBUTES

See attributes(5) for a description of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Architecture	SPARC, Intel
Availability	SUNWcarx.u, SUNWcsxu (64-bit Solaris)
	SUNWcsr, SUNWcsu (32-bit Solaris on Intel)
	SUNWhea (header files)
Interface Stability	Evolving
MT-Level	Safe

SEE ALSO

open(2), poll(2), write(2), attributes(5)

NOTES

The /dev/poll API is particularly beneficial to applications which poll a large number of file descriptors and poll them repeatedly. Applications will exhibit the best performance gain if the polled file descriptor list rarely change.

When using the /dev/poll driver, user should pay attention to remove a closed file descriptor from a monitored poll set. Failure to do so may result in a POLLNVAL revents being returned for the closed file descriptor. When a file descriptor is closed but not removed from the monitored set, and if the file descriptor is reused in subsequent open of a possibly different device, user will be polling the device associated with the reused file descriptor. In a multithreaded application, careful coordination among threads doing close and DP_POLL ioctl is recommended for consistent results.

The /dev/poll driver caches a list of polled file descriptors, which are specific to a process. Therefore, the /dev/poll file descriptor of a process will be inherited by its child process, just like any other file descriptors. But the child process will have very limited access through this inherited /dev/poll file descriptor. Any attempt to write or do ioctl by the child process will result in an EACCES error. The child process should close the inherited /dev/poll file descriptor and open its own if desired.

The /dev/poll driver does not yet support polling. Polling on a /dev/poll file descriptor will result in POLLERR being returned in the revents field of pollfd structure.

SunOS 5.8  Last Revised 31 Jan 1999

NAME | SYNOPSIS | PARAMETERS | DESCRIPTION | EXAMPLES | ERRORS | ATTRIBUTES | SEE ALSO | NOTES