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