114 lines · plain
1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later2.. c:namespace:: V4L3 4.. _func-poll:5 6***********7V4L2 poll()8***********9 10Name11====12 13v4l2-poll - Wait for some event on a file descriptor14 15Synopsis16========17 18.. code-block:: c19 20 #include <sys/poll.h>21 22.. c:function:: int poll( struct pollfd *ufds, unsigned int nfds, int timeout )23 24Arguments25=========26 27 28Description29===========30 31With the :c:func:`poll()` function applications can suspend execution32until the driver has captured data or is ready to accept data for33output.34 35When streaming I/O has been negotiated this function waits until a36buffer has been filled by the capture device and can be dequeued with37the :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. For output devices this38function waits until the device is ready to accept a new buffer to be39queued up with the :ref:`VIDIOC_QBUF <VIDIOC_QBUF>` ioctl for40display. When buffers are already in the outgoing queue of the driver41(capture) or the incoming queue isn't full (display) the function42returns immediately.43 44On success :c:func:`poll()` returns the number of file descriptors45that have been selected (that is, file descriptors for which the46``revents`` field of the respective ``struct pollfd`` structure47is non-zero). Capture devices set the ``POLLIN`` and ``POLLRDNORM``48flags in the ``revents`` field, output devices the ``POLLOUT`` and49``POLLWRNORM`` flags. When the function timed out it returns a value of50zero, on failure it returns -1 and the ``errno`` variable is set51appropriately. When the application did not call52:ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` the :c:func:`poll()`53function succeeds, but sets the ``POLLERR`` flag in the ``revents``54field. When the application has called55:ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` for a capture device but56hasn't yet called :ref:`VIDIOC_QBUF <VIDIOC_QBUF>`, the57:c:func:`poll()` function succeeds and sets the ``POLLERR`` flag in58the ``revents`` field. For output devices this same situation will cause59:c:func:`poll()` to succeed as well, but it sets the ``POLLOUT`` and60``POLLWRNORM`` flags in the ``revents`` field.61 62If an event occurred (see :ref:`VIDIOC_DQEVENT`)63then ``POLLPRI`` will be set in the ``revents`` field and64:c:func:`poll()` will return.65 66When use of the :c:func:`read()` function has been negotiated and the67driver does not capture yet, the :c:func:`poll()` function starts68capturing. When that fails it returns a ``POLLERR`` as above. Otherwise69it waits until data has been captured and can be read. When the driver70captures continuously (as opposed to, for example, still images) the71function may return immediately.72 73When use of the :c:func:`write()` function has been negotiated and the74driver does not stream yet, the :c:func:`poll()` function starts75streaming. When that fails it returns a ``POLLERR`` as above. Otherwise76it waits until the driver is ready for a non-blocking77:c:func:`write()` call.78 79If the caller is only interested in events (just ``POLLPRI`` is set in80the ``events`` field), then :c:func:`poll()` will *not* start81streaming if the driver does not stream yet. This makes it possible to82just 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 Value91============92 93On success, :c:func:`poll()` returns the number structures which have94non-zero ``revents`` fields, or zero if the call timed out. On error -195is returned, and the ``errno`` variable is set appropriately:96 97EBADF98 One or more of the ``ufds`` members specify an invalid file99 descriptor.100 101EBUSY102 The driver does not support multiple read or write streams and the103 device is already in use.104 105EFAULT106 ``ufds`` references an inaccessible memory area.107 108EINTR109 The call was interrupted by a signal.110 111EINVAL112 The ``nfds`` value exceeds the ``RLIMIT_NOFILE`` value. Use113 ``getrlimit()`` to obtain this value.114