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