V4L2 read()

읽기 선언과 인자

`v4l2-read`는 V4L2 장치에서 data를 읽습니다. `<unistd.h>`를 포함하고 `ssize_t read(int fd, void *buf, size_t count)`를 호출합니다.

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

.. _func-read:

***********
V4L2 read()
***********

Name
====

v4l2-read - Read from a V4L2 device

Synopsis
========

.. code-block:: c

    #include <unistd.h>

.. c:function:: ssize_t read( int fd, void *buf, size_t count )

Arguments
=========

``fd``
    File descriptor returned by :c:func:`open()`.

``buf``
   Buffer to be filled

``count``
  Max number of bytes to read

Frame 단위 읽기와 buffer 폐기 정책

`read()`는 `fd`에서 최대 `count` byte를 `buf`로 읽습니다. Buffer data layout은 해당 device interface 절을 따릅니다. `count == 0`이면 다른 효과 없이 0을 반환하고, `count > SSIZE_MAX`의 결과는 정의되지 않습니다. `count`와 관계없이 한 번의 호출은 최대 한 frame, 즉 두 field 분량만 제공합니다.

기본적으로 data가 생길 때까지 block합니다. `open()`에 `O_NONBLOCK`을 줬고 data가 없으면 즉시 `EAGAIN`을 반환합니다. `select()`와 `poll()`로 data가 준비될 때까지 기다릴 수 있으며 read를 지원하는 모든 driver는 두 함수도 지원해야 합니다.

Driver는 single 또는 multiple internal buffer를 사용하고 가득 찼을 때 oldest 또는 newest frame을 버리는 등 서로 다른 방식으로 read를 구현할 수 있습니다. 채우는 중인 buffer의 snapshot을 반환하는 일은 없습니다.

Single-buffer 방식은 application이 읽기 시작하면 완료될 때까지 capture를 멈춥니다. 따라서 vertical blanking interval 안에 읽기를 끝내거나 capture rate가 nominal frame rate보다 낮아져야 합니다. Active picture 또는 top/bottom field 사이 blanking에서 호출했을 때 동작은 폐기 정책에 달려 있습니다.

Application은 선택 사항인 `VIDIOC_G_PARM`과 `VIDIOC_S_PARM`으로 driver 내부 buffer 수를 조회하거나 설정할 수 있습니다. 폐기 정책은 보고되지 않고 변경할 수도 없습니다.

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

:c:func:`read()` attempts to read up to ``count`` bytes from file
descriptor ``fd`` into the buffer starting at ``buf``. The layout of the
data in the buffer is discussed in the respective device interface
section, see ##. If ``count`` is zero, :c:func:`read()` returns zero
and has no other results. If ``count`` is greater than ``SSIZE_MAX``,
the result is unspecified. Regardless of the ``count`` value each
:c:func:`read()` call will provide at most one frame (two fields)
worth of data.

By default :c:func:`read()` blocks until data becomes available. When
the ``O_NONBLOCK`` flag was given to the :c:func:`open()`
function it returns immediately with an ``EAGAIN`` error code when no data
is available. The :c:func:`select()` or
:c:func:`poll()` functions can always be used to suspend
execution until data becomes available. All drivers supporting the
:c:func:`read()` function must also support :c:func:`select()` and
:c:func:`poll()`.

Drivers can implement read functionality in different ways, using a
single or multiple buffers and discarding the oldest or newest frames
once the internal buffers are filled.

:c:func:`read()` never returns a "snapshot" of a buffer being filled.
Using a single buffer the driver will stop capturing when the
application starts reading the buffer until the read is finished. Thus
only the period of the vertical blanking interval is available for
reading, or the capture rate must fall below the nominal frame rate of
the video standard.

The behavior of :c:func:`read()` when called during the active picture
period or the vertical blanking separating the top and bottom field
depends on the discarding policy. A driver discarding the oldest frames
keeps capturing into an internal buffer, continuously overwriting the
previously, not read frame, and returns the frame being received at the
time of the :c:func:`read()` call as soon as it is complete.

A driver discarding the newest frames stops capturing until the next
:c:func:`read()` call. The frame being received at :c:func:`read()`
time is discarded, returning the following frame instead. Again this
implies a reduction of the capture rate to one half or less of the
nominal frame rate. An example of this model is the video read mode of
the bttv driver, initiating a DMA to user memory when :c:func:`read()`
is called and returning when the DMA finished.

In the multiple buffer model drivers maintain a ring of internal
buffers, automatically advancing to the next free buffer. This allows
continuous capturing when the application can empty the buffers fast
enough. Again, the behavior when the driver runs out of free buffers
depends on the discarding policy.

Applications can get and set the number of buffers used internally by
the driver with the :ref:`VIDIOC_G_PARM <VIDIOC_G_PARM>` and
:ref:`VIDIOC_S_PARM <VIDIOC_G_PARM>` ioctls. They are optional,
however. The discarding policy is not reported and cannot be changed.
For minimum requirements see :ref:`devices`.

짧은 읽기, frame 경계와 오류

성공하면 읽은 byte 수를 반환합니다. 요청한 수나 한 frame에 필요한 양보다 작아도 오류는 아니며 signal interruption 때문에 발생할 수 있습니다. 오류면 -1과 `errno`를 반환하고 다음 `read()`는 새 frame의 시작에서 다시 시작합니다.

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

On success, the number of bytes read is returned. It is not an error if
this number is smaller than the number of bytes requested, or the amount
of data required for one frame. This may happen for example because
:c:func:`read()` was interrupted by a signal. On error, -1 is
returned, and the ``errno`` variable is set appropriately. In this case
the next read will start at the beginning of a new frame. Possible error
codes are:

EAGAIN
    Non-blocking I/O has been selected using O_NONBLOCK and no data was
    immediately available for reading.

EBADF
    ``fd`` is not a valid file descriptor or is not open for reading, or
    the process already has the maximum number of files open.

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

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

EINTR
    The call was interrupted by a signal before any data was read.

EIO
    I/O error. This indicates some hardware problem or a failure to
    communicate with a remote device (USB camera etc.).

EINVAL
    The :c:func:`read()` function is not supported by this driver, not
    on this device, or generally not on this type of device.