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