1<html><head><meta http-equiv="Content-Type" content="text/html; charset=ANSI_X3.4-1968"><title>ioctl VIDIOC_QBUF, VIDIOC_DQBUF</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="vidioc-prepare-buf.html" title="ioctl VIDIOC_PREPARE_BUF"><link rel="next" href="vidioc-querybuf.html" title="ioctl VIDIOC_QUERYBUF"></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">ioctl VIDIOC_QBUF, VIDIOC_DQBUF</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="vidioc-prepare-buf.html">Prev</a> </td><th width="60%" align="center">Appendix A. Function Reference</th><td width="20%" align="right"> <a accesskey="n" href="vidioc-querybuf.html">Next</a></td></tr></table><hr></div><div class="refentry"><a name="vidioc-qbuf"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>VIDIOC_QBUF, VIDIOC_DQBUF — Exchange a buffer with the driver</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="funcsynopsis"><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">int <b class="fsfunc">ioctl</b>(</code></td><td>int <var class="pdparam">fd</var>, </td></tr><tr><td> </td><td>int <var class="pdparam">request</var>, </td></tr><tr><td> </td><td>struct v4l2_buffer *<var class="pdparam">argp</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div></div><div class="refsect1"><a name="idp1115593644"></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>request</code></em></span></dt><dd><p>VIDIOC_QBUF, VIDIOC_DQBUF</p></dd><dt><span class="term"><em class="parameter"><code>argp</code></em></span></dt><dd><p></p></dd></dl></div></div><div class="refsect1"><a name="idp1115650868"></a><h2>Description</h2><p>Applications call the <code class="constant">VIDIOC_QBUF</code> ioctl 2to enqueue an empty (capturing) or filled (output) buffer in the 3driver's incoming queue. The semantics depend on the selected I/O 4method.</p><p>To enqueue a buffer applications set the <em class="structfield"><code>type</code></em> 5field of a struct <a class="link" href="buffer.html#v4l2-buffer" title="Table 3.1. struct v4l2_buffer">v4l2_buffer</a> to the same buffer type as was previously used 6with struct <a class="link" href="vidioc-g-fmt.html#v4l2-format" title="Table A.72. struct v4l2_format">v4l2_format</a> <em class="structfield"><code>type</code></em> and struct <a class="link" href="vidioc-reqbufs.html#v4l2-requestbuffers" title="Table A.100. struct v4l2_requestbuffers">v4l2_requestbuffers</a> 7<em class="structfield"><code>type</code></em>. Applications must also set the 8<em class="structfield"><code>index</code></em> field. Valid index numbers range from 9zero to the number of buffers allocated with <a class="link" href="vidioc-reqbufs.html" title="ioctl VIDIOC_REQBUFS"><code class="constant">VIDIOC_REQBUFS</code></a> 10(struct <a class="link" href="vidioc-reqbufs.html#v4l2-requestbuffers" title="Table A.100. struct v4l2_requestbuffers">v4l2_requestbuffers</a> <em class="structfield"><code>count</code></em>) minus one. The 11contents of the struct <span class="structname">v4l2_buffer</span> returned 12by a <a class="link" href="vidioc-querybuf.html" title="ioctl VIDIOC_QUERYBUF"><code class="constant">VIDIOC_QUERYBUF</code></a> ioctl will do as well. When the buffer is 13intended for output (<em class="structfield"><code>type</code></em> is 14<code class="constant">V4L2_BUF_TYPE_VIDEO_OUTPUT</code>, 15<code class="constant">V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE</code>, or 16<code class="constant">V4L2_BUF_TYPE_VBI_OUTPUT</code>) applications must also 17initialize the <em class="structfield"><code>bytesused</code></em>, 18<em class="structfield"><code>field</code></em> and 19<em class="structfield"><code>timestamp</code></em> fields, see <a class="xref" href="buffer.html" title="Buffers">the section called “Buffers”</a> for details. 20Applications must also set <em class="structfield"><code>flags</code></em> to 0. 21The <em class="structfield"><code>reserved2</code></em> and 22<em class="structfield"><code>reserved</code></em> fields must be set to 0. When using 23the <a class="link" href="planar-apis.html" title="Single- and multi-planar APIs">multi-planar API</a>, the 24<em class="structfield"><code>m.planes</code></em> field must contain a userspace pointer 25to a filled-in array of struct <a class="link" href="buffer.html#v4l2-plane" title="Table 3.2. struct v4l2_plane">v4l2_plane</a> and the <em class="structfield"><code>length</code></em> 26field must be set to the number of elements in that array. 27</p><p>To enqueue a <a class="link" href="mmap.html" title="Streaming I/O (Memory Mapping)">memory mapped</a> 28buffer applications set the <em class="structfield"><code>memory</code></em> 29field to <code class="constant">V4L2_MEMORY_MMAP</code>. When 30<code class="constant">VIDIOC_QBUF</code> is called with a pointer to this 31structure the driver sets the 32<code class="constant">V4L2_BUF_FLAG_MAPPED</code> and 33<code class="constant">V4L2_BUF_FLAG_QUEUED</code> flags and clears the 34<code class="constant">V4L2_BUF_FLAG_DONE</code> flag in the 35<em class="structfield"><code>flags</code></em> field, or it returns an 36<span class="errorcode">EINVAL</span> error code.</p><p>To enqueue a <a class="link" href="userp.html" title="Streaming I/O (User Pointers)">user pointer</a> 37buffer applications set the <em class="structfield"><code>memory</code></em> 38field to <code class="constant">V4L2_MEMORY_USERPTR</code>, the 39<em class="structfield"><code>m.userptr</code></em> field to the address of the 40buffer and <em class="structfield"><code>length</code></em> to its size. When the multi-planar 41API is used, <em class="structfield"><code>m.userptr</code></em> and 42<em class="structfield"><code>length</code></em> members of the passed array of struct <a class="link" href="buffer.html#v4l2-plane" title="Table 3.2. struct v4l2_plane">v4l2_plane</a> 43have to be used instead. When <code class="constant">VIDIOC_QBUF</code> is called with 44a pointer to this structure the driver sets the 45<code class="constant">V4L2_BUF_FLAG_QUEUED</code> flag and clears the 46<code class="constant">V4L2_BUF_FLAG_MAPPED</code> and 47<code class="constant">V4L2_BUF_FLAG_DONE</code> flags in the 48<em class="structfield"><code>flags</code></em> field, or it returns an error code. 49This ioctl locks the memory pages of the buffer in physical memory, 50they cannot be swapped out to disk. Buffers remain locked until 51dequeued, until the <a class="link" href="vidioc-streamon.html" title="ioctl VIDIOC_STREAMON, VIDIOC_STREAMOFF"><code class="constant">VIDIOC_STREAMOFF</code></a> or <a class="link" href="vidioc-reqbufs.html" title="ioctl VIDIOC_REQBUFS"><code class="constant">VIDIOC_REQBUFS</code></a> ioctl is 52called, or until the device is closed.</p><p>To enqueue a <a class="link" href="dmabuf.html" title="Streaming I/O (DMA buffer importing)">DMABUF</a> buffer applications 53set the <em class="structfield"><code>memory</code></em> field to 54<code class="constant">V4L2_MEMORY_DMABUF</code> and the <em class="structfield"><code>m.fd</code></em> 55field to a file descriptor associated with a DMABUF buffer. When the 56multi-planar API is used the <em class="structfield"><code>m.fd</code></em> fields of the 57passed array of struct <a class="link" href="buffer.html#v4l2-plane" title="Table 3.2. struct v4l2_plane">v4l2_plane</a> have to be used instead. When 58<code class="constant">VIDIOC_QBUF</code> is called with a pointer to this structure the 59driver sets the <code class="constant">V4L2_BUF_FLAG_QUEUED</code> flag and clears the 60<code class="constant">V4L2_BUF_FLAG_MAPPED</code> and 61<code class="constant">V4L2_BUF_FLAG_DONE</code> flags in the 62<em class="structfield"><code>flags</code></em> field, or it returns an error code. This 63ioctl locks the buffer. Locking a buffer means passing it to a driver for a 64hardware access (usually DMA). If an application accesses (reads/writes) a 65locked buffer then the result is undefined. Buffers remain locked until 66dequeued, until the <a class="link" href="vidioc-streamon.html" title="ioctl VIDIOC_STREAMON, VIDIOC_STREAMOFF"><code class="constant">VIDIOC_STREAMOFF</code></a> or <a class="link" href="vidioc-reqbufs.html" title="ioctl VIDIOC_REQBUFS"><code class="constant">VIDIOC_REQBUFS</code></a> ioctl is called, or 67until the device is closed.</p><p>Applications call the <code class="constant">VIDIOC_DQBUF</code> 68ioctl to dequeue a filled (capturing) or displayed (output) buffer 69from the driver's outgoing queue. They just set the 70<em class="structfield"><code>type</code></em>, <em class="structfield"><code>memory</code></em> 71and <em class="structfield"><code>reserved</code></em> 72fields of a struct <a class="link" href="buffer.html#v4l2-buffer" title="Table 3.1. struct v4l2_buffer">v4l2_buffer</a> as above, when <code class="constant">VIDIOC_DQBUF</code> 73is called with a pointer to this structure the driver fills the 74remaining fields or returns an error code. The driver may also set 75<code class="constant">V4L2_BUF_FLAG_ERROR</code> in the <em class="structfield"><code>flags</code></em> 76field. It indicates a non-critical (recoverable) streaming error. In such case 77the application may continue as normal, but should be aware that data in the 78dequeued buffer might be corrupted. When using the multi-planar API, the 79planes array must be passed in as well.</p><p>By default <code class="constant">VIDIOC_DQBUF</code> blocks when no 80buffer is in the outgoing queue. When the 81<code class="constant">O_NONBLOCK</code> flag was given to the <a class="link" href="func-open.html" title="V4L2 open()"><code class="function">open()</code></a> 82function, <code class="constant">VIDIOC_DQBUF</code> returns immediately 83with an <span class="errorcode">EAGAIN</span> error code when no buffer is available.</p><p>The <span class="structname">v4l2_buffer</span> structure is 84specified in <a class="xref" href="buffer.html" title="Buffers">the section called “Buffers”</a>.</p></div><div class="refsect1"><a name="idp1115677580"></a><h2>Return Value</h2><p>On success <span class="returnvalue">0</span> is returned, on error <span class="returnvalue">-1</span> and the <code class="varname">errno</code> variable is set appropriately. The generic error codes are described at the <a class="link" href="gen_errors.html#gen-errors" title="Table 19.1. Generic error codes">Generic Error Codes</a> chapter.</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 85<code class="constant">O_NONBLOCK</code> and no buffer was in the outgoing 86queue.</p></dd><dt><span class="term"><span class="errorcode">EINVAL</span></span></dt><dd><p>The buffer <em class="structfield"><code>type</code></em> is not 87supported, or the <em class="structfield"><code>index</code></em> is out of bounds, 88or no buffers have been allocated yet, or the 89<em class="structfield"><code>userptr</code></em> or 90<em class="structfield"><code>length</code></em> are invalid.</p></dd><dt><span class="term"><span class="errorcode">EIO</span></span></dt><dd><p><code class="constant">VIDIOC_DQBUF</code> failed due to an 91internal error. Can also indicate temporary problems like signal 92loss. Note the driver might dequeue an (empty) buffer despite 93returning an error, or even stop capturing. Reusing such buffer may be unsafe 94though and its details (e.g. <em class="structfield"><code>index</code></em>) may not be 95returned either. It is recommended that drivers indicate recoverable errors 96by setting the <code class="constant">V4L2_BUF_FLAG_ERROR</code> and returning 0 instead. 97In that case the application should be able to safely reuse the buffer and 98continue streaming. 99 </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="vidioc-prepare-buf.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="vidioc-querybuf.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">ioctl VIDIOC_PREPARE_BUF </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> ioctl VIDIOC_QUERYBUF</td></tr></table></div></body></html> 100