poll(7d) 맨 페이지 - 윈디하나의 솔라나라

개요

섹션
맨페이지이름
검색(S)

poll

Name
     poll - driver for fast poll on many file descriptors

Synopsis
     #include <sys/devpoll.h>
     int fd = open("/dev/poll", O_RDWR);
     ssize_t n = write(int fd, struct pollfd buf[], int bufsize);
     int n = ioctl(int fd, DP_POLL, struct dvpoll* arg);
     int n = ioctl(int fd, DP_ISPOLLED, struct pollfd* pfd);

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
     Note -

       The /dev/poll device, associated driver and  corresponding
       manpages  may  be removed in a future Solaris release. For
       similar functionality in the event  ports  framework,  see
       port_create(3C).


     The  /dev/poll driver is a special driver that  enables  you
     to  monitor  multiple  sets   of polled file descriptors. By
     using the  /dev/poll driver, you can efficiently poll  large
     numbers  of file descriptors. Access to the /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 mon-
     itored poll file descriptor set  represented by the  fd.  To
     monitor  multiple  file  descriptor sets, 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 the 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 removes 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  struc-
     tures which are defined as follows:

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



     The  dp_fds points to  a  buffer  that  holds  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.  The  dp_nfds field also indicates the maximum
     number of file descriptors from which poll  information  can
     be obtained. If there is no interested  events on any of the
     polled file descriptors, the DP_POLL ioctl  call  will  wait
     dp_timeout  milliseconds  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 indi-
     cates the file desciptor on which  the  polled  events  hap-
     pened.  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 you 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  0.  The
     revents  field  contains  the  currently  polled events. 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
     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);
               }
        ...
       }



     The following example is part of a test program which  shows
     how DP_ISPOLLED() ioctl may be used.

       {
            ...

               loopcnt = 0;
               while (loopcnt < ITERATION) {
                       rn = random();
                       rn %= RANGE;
                       if (write(fds[rn], TESTSTRING, strlen(TESTSTRING)) !=
                                       strlen(TESTSTRING)) {
                               perror("write to fifo failed.");
                               close (wfd);
                               free(pollfd);
                               error = 1;
                               goto out1;
                       }
                       dpfd.fd = fds[rn];
                       dpfd.events = 0;
                       dpfd.revents = 0;
                       result = ioctl(wfd, DP_ISPOLLED, &dpfd);
                       if (result < 0) {
                               perror("/dev/poll ioctl DP_ISPOLLED failed");
                               printf("errno = %d\n", errno);
                               close (wfd);
                               free(pollfd);
                               error = 1;
                               goto out1;
                       }
                       if (result != 1) {
                               printf("DP_ISPOLLED returned incorrect result: %d.\n",
                                       result);
                               close (wfd);
                               free(pollfd);
                               error = 1;
                               goto out1;
                       }
                       if (dpfd.fd != fds[rn]) {
                               printf("DP_ISPOLLED returned wrong fd %d, expect %d\n",
                                       dpfd.fd, fds[rn]);
                               close (wfd);
                               free(pollfd);
                               error = 1;
                               goto out1;
        }
                       if (dpfd.revents != POLLIN) {
                               printf("DP_ISPOLLED returned unexpected revents %d\n",
                                       dpfd.revents);
                               close (wfd);
                               free(pollfd);
                               error = 1;
                               goto out1;
                       }
                       if (read(dpfd.fd, rbuf, strlen(TESTSTRING)) !=
                                       strlen(TESTSTRING)) {
                               perror("read from fifo failed");
                               close (wfd);
                               free(pollfd);
                               error = 1;
                               goto out1;
                       }
                       loopcnt++;
               }

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, or field of the dvpoll struct pointed
               by arg is not  valid   (for  example,  when  using
               write/pwrite  dp_nfds  is greater than {OPEN_MAX},
               or when using the DPPOLL ioctl dp_nfds is  greater
               than or equal to {OPEN_MAX}}.

     ENXIO
               The O_NONBLOCK flag is set, the named  file  is  a
               FIFO, the O_WRONLY 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  attri-
     butes:



     tab() box; lw(2.75i) lw(2.75i) lw(2.75i) lw(2.75i) ATTRIBUTE
     TYPEATTRIBUTE       VALUE       ArchitectureSPARC,       x86
     Availabilitysystem/library/processor       (        Solaris)
     system/core-os   system/header  Interface  StabilityObsolete
     MT-LevelSafe

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

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


     When using the /dev/poll driver, you should 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 is reused in  subse-
     quent  open  of  a different device, you will be polling the
     device associated with the reused file descriptor. In a mul-
     tithreaded  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  descrip-
     tors,  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.
맨 페이지 내용의 저작권은 맨 페이지 작성자에게 있습니다.
RSS ATOM XHTML 1.0 CSS3