1<html><head><meta http-equiv="Content-Type" content="text/html; charset=ANSI_X3.4-1968"><title>V4L2 read()</title><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"><link rel="home" href="index.html" title="LINUX MEDIA INFRASTRUCTURE API"><link rel="up" href="user-func.html" title="Appendix A. Function Reference"><link rel="prev" href="func-poll.html" title="V4L2 poll()"><link rel="next" href="func-select.html" title="V4L2 select()"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">V4L2 read()</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="func-poll.html">Prev</a> </td><th width="60%" align="center">Appendix A. Function Reference</th><td width="20%" align="right"> <a accesskey="n" href="func-select.html">Next</a></td></tr></table><hr></div><div class="refentry"><a name="func-read"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>v4l2-read — Read from a V4L2 device</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="funcsynopsis"><pre class="funcsynopsisinfo">#include <unistd.h></pre><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">ssize_t <b class="fsfunc">read</b>(</code></td><td>int <var class="pdparam">fd</var>, </td></tr><tr><td> </td><td>void *<var class="pdparam">buf</var>, </td></tr><tr><td> </td><td>size_t <var class="pdparam">count</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div></div><div class="refsect1"><a name="idp1117085860"></a><h2>Arguments</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="parameter"><code>fd</code></em></span></dt><dd><p>File descriptor returned by <a class="link" href="func-open.html" title="V4L2 open()"><code class="function">open()</code></a>.</p></dd><dt><span class="term"><em class="parameter"><code>buf</code></em></span></dt><dd><p></p></dd><dt><span class="term"><em class="parameter"><code>count</code></em></span></dt><dd><p></p></dd></dl></div></div><div class="refsect1"><a name="idp1117156500"></a><h2>Description</h2><p><code class="function">read()</code> attempts to read up to 2<em class="parameter"><code>count</code></em> bytes from file descriptor 3<em class="parameter"><code>fd</code></em> into the buffer starting at 4<em class="parameter"><code>buf</code></em>. The layout of the data in the buffer is 5discussed in the respective device interface section, see ##. If <em class="parameter"><code>count</code></em> is zero, 6<code class="function">read()</code> returns zero and has no other results. If 7<em class="parameter"><code>count</code></em> is greater than 8<code class="constant">SSIZE_MAX</code>, the result is unspecified. Regardless 9of the <em class="parameter"><code>count</code></em> value each 10<code class="function">read()</code> call will provide at most one frame (two 11fields) worth of data.</p><p>By default <code class="function">read()</code> blocks until data 12becomes available. When the <code class="constant">O_NONBLOCK</code> flag was 13given to the <a class="link" href="func-open.html" title="V4L2 open()"><code class="function">open()</code></a> function it 14returns immediately with an <span class="errorcode">EAGAIN</span> error code when no data is available. The 15<a class="link" href="func-select.html" title="V4L2 select()"><code class="function">select()</code></a> or <a class="link" href="func-poll.html" title="V4L2 poll()"><code class="function">poll()</code></a> functions 16can always be used to suspend execution until data becomes available. All 17drivers supporting the <code class="function">read()</code> function must also 18support <code class="function">select()</code> and 19<code class="function">poll()</code>.</p><p>Drivers can implement read functionality in different 20ways, using a single or multiple buffers and discarding the oldest or 21newest frames once the internal buffers are filled.</p><p><code class="function">read()</code> never returns a "snapshot" of a 22buffer being filled. Using a single buffer the driver will stop 23capturing when the application starts reading the buffer until the 24read is finished. Thus only the period of the vertical blanking 25interval is available for reading, or the capture rate must fall below 26the nominal frame rate of the video standard.</p><p>The behavior of 27<code class="function">read()</code> when called during the active picture 28period or the vertical blanking separating the top and bottom field 29depends on the discarding policy. A driver discarding the oldest 30frames keeps capturing into an internal buffer, continuously 31overwriting the previously, not read frame, and returns the frame 32being received at the time of the <code class="function">read()</code> call as 33soon as it is complete.</p><p>A driver discarding the newest frames stops capturing until 34the next <code class="function">read()</code> call. The frame being received at 35<code class="function">read()</code> time is discarded, returning the following 36frame instead. Again this implies a reduction of the capture rate to 37one half or less of the nominal frame rate. An example of this model 38is the video read mode of the bttv driver, initiating a DMA to user 39memory when <code class="function">read()</code> is called and returning when 40the DMA finished.</p><p>In the multiple buffer model drivers maintain a ring of 41internal buffers, automatically advancing to the next free buffer. 42This allows continuous capturing when the application can empty the 43buffers fast enough. Again, the behavior when the driver runs out of 44free buffers depends on the discarding policy.</p><p>Applications can get and set the number of buffers used 45internally by the driver with the <a class="link" href="vidioc-g-parm.html" title="ioctl VIDIOC_G_PARM, VIDIOC_S_PARM"><code class="constant">VIDIOC_G_PARM</code></a> and <a class="link" href="vidioc-g-parm.html" title="ioctl VIDIOC_G_PARM, VIDIOC_S_PARM"><code class="constant">VIDIOC_S_PARM</code></a> 46ioctls. They are optional, however. The discarding policy is not 47reported and cannot be changed. For minimum requirements see <a class="xref" href="devices.html" title="Chapter 4. Interfaces">Chapter 4, <i>Interfaces</i></a>.</p></div><div class="refsect1"><a name="idp1117171132"></a><h2>Return Value</h2><p>On success, the number of bytes read is returned. It is not 48an error if this number is smaller than the number of bytes requested, 49or the amount of data required for one frame. This may happen for 50example because <code class="function">read()</code> was interrupted by a 51signal. On error, -1 is returned, and the <code class="varname">errno</code> 52variable is set appropriately. In this case the next read will start 53at the beginning of a new frame. Possible error codes are:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><span class="errorcode">EAGAIN</span></span></dt><dd><p>Non-blocking I/O has been selected using 54O_NONBLOCK and no data was immediately available for reading.</p></dd><dt><span class="term"><span class="errorcode">EBADF</span></span></dt><dd><p><em class="parameter"><code>fd</code></em> is not a valid file 55descriptor or is not open for reading, or the process already has the 56maximum number of files open.</p></dd><dt><span class="term"><span class="errorcode">EBUSY</span></span></dt><dd><p>The driver does not support multiple read streams and the 57device is already in use.</p></dd><dt><span class="term"><span class="errorcode">EFAULT</span></span></dt><dd><p><em class="parameter"><code>buf</code></em> references an inaccessible 58memory area.</p></dd><dt><span class="term"><span class="errorcode">EINTR</span></span></dt><dd><p>The call was interrupted by a signal before any 59data was read.</p></dd><dt><span class="term"><span class="errorcode">EIO</span></span></dt><dd><p>I/O error. This indicates some hardware problem or a 60failure to communicate with a remote device (USB camera etc.).</p></dd><dt><span class="term"><span class="errorcode">EINVAL</span></span></dt><dd><p>The <code class="function">read()</code> function is not 61supported by this driver, not on this device, or generally not on this 62type of device.</p></dd></dl></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="func-poll.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="user-func.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="func-select.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">V4L2 poll() </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> V4L2 select()</td></tr></table></div></body></html> 63