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