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