V4L2 poll()

이벤트 대기 선언

`v4l2-poll`은 file descriptor에서 event가 발생할 때까지 기다리는 synchronous I/O 함수입니다. `<sys/poll.h>`를 포함하고 `int poll(struct pollfd *ufds, unsigned int nfds, int timeout)`을 호출합니다.

.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
.. c:namespace:: V4L

.. _func-poll:

***********
V4L2 poll()
***********

Name
====

v4l2-poll - Wait for some event on a file descriptor

Synopsis
========

.. code-block:: c

    #include <sys/poll.h>

.. c:function:: int poll( struct pollfd *ufds, unsigned int nfds, int timeout )

Arguments
=========


Description
===========

Streaming, read/write와 event 준비 상태

Application은 `poll()`로 capture data가 준비되거나 output 장치가 data를 받을 수 있을 때까지 실행을 멈출 수 있습니다. Streaming I/O에서는 capture buffer가 채워져 `VIDIOC_DQBUF`로 꺼낼 수 있거나 output 장치가 `VIDIOC_QBUF`로 새 buffer를 받을 수 있을 때까지 기다립니다. Capture outgoing queue에 buffer가 이미 있거나 display incoming queue가 가득 차지 않았으면 즉시 반환합니다.

성공하면 `revents`가 0이 아닌 descriptor 수, timeout이면 0, 실패하면 -1과 `errno`를 반환합니다. `VIDIOC_STREAMON`을 호출하지 않았으면 성공 반환과 함께 `POLLERR`가 설정됩니다. Capture에서 STREAMON 후 QBUF가 없을 때도 POLLERR입니다. Output의 같은 상황에서는 새 buffer를 받을 수 있으므로 `POLLOUT | POLLWRNORM`이 설정됩니다.

Read I/O가 협상됐고 아직 capture하지 않는 driver라면 `poll()`이 capture를 시작합니다. 실패하면 POLLERR이고, 성공하면 data를 읽을 수 있을 때까지 기다립니다. Continuous capture 장치는 data가 이미 있으면 즉시 반환할 수 있습니다. Write I/O가 협상됐고 아직 streaming하지 않으면 `poll()`이 streaming을 시작하고 non-blocking `write()`가 가능할 때까지 기다립니다.

Application이 `events`에 `POLLPRI`만 설정해 V4L2 event에만 관심을 표시하면 `poll()`은 아직 멈춘 streaming을 시작하지 않습니다. 따라서 buffer와 무관하게 event만 기다릴 수 있습니다. Read, write 또는 streaming I/O를 구현하는 모든 driver는 `poll()`도 지원해야 합니다.

With the :c:func:`poll()` function applications can suspend execution
until the driver has captured data or is ready to accept data for
output.

When streaming I/O has been negotiated this function waits until a
buffer has been filled by the capture device and can be dequeued with
the :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. For output devices this
function waits until the device is ready to accept a new buffer to be
queued up with the :ref:`VIDIOC_QBUF <VIDIOC_QBUF>` ioctl for
display. When buffers are already in the outgoing queue of the driver
(capture) or the incoming queue isn't full (display) the function
returns immediately.

On success :c:func:`poll()` returns the number of file descriptors
that have been selected (that is, file descriptors for which the
``revents`` field of the respective ``struct pollfd`` structure
is non-zero). Capture devices set the ``POLLIN`` and ``POLLRDNORM``
flags in the ``revents`` field, output devices the ``POLLOUT`` and
``POLLWRNORM`` flags. When the function timed out it returns a value of
zero, on failure it returns -1 and the ``errno`` variable is set
appropriately. When the application did not call
:ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` the :c:func:`poll()`
function succeeds, but sets the ``POLLERR`` flag in the ``revents``
field. When the application has called
:ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` for a capture device but
hasn't yet called :ref:`VIDIOC_QBUF <VIDIOC_QBUF>`, the
:c:func:`poll()` function succeeds and sets the ``POLLERR`` flag in
the ``revents`` field. For output devices this same situation will cause
:c:func:`poll()` to succeed as well, but it sets the ``POLLOUT`` and
``POLLWRNORM`` flags in the ``revents`` field.

If an event occurred (see :ref:`VIDIOC_DQEVENT`)
then ``POLLPRI`` will be set in the ``revents`` field and
:c:func:`poll()` will return.

When use of the :c:func:`read()` function has been negotiated and the
driver does not capture yet, the :c:func:`poll()` function starts
capturing. When that fails it returns a ``POLLERR`` as above. Otherwise
it waits until data has been captured and can be read. When the driver
captures continuously (as opposed to, for example, still images) the
function may return immediately.

When use of the :c:func:`write()` function has been negotiated and the
driver does not stream yet, the :c:func:`poll()` function starts
streaming. When that fails it returns a ``POLLERR`` as above. Otherwise
it waits until the driver is ready for a non-blocking
:c:func:`write()` call.

If the caller is only interested in events (just ``POLLPRI`` is set in
the ``events`` field), then :c:func:`poll()` will *not* start
streaming if the driver does not stream yet. This makes it possible to
just poll for events and not for buffers.

All drivers implementing the :c:func:`read()` or :c:func:`write()`
function or streaming I/O must also support the :c:func:`poll()`
function.

For more details see the :c:func:`poll()` manual page.

반환값과 오류

성공 시 non-zero `revents`를 가진 structure 수를 반환하고 timeout이면 0입니다. 오류 시 -1과 `errno`를 반환합니다.

Return Value
============

On success, :c:func:`poll()` returns the number structures which have
non-zero ``revents`` fields, or zero if the call timed out. On error -1
is returned, and the ``errno`` variable is set appropriately:

EBADF
    One or more of the ``ufds`` members specify an invalid file
    descriptor.

EBUSY
    The driver does not support multiple read or write streams and the
    device is already in use.

EFAULT
    ``ufds`` references an inaccessible memory area.

EINTR
    The call was interrupted by a signal.

EINVAL
    The ``nfds`` value exceeds the ``RLIMIT_NOFILE`` value. Use
    ``getrlimit()`` to obtain this value.