V4L2 select()

동기 I/O multiplexing 선언

`v4l2-select`는 여러 descriptor의 동기 I/O 준비 상태를 기다립니다. `<sys/time.h>`, `<sys/types.h>`, `<unistd.h>`를 포함하고 `int select(int nfds, fd_set *readfds, fd_set *writefds, fd_set *exceptfds, struct timeval *timeout)`을 호출합니다.

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

.. _func-select:

*************
V4L2 select()
*************

Name
====

v4l2-select - Synchronous I/O multiplexing

Synopsis
========

.. code-block:: c

    #include <sys/time.h>
    #include <sys/types.h>
    #include <unistd.h>

.. c:function:: int select( int nfds, fd_set *readfds, fd_set *writefds, fd_set *exceptfds, struct timeval *timeout )

Arguments
=========

``nfds``
  The highest-numbered file descriptor in any of the three sets, plus 1.

``readfds``
  File descriptions to be watched if a read() call won't block.

``writefds``
  File descriptions to be watched if a write() won't block.

``exceptfds``
  File descriptions to be watched for V4L2 events.

``timeout``
  Maximum time to wait.

Streaming과 read/write 준비 상태

Application은 `select()`로 driver가 capture data를 준비하거나 output data를 받을 수 있을 때까지 실행을 멈출 수 있습니다. Streaming I/O에서는 buffer가 채워지거나 display되어 `VIDIOC_DQBUF`로 꺼낼 수 있을 때까지 기다립니다. Driver outgoing queue에 buffer가 이미 있으면 즉시 반환합니다.

성공하면 반환된 `fd_set`에 설정된 bit의 총수, timeout이면 0, 실패하면 -1과 `errno`를 반환합니다. 아직 `VIDIOC_QBUF` 또는 `VIDIOC_STREAMON`을 호출하지 않았어도 `select()`는 성공하고 readfds 또는 writefds에 descriptor bit를 설정하지만 뒤이은 `VIDIOC_DQBUF`는 실패합니다.

Read I/O가 협상됐고 아직 capture하지 않으면 `select()`가 capture를 시작합니다. 시작 실패 자체는 select 성공으로 나타나며, 다시 capture 시작을 시도하는 다음 `read()`가 적절한 오류를 반환합니다. Continuous capture에서 data가 이미 있으면 즉시 반환합니다. Write I/O에서는 non-blocking `write()`가 가능할 때까지 기다립니다.

Read, write 또는 streaming I/O를 구현하는 모든 driver는 `select()`도 지원해야 합니다.

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

With the :c:func:`select()` 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 or displayed and can be dequeued with the
:ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. When buffers are already in
the outgoing queue of the driver the function returns immediately.

On success :c:func:`select()` returns the total number of bits set in
``fd_set``. 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_QBUF` or
:ref:`VIDIOC_STREAMON` yet the :c:func:`select()`
function succeeds, setting the bit of the file descriptor in ``readfds``
or ``writefds``, but subsequent :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>`
calls will fail. [#f1]_

When use of the :c:func:`read()` function has been negotiated and the
driver does not capture yet, the :c:func:`select()` function starts
capturing. When that fails, :c:func:`select()` returns successful and
a subsequent :c:func:`read()` call, which also attempts to start
capturing, will return an appropriate error code. When the driver
captures continuously (as opposed to, for example, still images) and
data is already available the :c:func:`select()` function returns
immediately.

When use of the :c:func:`write()` function has been negotiated the
:c:func:`select()` function just waits until the driver is ready for a
non-blocking :c:func:`write()` call.

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

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

반환 후 set 상태와 오류

성공하면 세 반환 set에 포함된 descriptor 수를 반환하고 timeout이면 0입니다. 오류면 -1과 `errno`를 반환하며 이때 descriptor set들과 `timeout`의 내용은 undefined입니다.

Linux kernel의 `select()` 구현은 `poll()`과 유사하지만 `POLLERR`를 직접 반환할 수 없습니다. 따라서 잘못된 streaming 상태가 descriptor-ready처럼 보이고 실제 후속 I/O에서 오류가 드러날 수 있습니다.

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

On success, :c:func:`select()` returns the number of descriptors
contained in the three returned descriptor sets, which will be zero if
the timeout expired. On error -1 is returned, and the ``errno`` variable
is set appropriately; the sets and ``timeout`` are undefined. Possible
error codes are:

EBADF
    One or more of the file descriptor sets specified a file descriptor
    that is not open.

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

EFAULT
    The ``readfds``, ``writefds``, ``exceptfds`` or ``timeout`` pointer
    references an inaccessible memory area.

EINTR
    The call was interrupted by a signal.

EINVAL
    The ``nfds`` argument is less than zero or greater than
    ``FD_SETSIZE``.

.. [#f1]
   The Linux kernel implements :c:func:`select()` like the
   :c:func:`poll()` function, but :c:func:`select()` cannot
   return a ``POLLERR``.