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

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