Documentation/userspace-api/media/v4l/func-read.rst

Source file repositories/reference/linux-study-clean/Documentation/userspace-api/media/v4l/func-read.rst

File Facts

System
Linux kernel
Corpus path
Documentation/userspace-api/media/v4l/func-read.rst
Extension
.rst
Size
4691 bytes
Lines
131
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

.. 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

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

Annotation

Implementation Notes