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