Documentation/userspace-api/media/v4l/func-poll.rst

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