• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd">
2<HTML
3><HEAD
4><TITLE
5>ioctl VIDIOC_QBUF, VIDIOC_DQBUF</TITLE
6><META
7NAME="GENERATOR"
8CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
9REL="HOME"
10TITLE="Video for Linux Two API Specification"
11HREF="book1.htm"><LINK
12REL="UP"
13TITLE="Function Reference"
14HREF="r7624.htm"><LINK
15REL="PREVIOUS"
16TITLE="ioctl VIDIOC_OVERLAY"
17HREF="r12816.htm"><LINK
18REL="NEXT"
19TITLE="ioctl VIDIOC_QUERYBUF"
20HREF="r13022.htm"></HEAD
21><BODY
22CLASS="REFENTRY"
23BGCOLOR="#FFFFFF"
24TEXT="#000000"
25LINK="#0000FF"
26VLINK="#840084"
27ALINK="#0000FF"
28><DIV
29CLASS="NAVHEADER"
30><TABLE
31SUMMARY="Header navigation table"
32WIDTH="100%"
33BORDER="0"
34CELLPADDING="0"
35CELLSPACING="0"
36><TR
37><TH
38COLSPAN="3"
39ALIGN="center"
40>Video for Linux Two API Specification: Revision 0.24</TH
41></TR
42><TR
43><TD
44WIDTH="10%"
45ALIGN="left"
46VALIGN="bottom"
47><A
48HREF="r12816.htm"
49ACCESSKEY="P"
50>Prev</A
51></TD
52><TD
53WIDTH="80%"
54ALIGN="center"
55VALIGN="bottom"
56></TD
57><TD
58WIDTH="10%"
59ALIGN="right"
60VALIGN="bottom"
61><A
62HREF="r13022.htm"
63ACCESSKEY="N"
64>Next</A
65></TD
66></TR
67></TABLE
68><HR
69ALIGN="LEFT"
70WIDTH="100%"></DIV
71><H1
72><A
73NAME="VIDIOC-QBUF"
74></A
75>ioctl VIDIOC_QBUF, VIDIOC_DQBUF</H1
76><DIV
77CLASS="REFNAMEDIV"
78><A
79NAME="AEN12882"
80></A
81><H2
82>Name</H2
83>VIDIOC_QBUF, VIDIOC_DQBUF&nbsp;--&nbsp;Exchange a buffer with the driver</DIV
84><DIV
85CLASS="REFSYNOPSISDIV"
86><A
87NAME="AEN12886"
88></A
89><H2
90>Synopsis</H2
91><DIV
92CLASS="FUNCSYNOPSIS"
93><P
94></P
95><A
96NAME="AEN12887"
97></A
98><P
99><CODE
100><CODE
101CLASS="FUNCDEF"
102>int ioctl</CODE
103>(int fd, int request, struct v4l2_buffer *argp);</CODE
104></P
105><P
106></P
107></DIV
108></DIV
109><DIV
110CLASS="REFSECT1"
111><A
112NAME="AEN12897"
113></A
114><H2
115>Arguments</H2
116><P
117></P
118><DIV
119CLASS="VARIABLELIST"
120><DL
121><DT
122><CODE
123CLASS="PARAMETER"
124>fd</CODE
125></DT
126><DD
127><P
128>File descriptor returned by <A
129HREF="r14090.htm"
130><CODE
131CLASS="FUNCTION"
132>open()</CODE
133></A
134>.</P
135></DD
136><DT
137><CODE
138CLASS="PARAMETER"
139>request</CODE
140></DT
141><DD
142><P
143>VIDIOC_QBUF, VIDIOC_DQBUF</P
144></DD
145><DT
146><CODE
147CLASS="PARAMETER"
148>argp</CODE
149></DT
150><DD
151><P
152></P
153></DD
154></DL
155></DIV
156></DIV
157><DIV
158CLASS="REFSECT1"
159><A
160NAME="AEN12917"
161></A
162><H2
163>Description</H2
164><P
165>Applications call the <CODE
166CLASS="CONSTANT"
167>VIDIOC_QBUF</CODE
168> ioctl
169to enqueue an empty (capturing) or filled (output) buffer in the
170driver's incoming queue. The semantics depend on the selected I/O
171method.</P
172><P
173>To enqueue a <A
174HREF="x5791.htm"
175>memory mapped</A
176>
177buffer applications set the <CODE
178CLASS="STRUCTFIELD"
179>type</CODE
180> field of a
181struct&nbsp;<A
182HREF="x5953.htm#V4L2-BUFFER"
183>v4l2_buffer</A
184> to the same buffer type as previously struct&nbsp;<A
185HREF="r10944.htm#V4L2-FORMAT"
186>v4l2_format</A
187>
188<CODE
189CLASS="STRUCTFIELD"
190>type</CODE
191> and struct&nbsp;<A
192HREF="r13696.htm#V4L2-REQUESTBUFFERS"
193>v4l2_requestbuffers</A
194>
195<CODE
196CLASS="STRUCTFIELD"
197>type</CODE
198>, the <CODE
199CLASS="STRUCTFIELD"
200>memory</CODE
201>
202field to <CODE
203CLASS="CONSTANT"
204>V4L2_MEMORY_MMAP</CODE
205> and the
206<CODE
207CLASS="STRUCTFIELD"
208>index</CODE
209> field. Valid index numbers range from
210zero to the number of buffers allocated with <A
211HREF="r13696.htm"
212><CODE
213CLASS="CONSTANT"
214>VIDIOC_REQBUFS</CODE
215></A
216>
217(struct&nbsp;<A
218HREF="r13696.htm#V4L2-REQUESTBUFFERS"
219>v4l2_requestbuffers</A
220> <CODE
221CLASS="STRUCTFIELD"
222>count</CODE
223>) minus one. The
224contents of the struct <CODE
225CLASS="STRUCTNAME"
226>v4l2_buffer</CODE
227> returned
228by a <A
229HREF="r13022.htm"
230><CODE
231CLASS="CONSTANT"
232>VIDIOC_QUERYBUF</CODE
233></A
234> ioctl will do as well. When the buffer is
235intended for output (<CODE
236CLASS="STRUCTFIELD"
237>type</CODE
238> is
239<CODE
240CLASS="CONSTANT"
241>V4L2_BUF_TYPE_VIDEO_OUTPUT</CODE
242> or
243<CODE
244CLASS="CONSTANT"
245>V4L2_BUF_TYPE_VBI_OUTPUT</CODE
246>) applications must also
247initialize the <CODE
248CLASS="STRUCTFIELD"
249>bytesused</CODE
250>,
251<CODE
252CLASS="STRUCTFIELD"
253>field</CODE
254> and
255<CODE
256CLASS="STRUCTFIELD"
257>timestamp</CODE
258> fields. See <A
259HREF="x5953.htm"
260>Section 3.5</A
261> for details. When
262<CODE
263CLASS="CONSTANT"
264>VIDIOC_QBUF</CODE
265> is called with a pointer to this
266structure the driver sets the
267<CODE
268CLASS="CONSTANT"
269>V4L2_BUF_FLAG_MAPPED</CODE
270> and
271<CODE
272CLASS="CONSTANT"
273>V4L2_BUF_FLAG_QUEUED</CODE
274> flags and clears the
275<CODE
276CLASS="CONSTANT"
277>V4L2_BUF_FLAG_DONE</CODE
278> flag in the
279<CODE
280CLASS="STRUCTFIELD"
281>flags</CODE
282> field, or it returns an
283<SPAN
284CLASS="ERRORCODE"
285>EINVAL</SPAN
286> error code.</P
287><P
288>To enqueue a <A
289HREF="x5884.htm"
290>user pointer</A
291>
292buffer applications set the <CODE
293CLASS="STRUCTFIELD"
294>type</CODE
295> field of a
296struct&nbsp;<A
297HREF="x5953.htm#V4L2-BUFFER"
298>v4l2_buffer</A
299> to the same buffer type as previously struct&nbsp;<A
300HREF="r10944.htm#V4L2-FORMAT"
301>v4l2_format</A
302>
303<CODE
304CLASS="STRUCTFIELD"
305>type</CODE
306> and struct&nbsp;<A
307HREF="r13696.htm#V4L2-REQUESTBUFFERS"
308>v4l2_requestbuffers</A
309>
310<CODE
311CLASS="STRUCTFIELD"
312>type</CODE
313>, the <CODE
314CLASS="STRUCTFIELD"
315>memory</CODE
316>
317field to <CODE
318CLASS="CONSTANT"
319>V4L2_MEMORY_USERPTR</CODE
320> and the
321<CODE
322CLASS="STRUCTFIELD"
323>m.userptr</CODE
324> field to the address of the
325buffer and <CODE
326CLASS="STRUCTFIELD"
327>length</CODE
328> to its size. When the
329buffer is intended for output additional fields must be set as above.
330When <CODE
331CLASS="CONSTANT"
332>VIDIOC_QBUF</CODE
333> is called with a pointer to this
334structure the driver sets the <CODE
335CLASS="CONSTANT"
336>V4L2_BUF_FLAG_QUEUED</CODE
337>
338flag and clears the <CODE
339CLASS="CONSTANT"
340>V4L2_BUF_FLAG_MAPPED</CODE
341> and
342<CODE
343CLASS="CONSTANT"
344>V4L2_BUF_FLAG_DONE</CODE
345> flags in the
346<CODE
347CLASS="STRUCTFIELD"
348>flags</CODE
349> field, or it returns an error code.
350This ioctl locks the memory pages of the buffer in physical memory,
351they cannot be swapped out to disk. Buffers remain locked until
352dequeued, until the <A
353HREF="r13817.htm"
354><CODE
355CLASS="CONSTANT"
356>VIDIOC_STREAMOFF</CODE
357></A
358> or <A
359HREF="r13696.htm"
360><CODE
361CLASS="CONSTANT"
362>VIDIOC_REQBUFS</CODE
363></A
364> ioctl are
365called, or until the device is closed.</P
366><P
367>Applications call the <CODE
368CLASS="CONSTANT"
369>VIDIOC_DQBUF</CODE
370>
371ioctl to dequeue a filled (capturing) or displayed (output) buffer
372from the driver's outgoing queue. They just set the
373<CODE
374CLASS="STRUCTFIELD"
375>type</CODE
376> and <CODE
377CLASS="STRUCTFIELD"
378>memory</CODE
379>
380fields of a struct&nbsp;<A
381HREF="x5953.htm#V4L2-BUFFER"
382>v4l2_buffer</A
383> as above, when <CODE
384CLASS="CONSTANT"
385>VIDIOC_DQBUF</CODE
386>
387is called with a pointer to this structure the driver fills the
388remaining fields or returns an error code.</P
389><P
390>By default <CODE
391CLASS="CONSTANT"
392>VIDIOC_DQBUF</CODE
393> blocks when no
394buffer is in the outgoing queue. When the
395<CODE
396CLASS="CONSTANT"
397>O_NONBLOCK</CODE
398> flag was given to the <A
399HREF="r14090.htm"
400><CODE
401CLASS="FUNCTION"
402>open()</CODE
403></A
404>
405function, <CODE
406CLASS="CONSTANT"
407>VIDIOC_DQBUF</CODE
408> returns immediately
409with an <SPAN
410CLASS="ERRORCODE"
411>EAGAIN</SPAN
412> error code when no buffer is available.</P
413><P
414>The <CODE
415CLASS="STRUCTNAME"
416>v4l2_buffer</CODE
417> structure is
418specified in <A
419HREF="x5953.htm"
420>Section 3.5</A
421>.</P
422></DIV
423><DIV
424CLASS="REFSECT1"
425><A
426NAME="AEN12989"
427></A
428><H2
429>Return Value</H2
430><P
431>On success <SPAN
432CLASS="RETURNVALUE"
433>0</SPAN
434> is returned, on error <SPAN
435CLASS="RETURNVALUE"
436>-1</SPAN
437> and the <CODE
438CLASS="VARNAME"
439>errno</CODE
440> variable is set appropriately:</P
441><P
442></P
443><DIV
444CLASS="VARIABLELIST"
445><DL
446><DT
447><SPAN
448CLASS="ERRORCODE"
449>EAGAIN</SPAN
450></DT
451><DD
452><P
453>Non-blocking I/O has been selected using
454<CODE
455CLASS="CONSTANT"
456>O_NONBLOCK</CODE
457> and no buffer was in the outgoing
458queue.</P
459></DD
460><DT
461><SPAN
462CLASS="ERRORCODE"
463>EINVAL</SPAN
464></DT
465><DD
466><P
467>The buffer <CODE
468CLASS="STRUCTFIELD"
469>type</CODE
470> is not
471supported, or the <CODE
472CLASS="STRUCTFIELD"
473>index</CODE
474> is out of bounds,
475or no buffers have been allocated yet, or the
476<CODE
477CLASS="STRUCTFIELD"
478>userptr</CODE
479> or
480<CODE
481CLASS="STRUCTFIELD"
482>length</CODE
483> are invalid.</P
484></DD
485><DT
486><SPAN
487CLASS="ERRORCODE"
488>ENOMEM</SPAN
489></DT
490><DD
491><P
492>Not enough physical or virtual memory was available to
493enqueue a user pointer buffer.</P
494></DD
495><DT
496><SPAN
497CLASS="ERRORCODE"
498>EIO</SPAN
499></DT
500><DD
501><P
502><CODE
503CLASS="CONSTANT"
504>VIDIOC_DQBUF</CODE
505> failed due to an
506internal error. Can also indicate temporary problems like signal
507loss. Note the driver might dequeue an (empty) buffer despite
508returning an error, or even stop capturing.</P
509></DD
510></DL
511></DIV
512></DIV
513><DIV
514CLASS="NAVFOOTER"
515><HR
516ALIGN="LEFT"
517WIDTH="100%"><TABLE
518SUMMARY="Footer navigation table"
519WIDTH="100%"
520BORDER="0"
521CELLPADDING="0"
522CELLSPACING="0"
523><TR
524><TD
525WIDTH="33%"
526ALIGN="left"
527VALIGN="top"
528><A
529HREF="r12816.htm"
530ACCESSKEY="P"
531>Prev</A
532></TD
533><TD
534WIDTH="34%"
535ALIGN="center"
536VALIGN="top"
537><A
538HREF="book1.htm"
539ACCESSKEY="H"
540>Home</A
541></TD
542><TD
543WIDTH="33%"
544ALIGN="right"
545VALIGN="top"
546><A
547HREF="r13022.htm"
548ACCESSKEY="N"
549>Next</A
550></TD
551></TR
552><TR
553><TD
554WIDTH="33%"
555ALIGN="left"
556VALIGN="top"
557>ioctl VIDIOC_OVERLAY</TD
558><TD
559WIDTH="34%"
560ALIGN="center"
561VALIGN="top"
562><A
563HREF="r7624.htm"
564ACCESSKEY="U"
565>Up</A
566></TD
567><TD
568WIDTH="33%"
569ALIGN="right"
570VALIGN="top"
571>ioctl VIDIOC_QUERYBUF</TD
572></TR
573></TABLE
574></DIV
575></BODY
576></HTML
577>
578