• 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>V4L2 read()</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="V4L2 poll()"
17HREF="r14169.htm"><LINK
18REL="NEXT"
19TITLE="V4L2 select()"
20HREF="r14390.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="r14169.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="r14390.htm"
63ACCESSKEY="N"
64>Next</A
65></TD
66></TR
67></TABLE
68><HR
69ALIGN="LEFT"
70WIDTH="100%"></DIV
71><H1
72><A
73NAME="FUNC-READ"
74></A
75>V4L2 read()</H1
76><DIV
77CLASS="REFNAMEDIV"
78><A
79NAME="AEN14268"
80></A
81><H2
82>Name</H2
83>v4l2-read&nbsp;--&nbsp;Read from a V4L2 device</DIV
84><DIV
85CLASS="REFSYNOPSISDIV"
86><A
87NAME="AEN14271"
88></A
89><H2
90>Synopsis</H2
91><DIV
92CLASS="FUNCSYNOPSIS"
93><P
94></P
95><A
96NAME="AEN14272"
97></A
98><PRE
99CLASS="FUNCSYNOPSISINFO"
100>#include &lt;unistd.h&gt;</PRE
101><P
102><CODE
103><CODE
104CLASS="FUNCDEF"
105>ssize_t read</CODE
106>(int fd, void *buf, size_t count);</CODE
107></P
108><P
109></P
110></DIV
111></DIV
112><DIV
113CLASS="REFSECT1"
114><A
115NAME="AEN14283"
116></A
117><H2
118>Arguments</H2
119><P
120></P
121><DIV
122CLASS="VARIABLELIST"
123><DL
124><DT
125><CODE
126CLASS="PARAMETER"
127>fd</CODE
128></DT
129><DD
130><P
131>File descriptor returned by <A
132HREF="r14090.htm"
133><CODE
134CLASS="FUNCTION"
135>open()</CODE
136></A
137>.</P
138></DD
139><DT
140><CODE
141CLASS="PARAMETER"
142>buf</CODE
143></DT
144><DD
145><P
146></P
147></DD
148><DT
149><CODE
150CLASS="PARAMETER"
151>count</CODE
152></DT
153><DD
154><P
155></P
156></DD
157></DL
158></DIV
159></DIV
160><DIV
161CLASS="REFSECT1"
162><A
163NAME="AEN14303"
164></A
165><H2
166>Description</H2
167><P
168><CODE
169CLASS="FUNCTION"
170>read()</CODE
171> attempts to read up to
172<CODE
173CLASS="PARAMETER"
174>count</CODE
175> bytes from file descriptor
176<CODE
177CLASS="PARAMETER"
178>fd</CODE
179> into the buffer starting at
180<CODE
181CLASS="PARAMETER"
182>buf</CODE
183>. The layout of the data in the buffer is
184discussed in the respective device interface section, see ##. If <CODE
185CLASS="PARAMETER"
186>count</CODE
187> is zero,
188<CODE
189CLASS="FUNCTION"
190>read()</CODE
191> returns zero and has no other results. If
192<CODE
193CLASS="PARAMETER"
194>count</CODE
195> is greater than
196<CODE
197CLASS="CONSTANT"
198>SSIZE_MAX</CODE
199>, the result is unspecified. Regardless
200of the <CODE
201CLASS="PARAMETER"
202>count</CODE
203> value each
204<CODE
205CLASS="FUNCTION"
206>read()</CODE
207> call will provide at most one frame (two
208fields) worth of data.</P
209><P
210>By default <CODE
211CLASS="FUNCTION"
212>read()</CODE
213> blocks until data
214becomes available. When the <CODE
215CLASS="CONSTANT"
216>O_NONBLOCK</CODE
217> flag was
218given to the <A
219HREF="r14090.htm"
220><CODE
221CLASS="FUNCTION"
222>open()</CODE
223></A
224> function it
225returns immediately with an <SPAN
226CLASS="ERRORCODE"
227>EAGAIN</SPAN
228> error code when no data is available. The
229<A
230HREF="r14390.htm"
231><CODE
232CLASS="FUNCTION"
233>select()</CODE
234></A
235> or <A
236HREF="r14169.htm"
237><CODE
238CLASS="FUNCTION"
239>poll()</CODE
240></A
241> functions
242can always be used to suspend execution until data becomes available. All
243drivers supporting the <CODE
244CLASS="FUNCTION"
245>read()</CODE
246> function must also
247support <CODE
248CLASS="FUNCTION"
249>select()</CODE
250> and
251<CODE
252CLASS="FUNCTION"
253>poll()</CODE
254>.</P
255><P
256>Drivers can implement read functionality in different
257ways, using a single or multiple buffers and discarding the oldest or
258newest frames once the internal buffers are filled.</P
259><P
260><CODE
261CLASS="FUNCTION"
262>read()</CODE
263> never returns a "snapshot" of a
264buffer being filled. Using a single buffer the driver will stop
265capturing when the application starts reading the buffer until the
266read is finished. Thus only the period of the vertical blanking
267interval is available for reading, or the capture rate must fall below
268the nominal frame rate of the video standard.</P
269><P
270>The behavior of
271<CODE
272CLASS="FUNCTION"
273>read()</CODE
274> when called during the active picture
275period or the vertical blanking separating the top and bottom field
276depends on the discarding policy. A driver discarding the oldest
277frames keeps capturing into an internal buffer, continuously
278overwriting the previously, not read frame, and returns the frame
279being received at the time of the <CODE
280CLASS="FUNCTION"
281>read()</CODE
282> call as
283soon as it is complete.</P
284><P
285>A driver discarding the newest frames stops capturing until
286the next <CODE
287CLASS="FUNCTION"
288>read()</CODE
289> call. The frame being received at
290<CODE
291CLASS="FUNCTION"
292>read()</CODE
293> time is discarded, returning the following
294frame instead. Again this implies a reduction of the capture rate to
295one half or less of the nominal frame rate. An example of this model
296is the video read mode of the bttv driver, initiating a DMA to user
297memory when <CODE
298CLASS="FUNCTION"
299>read()</CODE
300> is called and returning when
301the DMA finished.</P
302><P
303>In the multiple buffer model drivers maintain a ring of
304internal buffers, automatically advancing to the next free buffer.
305This allows continuous capturing when the application can empty the
306buffers fast enough. Again, the behavior when the driver runs out of
307free buffers depends on the discarding policy.</P
308><P
309>Applications can get and set the number of buffers used
310internally by the driver with the <A
311HREF="r11680.htm"
312><CODE
313CLASS="CONSTANT"
314>VIDIOC_G_PARM</CODE
315></A
316> and <A
317HREF="r11680.htm"
318><CODE
319CLASS="CONSTANT"
320>VIDIOC_S_PARM</CODE
321></A
322>
323ioctls. They are optional, however. The discarding policy is not
324reported and cannot be changed. For minimum requirements see <A
325HREF="c6488.htm"
326>Chapter 4</A
327>.</P
328></DIV
329><DIV
330CLASS="REFSECT1"
331><A
332NAME="AEN14346"
333></A
334><H2
335>Return Value</H2
336><P
337>On success, the number of bytes read is returned. It is not
338an error if this number is smaller than the number of bytes requested,
339or the amount of data required for one frame. This may happen for
340example because <CODE
341CLASS="FUNCTION"
342>read()</CODE
343> was interrupted by a
344signal. On error, -1 is returned, and the <CODE
345CLASS="VARNAME"
346>errno</CODE
347>
348variable is set appropriately. In this case the next read will start
349at the beginning of a new frame. Possible error codes are:</P
350><P
351></P
352><DIV
353CLASS="VARIABLELIST"
354><DL
355><DT
356><SPAN
357CLASS="ERRORCODE"
358>EAGAIN</SPAN
359></DT
360><DD
361><P
362>Non-blocking I/O has been selected using
363O_NONBLOCK and no data was immediately available for reading.</P
364></DD
365><DT
366><SPAN
367CLASS="ERRORCODE"
368>EBADF</SPAN
369></DT
370><DD
371><P
372><CODE
373CLASS="PARAMETER"
374>fd</CODE
375> is not a valid file
376descriptor or is not open for reading, or the process already has the
377maximum number of files open.</P
378></DD
379><DT
380><SPAN
381CLASS="ERRORCODE"
382>EBUSY</SPAN
383></DT
384><DD
385><P
386>The driver does not support multiple read streams and the
387device is already in use.</P
388></DD
389><DT
390><SPAN
391CLASS="ERRORCODE"
392>EFAULT</SPAN
393></DT
394><DD
395><P
396><CODE
397CLASS="PARAMETER"
398>buf</CODE
399> references an inaccessible
400memory area.</P
401></DD
402><DT
403><SPAN
404CLASS="ERRORCODE"
405>EINTR</SPAN
406></DT
407><DD
408><P
409>The call was interrupted by a signal before any
410data was read.</P
411></DD
412><DT
413><SPAN
414CLASS="ERRORCODE"
415>EIO</SPAN
416></DT
417><DD
418><P
419>I/O error. This indicates some hardware problem or a
420failure to communicate with a remote device (USB camera etc.).</P
421></DD
422><DT
423><SPAN
424CLASS="ERRORCODE"
425>EINVAL</SPAN
426></DT
427><DD
428><P
429>The <CODE
430CLASS="FUNCTION"
431>read()</CODE
432> function is not
433supported by this driver, not on this device, or generally not on this
434type of device.</P
435></DD
436></DL
437></DIV
438></DIV
439><DIV
440CLASS="NAVFOOTER"
441><HR
442ALIGN="LEFT"
443WIDTH="100%"><TABLE
444SUMMARY="Footer navigation table"
445WIDTH="100%"
446BORDER="0"
447CELLPADDING="0"
448CELLSPACING="0"
449><TR
450><TD
451WIDTH="33%"
452ALIGN="left"
453VALIGN="top"
454><A
455HREF="r14169.htm"
456ACCESSKEY="P"
457>Prev</A
458></TD
459><TD
460WIDTH="34%"
461ALIGN="center"
462VALIGN="top"
463><A
464HREF="book1.htm"
465ACCESSKEY="H"
466>Home</A
467></TD
468><TD
469WIDTH="33%"
470ALIGN="right"
471VALIGN="top"
472><A
473HREF="r14390.htm"
474ACCESSKEY="N"
475>Next</A
476></TD
477></TR
478><TR
479><TD
480WIDTH="33%"
481ALIGN="left"
482VALIGN="top"
483>V4L2 poll()</TD
484><TD
485WIDTH="34%"
486ALIGN="center"
487VALIGN="top"
488><A
489HREF="r7624.htm"
490ACCESSKEY="U"
491>Up</A
492></TD
493><TD
494WIDTH="33%"
495ALIGN="right"
496VALIGN="top"
497>V4L2 select()</TD
498></TR
499></TABLE
500></DIV
501></BODY
502></HTML
503>
504