func-poll.rst

  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.