Documentation/media/uapi/v4l/func-poll.rst

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