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