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 -- 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 <unistd.h></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