1<refentry id="func-read"> 2 <refmeta> 3 <refentrytitle>V4L2 read()</refentrytitle> 4 &manvol; 5 </refmeta> 6 7 <refnamediv> 8 <refname>v4l2-read</refname> 9 <refpurpose>Read from a V4L2 device</refpurpose> 10 </refnamediv> 11 12 <refsynopsisdiv> 13 <funcsynopsis> 14 <funcsynopsisinfo>#include <unistd.h></funcsynopsisinfo> 15 <funcprototype> 16 <funcdef>ssize_t <function>read</function></funcdef> 17 <paramdef>int <parameter>fd</parameter></paramdef> 18 <paramdef>void *<parameter>buf</parameter></paramdef> 19 <paramdef>size_t <parameter>count</parameter></paramdef> 20 </funcprototype> 21 </funcsynopsis> 22 </refsynopsisdiv> 23 24 <refsect1> 25 <title>Arguments</title> 26 27 <variablelist> 28 <varlistentry> 29 <term><parameter>fd</parameter></term> 30 <listitem> 31 <para>&fd;</para> 32 </listitem> 33 </varlistentry> 34 <varlistentry> 35 <term><parameter>buf</parameter></term> 36 <listitem> 37 <para></para> 38 </listitem> 39 </varlistentry> 40 <varlistentry> 41 <term><parameter>count</parameter></term> 42 <listitem> 43 <para></para> 44 </listitem> 45 </varlistentry> 46 </variablelist> 47 </refsect1> 48 49 <refsect1> 50 <title>Description</title> 51 52 <para><function>read()</function> attempts to read up to 53<parameter>count</parameter> bytes from file descriptor 54<parameter>fd</parameter> into the buffer starting at 55<parameter>buf</parameter>. The layout of the data in the buffer is 56discussed in the respective device interface section, see ##. If <parameter>count</parameter> is zero, 57<function>read()</function> returns zero and has no other results. If 58<parameter>count</parameter> is greater than 59<constant>SSIZE_MAX</constant>, the result is unspecified. Regardless 60of the <parameter>count</parameter> value each 61<function>read()</function> call will provide at most one frame (two 62fields) worth of data.</para> 63 64 <para>By default <function>read()</function> blocks until data 65becomes available. When the <constant>O_NONBLOCK</constant> flag was 66given to the &func-open; function it 67returns immediately with an &EAGAIN; when no data is available. The 68&func-select; or &func-poll; functions 69can always be used to suspend execution until data becomes available. All 70drivers supporting the <function>read()</function> function must also 71support <function>select()</function> and 72<function>poll()</function>.</para> 73 74 <para>Drivers can implement read functionality in different 75ways, using a single or multiple buffers and discarding the oldest or 76newest frames once the internal buffers are filled.</para> 77 78 <para><function>read()</function> never returns a "snapshot" of a 79buffer being filled. Using a single buffer the driver will stop 80capturing when the application starts reading the buffer until the 81read is finished. Thus only the period of the vertical blanking 82interval is available for reading, or the capture rate must fall below 83the nominal frame rate of the video standard.</para> 84 85<para>The behavior of 86<function>read()</function> when called during the active picture 87period or the vertical blanking separating the top and bottom field 88depends on the discarding policy. A driver discarding the oldest 89frames keeps capturing into an internal buffer, continuously 90overwriting the previously, not read frame, and returns the frame 91being received at the time of the <function>read()</function> call as 92soon as it is complete.</para> 93 94 <para>A driver discarding the newest frames stops capturing until 95the next <function>read()</function> call. The frame being received at 96<function>read()</function> time is discarded, returning the following 97frame instead. Again this implies a reduction of the capture rate to 98one half or less of the nominal frame rate. An example of this model 99is the video read mode of the bttv driver, initiating a DMA to user 100memory when <function>read()</function> is called and returning when 101the DMA finished.</para> 102 103 <para>In the multiple buffer model drivers maintain a ring of 104internal buffers, automatically advancing to the next free buffer. 105This allows continuous capturing when the application can empty the 106buffers fast enough. Again, the behavior when the driver runs out of 107free buffers depends on the discarding policy.</para> 108 109 <para>Applications can get and set the number of buffers used 110internally by the driver with the &VIDIOC-G-PARM; and &VIDIOC-S-PARM; 111ioctls. They are optional, however. The discarding policy is not 112reported and cannot be changed. For minimum requirements see <xref 113 linkend="devices" />.</para> 114 </refsect1> 115 116 <refsect1> 117 <title>Return Value</title> 118 119 <para>On success, the number of bytes read is returned. It is not 120an error if this number is smaller than the number of bytes requested, 121or the amount of data required for one frame. This may happen for 122example because <function>read()</function> was interrupted by a 123signal. On error, -1 is returned, and the <varname>errno</varname> 124variable is set appropriately. In this case the next read will start 125at the beginning of a new frame. Possible error codes are:</para> 126 127 <variablelist> 128 <varlistentry> 129 <term><errorcode>EAGAIN</errorcode></term> 130 <listitem> 131 <para>Non-blocking I/O has been selected using 132O_NONBLOCK and no data was immediately available for reading.</para> 133 </listitem> 134 </varlistentry> 135 <varlistentry> 136 <term><errorcode>EBADF</errorcode></term> 137 <listitem> 138 <para><parameter>fd</parameter> is not a valid file 139descriptor or is not open for reading, or the process already has the 140maximum number of files open.</para> 141 </listitem> 142 </varlistentry> 143 <varlistentry> 144 <term><errorcode>EBUSY</errorcode></term> 145 <listitem> 146 <para>The driver does not support multiple read streams and the 147device is already in use.</para> 148 </listitem> 149 </varlistentry> 150 <varlistentry> 151 <term><errorcode>EFAULT</errorcode></term> 152 <listitem> 153 <para><parameter>buf</parameter> references an inaccessible 154memory area.</para> 155 </listitem> 156 </varlistentry> 157 <varlistentry> 158 <term><errorcode>EINTR</errorcode></term> 159 <listitem> 160 <para>The call was interrupted by a signal before any 161data was read.</para> 162 </listitem> 163 </varlistentry> 164 <varlistentry> 165 <term><errorcode>EIO</errorcode></term> 166 <listitem> 167 <para>I/O error. This indicates some hardware problem or a 168failure to communicate with a remote device (USB camera etc.).</para> 169 </listitem> 170 </varlistentry> 171 <varlistentry> 172 <term><errorcode>EINVAL</errorcode></term> 173 <listitem> 174 <para>The <function>read()</function> function is not 175supported by this driver, not on this device, or generally not on this 176type of device.</para> 177 </listitem> 178 </varlistentry> 179 </variablelist> 180 </refsect1> 181</refentry> 182 183<!-- 184Local Variables: 185mode: sgml 186sgml-parent-document: "v4l2.sgml" 187indent-tabs-mode: nil 188End: 189--> 190