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

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