| 1 |
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later |
| 2 |
.. c:namespace:: V4L |
| 3 |
|
| 4 |
.. _func-read: |
| 5 |
|
| 6 |
*********** |
| 7 |
V4L2 read() |
| 8 |
*********** |
| 9 |
|
| 10 |
Name |
| 11 |
==== |
| 12 |
|
| 13 |
v4l2-read - Read from a V4L2 device |
| 14 |
|
| 15 |
Synopsis |
| 16 |
======== |
| 17 |
|
| 18 |
.. code-block:: c |
| 19 |
|
| 20 |
#include <unistd.h> |
| 21 |
|
| 22 |
.. c:function:: ssize_t read( int fd, void *buf, size_t count ) |
| 23 |
|
| 24 |
Arguments |
| 25 |
========= |
| 26 |
|
| 27 |
``fd`` |
| 28 |
File descriptor returned by :c:func:`open()`. |
| 29 |
|
| 30 |
``buf`` |
| 31 |
Buffer to be filled |
| 32 |
|
| 33 |
``count`` |
| 34 |
Max number of bytes to read |
| 35 |
|
| 36 |
Description |
| 37 |
=========== |
| 38 |
|
| 39 |
:c:func:`read()` attempts to read up to ``count`` bytes from file |
| 40 |
descriptor ``fd`` into the buffer starting at ``buf``. The layout of the |
| 41 |
data in the buffer is discussed in the respective device interface |
| 42 |
section, see ##. If ``count`` is zero, :c:func:`read()` returns zero |
| 43 |
and has no other results. If ``count`` is greater than ``SSIZE_MAX``, |
| 44 |
the result is unspecified. Regardless of the ``count`` value each |
| 45 |
:c:func:`read()` call will provide at most one frame (two fields) |
| 46 |
worth of data. |
| 47 |
|
| 48 |
By default :c:func:`read()` blocks until data becomes available. When |
| 49 |
the ``O_NONBLOCK`` flag was given to the :c:func:`open()` |
| 50 |
function it returns immediately with an ``EAGAIN`` error code when no data |
| 51 |
is available. The :c:func:`select()` or |
| 52 |
:c:func:`poll()` functions can always be used to suspend |
| 53 |
execution until data becomes available. All drivers supporting the |
| 54 |
:c:func:`read()` function must also support :c:func:`select()` and |
| 55 |
:c:func:`poll()`. |
| 56 |
|
| 57 |
Drivers can implement read functionality in different ways, using a |
| 58 |
single or multiple buffers and discarding the oldest or newest frames |
| 59 |
once the internal buffers are filled. |
| 60 |
|
| 61 |
:c:func:`read()` never returns a "snapshot" of a buffer being filled. |
| 62 |
Using a single buffer the driver will stop capturing when the |
| 63 |
application starts reading the buffer until the read is finished. Thus |
| 64 |
only the period of the vertical blanking interval is available for |
| 65 |
reading, or the capture rate must fall below the nominal frame rate of |
| 66 |
the video standard. |
| 67 |
|
| 68 |
The behavior of :c:func:`read()` when called during the active picture |
| 69 |
period or the vertical blanking separating the top and bottom field |
| 70 |
depends on the discarding policy. A driver discarding the oldest frames |
| 71 |
keeps capturing into an internal buffer, continuously overwriting the |
| 72 |
previously, not read frame, and returns the frame being received at the |
| 73 |
time of the :c:func:`read()` call as soon as it is complete. |
| 74 |
|
| 75 |
A driver discarding the newest frames stops capturing until the next |
| 76 |
:c:func:`read()` call. The frame being received at :c:func:`read()` |
| 77 |
time is discarded, returning the following frame instead. Again this |
| 78 |
implies a reduction of the capture rate to one half or less of the |
| 79 |
nominal frame rate. An example of this model is the video read mode of |
| 80 |
the bttv driver, initiating a DMA to user memory when :c:func:`read()` |
| 81 |
is called and returning when the DMA finished. |
| 82 |
|
| 83 |
In the multiple buffer model drivers maintain a ring of internal |
| 84 |
buffers, automatically advancing to the next free buffer. This allows |
| 85 |
continuous capturing when the application can empty the buffers fast |
| 86 |
enough. Again, the behavior when the driver runs out of free buffers |
| 87 |
depends on the discarding policy. |
| 88 |
|
| 89 |
Applications can get and set the number of buffers used internally by |
| 90 |
the driver with the :ref:`VIDIOC_G_PARM <VIDIOC_G_PARM>` and |
| 91 |
:ref:`VIDIOC_S_PARM <VIDIOC_G_PARM>` ioctls. They are optional, |
| 92 |
however. The discarding policy is not reported and cannot be changed. |
| 93 |
For minimum requirements see :ref:`devices`. |
| 94 |
|
| 95 |
Return Value |
| 96 |
============ |
| 97 |
|
| 98 |
On success, the number of bytes read is returned. It is not an error if |
| 99 |
this number is smaller than the number of bytes requested, or the amount |
| 100 |
of data required for one frame. This may happen for example because |
| 101 |
:c:func:`read()` was interrupted by a signal. On error, -1 is |
| 102 |
returned, and the ``errno`` variable is set appropriately. In this case |
| 103 |
the next read will start at the beginning of a new frame. Possible error |
| 104 |
codes are: |
| 105 |
|
| 106 |
EAGAIN |
| 107 |
Non-blocking I/O has been selected using O_NONBLOCK and no data was |
| 108 |
immediately available for reading. |
| 109 |
|
| 110 |
EBADF |
| 111 |
``fd`` is not a valid file descriptor or is not open for reading, or |
| 112 |
the process already has the maximum number of files open. |
| 113 |
|
| 114 |
EBUSY |
| 115 |
The driver does not support multiple read streams and the device is |
| 116 |
already in use. |
| 117 |
|
| 118 |
EFAULT |
| 119 |
``buf`` references an inaccessible memory area. |
| 120 |
|
| 121 |
EINTR |
| 122 |
The call was interrupted by a signal before any data was read. |
| 123 |
|
| 124 |
EIO |
| 125 |
I/O error. This indicates some hardware problem or a failure to |
| 126 |
communicate with a remote device (USB camera etc.). |
| 127 |
|
| 128 |
EINVAL |
| 129 |
The :c:func:`read()` function is not supported by this driver, not |
| 130 |
on this device, or generally not on this type of device. |