doc/spec/r12878.htm

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd">
<HTML
><HEAD
><TITLE
>ioctl VIDIOC_QBUF, VIDIOC_DQBUF</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
REL="HOME"
TITLE="Video for Linux Two API Specification"
HREF="book1.htm"><LINK
REL="UP"
TITLE="Function Reference"
HREF="r7624.htm"><LINK
REL="PREVIOUS"
TITLE="ioctl VIDIOC_OVERLAY"
HREF="r12816.htm"><LINK
REL="NEXT"
TITLE="ioctl VIDIOC_QUERYBUF"
HREF="r13022.htm"></HEAD
><BODY
CLASS="REFENTRY"
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#840084"
ALINK="#0000FF"
><DIV
CLASS="NAVHEADER"
><TABLE
SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="3"
ALIGN="center"
>Video for Linux Two API Specification: Revision 0.24</TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="bottom"
><A
HREF="r12816.htm"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
></TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="r13022.htm"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><H1
><A
NAME="VIDIOC-QBUF"
></A
>ioctl VIDIOC_QBUF, VIDIOC_DQBUF</H1
><DIV
CLASS="REFNAMEDIV"
><A
NAME="AEN12882"
></A
><H2
>Name</H2
>VIDIOC_QBUF, VIDIOC_DQBUF&nbsp;--&nbsp;Exchange a buffer with the driver</DIV
><DIV
CLASS="REFSYNOPSISDIV"
><A
NAME="AEN12886"
></A
><H2
>Synopsis</H2
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN12887"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>int ioctl</CODE
>(int fd, int request, struct v4l2_buffer *argp);</CODE
></P
><P
></P
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN12897"
></A
><H2
>Arguments</H2
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><CODE
CLASS="PARAMETER"
>fd</CODE
></DT
><DD
><P
>File descriptor returned by <A
HREF="r14090.htm"
><CODE
CLASS="FUNCTION"
>open()</CODE
></A
>.</P
></DD
><DT
><CODE
CLASS="PARAMETER"
>request</CODE
></DT
><DD
><P
>VIDIOC_QBUF, VIDIOC_DQBUF</P
></DD
><DT
><CODE
CLASS="PARAMETER"
>argp</CODE
></DT
><DD
><P
></P
></DD
></DL
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN12917"
></A
><H2
>Description</H2
><P
>Applications call the <CODE
CLASS="CONSTANT"
>VIDIOC_QBUF</CODE
> ioctl
to enqueue an empty (capturing) or filled (output) buffer in the
driver's incoming queue. The semantics depend on the selected I/O
method.</P
><P
>To enqueue a <A
HREF="x5791.htm"
>memory mapped</A
>
buffer applications set the <CODE
CLASS="STRUCTFIELD"
>type</CODE
> field of a
struct&nbsp;<A
HREF="x5953.htm#V4L2-BUFFER"
>v4l2_buffer</A
> to the same buffer type as previously struct&nbsp;<A
HREF="r10944.htm#V4L2-FORMAT"
>v4l2_format</A
>
<CODE
CLASS="STRUCTFIELD"
>type</CODE
> and struct&nbsp;<A
HREF="r13696.htm#V4L2-REQUESTBUFFERS"
>v4l2_requestbuffers</A
>
<CODE
CLASS="STRUCTFIELD"
>type</CODE
>, the <CODE
CLASS="STRUCTFIELD"
>memory</CODE
>
field to <CODE
CLASS="CONSTANT"
>V4L2_MEMORY_MMAP</CODE
> and the
<CODE
CLASS="STRUCTFIELD"
>index</CODE
> field. Valid index numbers range from
zero to the number of buffers allocated with <A
HREF="r13696.htm"
><CODE
CLASS="CONSTANT"
>VIDIOC_REQBUFS</CODE
></A
>
(struct&nbsp;<A
HREF="r13696.htm#V4L2-REQUESTBUFFERS"
>v4l2_requestbuffers</A
> <CODE
CLASS="STRUCTFIELD"
>count</CODE
>) minus one. The
contents of the struct <CODE
CLASS="STRUCTNAME"
>v4l2_buffer</CODE
> returned
by a <A
HREF="r13022.htm"
><CODE
CLASS="CONSTANT"
>VIDIOC_QUERYBUF</CODE
></A
> ioctl will do as well. When the buffer is
intended for output (<CODE
CLASS="STRUCTFIELD"
>type</CODE
> is
<CODE
CLASS="CONSTANT"
>V4L2_BUF_TYPE_VIDEO_OUTPUT</CODE
> or
<CODE
CLASS="CONSTANT"
>V4L2_BUF_TYPE_VBI_OUTPUT</CODE
>) applications must also
initialize the <CODE
CLASS="STRUCTFIELD"
>bytesused</CODE
>,
<CODE
CLASS="STRUCTFIELD"
>field</CODE
> and
<CODE
CLASS="STRUCTFIELD"
>timestamp</CODE
> fields. See <A
HREF="x5953.htm"
>Section 3.5</A
> for details. When
<CODE
CLASS="CONSTANT"
>VIDIOC_QBUF</CODE
> is called with a pointer to this
structure the driver sets the
<CODE
CLASS="CONSTANT"
>V4L2_BUF_FLAG_MAPPED</CODE
> and
<CODE
CLASS="CONSTANT"
>V4L2_BUF_FLAG_QUEUED</CODE
> flags and clears the
<CODE
CLASS="CONSTANT"
>V4L2_BUF_FLAG_DONE</CODE
> flag in the
<CODE
CLASS="STRUCTFIELD"
>flags</CODE
> field, or it returns an
<SPAN
CLASS="ERRORCODE"
>EINVAL</SPAN
> error code.</P
><P
>To enqueue a <A
HREF="x5884.htm"
>user pointer</A
>
buffer applications set the <CODE
CLASS="STRUCTFIELD"
>type</CODE
> field of a
struct&nbsp;<A
HREF="x5953.htm#V4L2-BUFFER"
>v4l2_buffer</A
> to the same buffer type as previously struct&nbsp;<A
HREF="r10944.htm#V4L2-FORMAT"
>v4l2_format</A
>
<CODE
CLASS="STRUCTFIELD"
>type</CODE
> and struct&nbsp;<A
HREF="r13696.htm#V4L2-REQUESTBUFFERS"
>v4l2_requestbuffers</A
>
<CODE
CLASS="STRUCTFIELD"
>type</CODE
>, the <CODE
CLASS="STRUCTFIELD"
>memory</CODE
>
field to <CODE
CLASS="CONSTANT"
>V4L2_MEMORY_USERPTR</CODE
> and the
<CODE
CLASS="STRUCTFIELD"
>m.userptr</CODE
> field to the address of the
buffer and <CODE
CLASS="STRUCTFIELD"
>length</CODE
> to its size. When the
buffer is intended for output additional fields must be set as above.
When <CODE
CLASS="CONSTANT"
>VIDIOC_QBUF</CODE
> is called with a pointer to this
structure the driver sets the <CODE
CLASS="CONSTANT"
>V4L2_BUF_FLAG_QUEUED</CODE
>
flag and clears the <CODE
CLASS="CONSTANT"
>V4L2_BUF_FLAG_MAPPED</CODE
> and
<CODE
CLASS="CONSTANT"
>V4L2_BUF_FLAG_DONE</CODE
> flags in the
<CODE
CLASS="STRUCTFIELD"
>flags</CODE
> field, or it returns an error code.
This ioctl locks the memory pages of the buffer in physical memory,
they cannot be swapped out to disk. Buffers remain locked until
dequeued, until the <A
HREF="r13817.htm"
><CODE
CLASS="CONSTANT"
>VIDIOC_STREAMOFF</CODE
></A
> or <A
HREF="r13696.htm"
><CODE
CLASS="CONSTANT"
>VIDIOC_REQBUFS</CODE
></A
> ioctl are
called, or until the device is closed.</P
><P
>Applications call the <CODE
CLASS="CONSTANT"
>VIDIOC_DQBUF</CODE
>
ioctl to dequeue a filled (capturing) or displayed (output) buffer
from the driver's outgoing queue. They just set the
<CODE
CLASS="STRUCTFIELD"
>type</CODE
> and <CODE
CLASS="STRUCTFIELD"
>memory</CODE
>
fields of a struct&nbsp;<A
HREF="x5953.htm#V4L2-BUFFER"
>v4l2_buffer</A
> as above, when <CODE
CLASS="CONSTANT"
>VIDIOC_DQBUF</CODE
>
is called with a pointer to this structure the driver fills the
remaining fields or returns an error code.</P
><P
>By default <CODE
CLASS="CONSTANT"
>VIDIOC_DQBUF</CODE
> blocks when no
buffer is in the outgoing queue. When the
<CODE
CLASS="CONSTANT"
>O_NONBLOCK</CODE
> flag was given to the <A
HREF="r14090.htm"
><CODE
CLASS="FUNCTION"
>open()</CODE
></A
>
function, <CODE
CLASS="CONSTANT"
>VIDIOC_DQBUF</CODE
> returns immediately
with an <SPAN
CLASS="ERRORCODE"
>EAGAIN</SPAN
> error code when no buffer is available.</P
><P
>The <CODE
CLASS="STRUCTNAME"
>v4l2_buffer</CODE
> structure is
specified in <A
HREF="x5953.htm"
>Section 3.5</A
>.</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN12989"
></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:</P
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><SPAN
CLASS="ERRORCODE"
>EAGAIN</SPAN
></DT
><DD
><P
>Non-blocking I/O has been selected using
<CODE
CLASS="CONSTANT"
>O_NONBLOCK</CODE
> and no buffer was in the outgoing
queue.</P
></DD
><DT
><SPAN
CLASS="ERRORCODE"
>EINVAL</SPAN
></DT
><DD
><P
>The buffer <CODE
CLASS="STRUCTFIELD"
>type</CODE
> is not
supported, or the <CODE
CLASS="STRUCTFIELD"
>index</CODE
> is out of bounds,
or no buffers have been allocated yet, or the
<CODE
CLASS="STRUCTFIELD"
>userptr</CODE
> or
<CODE
CLASS="STRUCTFIELD"
>length</CODE
> are invalid.</P
></DD
><DT
><SPAN
CLASS="ERRORCODE"
>ENOMEM</SPAN
></DT
><DD
><P
>Not enough physical or virtual memory was available to
enqueue a user pointer buffer.</P
></DD
><DT
><SPAN
CLASS="ERRORCODE"
>EIO</SPAN
></DT
><DD
><P
><CODE
CLASS="CONSTANT"
>VIDIOC_DQBUF</CODE
> failed due to an
internal error. Can also indicate temporary problems like signal
loss. Note the driver might dequeue an (empty) buffer despite
returning an error, or even stop capturing.</P
></DD
></DL
></DIV
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
SUMMARY="Footer navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="r12816.htm"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="book1.htm"
ACCESSKEY="H"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="r13022.htm"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>ioctl VIDIOC_OVERLAY</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="r7624.htm"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>ioctl VIDIOC_QUERYBUF</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>