Orange Pi5 kernel

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