Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame^] | 1 | .. -*- coding: utf-8; mode: rst -*- |
| 2 | |
| 3 | .. _func-poll: |
| 4 | |
| 5 | *********** |
| 6 | V4L2 poll() |
| 7 | *********** |
| 8 | |
| 9 | *man v4l2-poll(2)* |
| 10 | |
| 11 | Wait for some event on a file descriptor |
| 12 | |
| 13 | |
| 14 | Synopsis |
| 15 | ======== |
| 16 | |
| 17 | .. code-block:: c |
| 18 | |
| 19 | #include <sys/poll.h> |
| 20 | |
| 21 | |
| 22 | .. c:function:: int poll( struct pollfd *ufds, unsigned int nfds, int timeout ) |
| 23 | |
| 24 | Description |
| 25 | =========== |
| 26 | |
| 27 | With the :c:func:`poll()` function applications can suspend execution |
| 28 | until the driver has captured data or is ready to accept data for |
| 29 | output. |
| 30 | |
| 31 | When streaming I/O has been negotiated this function waits until a |
| 32 | buffer has been filled by the capture device and can be dequeued with |
| 33 | the :ref:`VIDIOC_DQBUF <vidioc-qbuf>` ioctl. For output devices this |
| 34 | function waits until the device is ready to accept a new buffer to be |
| 35 | queued up with the :ref:`VIDIOC_QBUF <vidioc-qbuf>` ioctl for |
| 36 | display. When buffers are already in the outgoing queue of the driver |
| 37 | (capture) or the incoming queue isn't full (display) the function |
| 38 | returns immediately. |
| 39 | |
| 40 | On success :c:func:`poll()` returns the number of file descriptors |
| 41 | that have been selected (that is, file descriptors for which the |
| 42 | ``revents`` field of the respective :c:type:`struct pollfd` structure |
| 43 | is non-zero). Capture devices set the ``POLLIN`` and ``POLLRDNORM`` |
| 44 | flags in the ``revents`` field, output devices the ``POLLOUT`` and |
| 45 | ``POLLWRNORM`` flags. When the function timed out it returns a value of |
| 46 | zero, on failure it returns -1 and the ``errno`` variable is set |
| 47 | appropriately. When the application did not call |
| 48 | :ref:`VIDIOC_STREAMON <vidioc-streamon>` the :c:func:`poll()` |
| 49 | function succeeds, but sets the ``POLLERR`` flag in the ``revents`` |
| 50 | field. When the application has called |
| 51 | :ref:`VIDIOC_STREAMON <vidioc-streamon>` for a capture device but |
| 52 | hasn't yet called :ref:`VIDIOC_QBUF <vidioc-qbuf>`, the |
| 53 | :c:func:`poll()` function succeeds and sets the ``POLLERR`` flag in |
| 54 | the ``revents`` field. For output devices this same situation will cause |
| 55 | :c:func:`poll()` to succeed as well, but it sets the ``POLLOUT`` and |
| 56 | ``POLLWRNORM`` flags in the ``revents`` field. |
| 57 | |
| 58 | If an event occurred (see :ref:`VIDIOC_DQEVENT <vidioc-dqevent>`) |
| 59 | then ``POLLPRI`` will be set in the ``revents`` field and |
| 60 | :c:func:`poll()` will return. |
| 61 | |
| 62 | When use of the :c:func:`read()` function has been negotiated and the |
| 63 | driver does not capture yet, the :c:func:`poll()` function starts |
| 64 | capturing. When that fails it returns a ``POLLERR`` as above. Otherwise |
| 65 | it waits until data has been captured and can be read. When the driver |
| 66 | captures continuously (as opposed to, for example, still images) the |
| 67 | function may return immediately. |
| 68 | |
| 69 | When use of the :c:func:`write()` function has been negotiated and the |
| 70 | driver does not stream yet, the :c:func:`poll()` function starts |
| 71 | streaming. When that fails it returns a ``POLLERR`` as above. Otherwise |
| 72 | it waits until the driver is ready for a non-blocking |
| 73 | :c:func:`write()` call. |
| 74 | |
| 75 | If the caller is only interested in events (just ``POLLPRI`` is set in |
| 76 | the ``events`` field), then :c:func:`poll()` will *not* start |
| 77 | streaming if the driver does not stream yet. This makes it possible to |
| 78 | just poll for events and not for buffers. |
| 79 | |
| 80 | All drivers implementing the :c:func:`read()` or :c:func:`write()` |
| 81 | function or streaming I/O must also support the :c:func:`poll()` |
| 82 | function. |
| 83 | |
| 84 | For more details see the :c:func:`poll()` manual page. |
| 85 | |
| 86 | |
| 87 | Return Value |
| 88 | ============ |
| 89 | |
| 90 | On success, :c:func:`poll()` returns the number structures which have |
| 91 | non-zero ``revents`` fields, or zero if the call timed out. On error -1 |
| 92 | is returned, and the ``errno`` variable is set appropriately: |
| 93 | |
| 94 | EBADF |
| 95 | One or more of the ``ufds`` members specify an invalid file |
| 96 | descriptor. |
| 97 | |
| 98 | EBUSY |
| 99 | The driver does not support multiple read or write streams and the |
| 100 | device is already in use. |
| 101 | |
| 102 | EFAULT |
| 103 | ``ufds`` references an inaccessible memory area. |
| 104 | |
| 105 | EINTR |
| 106 | The call was interrupted by a signal. |
| 107 | |
| 108 | EINVAL |
| 109 | The ``nfds`` argument is greater than ``OPEN_MAX``. |
| 110 | |
| 111 | |
| 112 | .. ------------------------------------------------------------------------------ |
| 113 | .. This file was automatically converted from DocBook-XML with the dbxml |
| 114 | .. library (https://github.com/return42/sphkerneldoc). The origin XML comes |
| 115 | .. from the linux kernel, refer to: |
| 116 | .. |
| 117 | .. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook |
| 118 | .. ------------------------------------------------------------------------------ |