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 mmap()</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_STREAMON, VIDIOC_STREAMOFF" 17HREF="r13817.htm"><LINK 18REL="NEXT" 19TITLE="V4L2 munmap()" 20HREF="r14037.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="r13817.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="r14037.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-MMAP" 74></A 75>V4L2 mmap()</H1 76><DIV 77CLASS="REFNAMEDIV" 78><A 79NAME="AEN13893" 80></A 81><H2 82>Name</H2 83>v4l2-mmap -- Map device memory into application address space</DIV 84><DIV 85CLASS="REFSYNOPSISDIV" 86><A 87NAME="AEN13896" 88></A 89><H2 90>Synopsis</H2 91><DIV 92CLASS="FUNCSYNOPSIS" 93><P 94></P 95><A 96NAME="AEN13897" 97></A 98><PRE 99CLASS="FUNCSYNOPSISINFO" 100>#include <unistd.h> 101#include <sys/mman.h></PRE 102><P 103><CODE 104><CODE 105CLASS="FUNCDEF" 106>void *mmap</CODE 107>(void *start, size_t length, int prot, int flags, int fd, off_t offset);</CODE 108></P 109><P 110></P 111></DIV 112></DIV 113><DIV 114CLASS="REFSECT1" 115><A 116NAME="AEN13914" 117></A 118><H2 119>Arguments</H2 120><P 121></P 122><DIV 123CLASS="VARIABLELIST" 124><DL 125><DT 126><CODE 127CLASS="PARAMETER" 128>start</CODE 129></DT 130><DD 131><P 132>Map the buffer to this address in the 133application's address space. When the <CODE 134CLASS="CONSTANT" 135>MAP_FIXED</CODE 136> 137flag is specified, <CODE 138CLASS="PARAMETER" 139>start</CODE 140> must be a multiple of the 141pagesize and mmap will fail when the specified address 142cannot be used. Use of this option is discouraged; applications should 143just specify a <CODE 144CLASS="CONSTANT" 145>NULL</CODE 146> pointer here.</P 147></DD 148><DT 149><CODE 150CLASS="PARAMETER" 151>length</CODE 152></DT 153><DD 154><P 155>Length of the memory area to map. This must be the 156same value as returned by the driver in the struct <A 157HREF="x5953.htm#V4L2-BUFFER" 158>v4l2_buffer</A 159> 160<CODE 161CLASS="STRUCTFIELD" 162>length</CODE 163> field.</P 164></DD 165><DT 166><CODE 167CLASS="PARAMETER" 168>prot</CODE 169></DT 170><DD 171><P 172>The <CODE 173CLASS="PARAMETER" 174>prot</CODE 175> argument describes the 176desired memory protection. Regardless of the device type and the 177direction of data exchange it should be set to 178<CODE 179CLASS="CONSTANT" 180>PROT_READ</CODE 181> | <CODE 182CLASS="CONSTANT" 183>PROT_WRITE</CODE 184>, 185permitting read and write access to image buffers. Drivers should 186support at least this combination of flags. Note the Linux 187<TT 188CLASS="FILENAME" 189>video-buf</TT 190> kernel module, which is used by the 191bttv, saa7134, saa7146, cx88 and vivi driver supports only 192<CODE 193CLASS="CONSTANT" 194>PROT_READ</CODE 195> | <CODE 196CLASS="CONSTANT" 197>PROT_WRITE</CODE 198>. When 199the driver does not support the desired protection the 200<CODE 201CLASS="FUNCTION" 202>mmap()</CODE 203> function fails.</P 204><P 205>Note device memory accesses (e. g. the memory on a 206graphics card with video capturing hardware) may incur a performance 207penalty compared to main memory accesses, or reads may be 208significantly slower than writes or vice versa. Other I/O methods may 209be more efficient in this case.</P 210></DD 211><DT 212><CODE 213CLASS="PARAMETER" 214>flags</CODE 215></DT 216><DD 217><P 218>The <CODE 219CLASS="PARAMETER" 220>flags</CODE 221> parameter 222specifies the type of the mapped object, mapping options and whether 223modifications made to the mapped copy of the page are private to the 224process or are to be shared with other references.</P 225><P 226><CODE 227CLASS="CONSTANT" 228>MAP_FIXED</CODE 229> requests that the 230driver selects no other address than the one specified. If the 231specified address cannot be used, <CODE 232CLASS="FUNCTION" 233>mmap()</CODE 234> will fail. If 235<CODE 236CLASS="CONSTANT" 237>MAP_FIXED</CODE 238> is specified, 239<CODE 240CLASS="PARAMETER" 241>start</CODE 242> must be a multiple of the pagesize. Use 243of this option is discouraged.</P 244><P 245>One of the <CODE 246CLASS="CONSTANT" 247>MAP_SHARED</CODE 248> or 249<CODE 250CLASS="CONSTANT" 251>MAP_PRIVATE</CODE 252> flags must be set. 253<CODE 254CLASS="CONSTANT" 255>MAP_SHARED</CODE 256> allows applications to share the 257mapped memory with other (e. g. child-) processes. Note the Linux 258<TT 259CLASS="FILENAME" 260>video-buf</TT 261> module which is used by the bttv, 262saa7134, saa7146, cx88 and vivi driver supports only 263<CODE 264CLASS="CONSTANT" 265>MAP_SHARED</CODE 266>. <CODE 267CLASS="CONSTANT" 268>MAP_PRIVATE</CODE 269> 270requests copy-on-write semantics. V4L2 applications should not set the 271<CODE 272CLASS="CONSTANT" 273>MAP_PRIVATE</CODE 274>, <CODE 275CLASS="CONSTANT" 276>MAP_DENYWRITE</CODE 277>, 278<CODE 279CLASS="CONSTANT" 280>MAP_EXECUTABLE</CODE 281> or <CODE 282CLASS="CONSTANT" 283>MAP_ANON</CODE 284> 285flag.</P 286></DD 287><DT 288><CODE 289CLASS="PARAMETER" 290>fd</CODE 291></DT 292><DD 293><P 294>File descriptor returned by <A 295HREF="r14090.htm" 296><CODE 297CLASS="FUNCTION" 298>open()</CODE 299></A 300>.</P 301></DD 302><DT 303><CODE 304CLASS="PARAMETER" 305>offset</CODE 306></DT 307><DD 308><P 309>Offset of the buffer in device memory. This must be the 310same value as returned by the driver in the struct <A 311HREF="x5953.htm#V4L2-BUFFER" 312>v4l2_buffer</A 313> 314<CODE 315CLASS="STRUCTFIELD" 316>m</CODE 317> union <CODE 318CLASS="STRUCTFIELD" 319>offset</CODE 320> field.</P 321></DD 322></DL 323></DIV 324></DIV 325><DIV 326CLASS="REFSECT1" 327><A 328NAME="AEN13982" 329></A 330><H2 331>Description</H2 332><P 333>The <CODE 334CLASS="FUNCTION" 335>mmap()</CODE 336> function asks to map 337<CODE 338CLASS="PARAMETER" 339>length</CODE 340> bytes starting at 341<CODE 342CLASS="PARAMETER" 343>offset</CODE 344> in the memory of the device specified by 345<CODE 346CLASS="PARAMETER" 347>fd</CODE 348> into the application address space, 349preferably at address <CODE 350CLASS="PARAMETER" 351>start</CODE 352>. This latter 353address is a hint only, and is usually specified as 0.</P 354><P 355>Suitable length and offset parameters are queried with the 356<A 357HREF="r13022.htm" 358><CODE 359CLASS="CONSTANT" 360>VIDIOC_QUERYBUF</CODE 361></A 362> ioctl. Buffers must be allocated with the 363<A 364HREF="r13696.htm" 365><CODE 366CLASS="CONSTANT" 367>VIDIOC_REQBUFS</CODE 368></A 369> ioctl before they can be queried.</P 370><P 371>To unmap buffers the <A 372HREF="r14037.htm" 373><CODE 374CLASS="FUNCTION" 375>munmap()</CODE 376></A 377> function is used.</P 378></DIV 379><DIV 380CLASS="REFSECT1" 381><A 382NAME="AEN13998" 383></A 384><H2 385>Return Value</H2 386><P 387>On success <CODE 388CLASS="FUNCTION" 389>mmap()</CODE 390> returns a pointer to 391the mapped buffer. On error <CODE 392CLASS="CONSTANT" 393>MAP_FAILED</CODE 394> (-1) is 395returned, and the <CODE 396CLASS="VARNAME" 397>errno</CODE 398> variable is set 399appropriately. Possible error codes are:</P 400><P 401></P 402><DIV 403CLASS="VARIABLELIST" 404><DL 405><DT 406><SPAN 407CLASS="ERRORCODE" 408>EBADF</SPAN 409></DT 410><DD 411><P 412><CODE 413CLASS="PARAMETER" 414>fd</CODE 415> is not a valid file 416descriptor.</P 417></DD 418><DT 419><SPAN 420CLASS="ERRORCODE" 421>EACCES</SPAN 422></DT 423><DD 424><P 425><CODE 426CLASS="PARAMETER" 427>fd</CODE 428> is 429not open for reading and writing.</P 430></DD 431><DT 432><SPAN 433CLASS="ERRORCODE" 434>EINVAL</SPAN 435></DT 436><DD 437><P 438>The <CODE 439CLASS="PARAMETER" 440>start</CODE 441> or 442<CODE 443CLASS="PARAMETER" 444>length</CODE 445> or <CODE 446CLASS="PARAMETER" 447>offset</CODE 448> are not 449suitable. (E. g. they are too large, or not aligned on a 450<CODE 451CLASS="CONSTANT" 452>PAGESIZE</CODE 453> boundary.)</P 454><P 455>The <CODE 456CLASS="PARAMETER" 457>flags</CODE 458> or 459<CODE 460CLASS="PARAMETER" 461>prot</CODE 462> value is not supported.</P 463><P 464>No buffers have been allocated with the 465<A 466HREF="r13696.htm" 467><CODE 468CLASS="CONSTANT" 469>VIDIOC_REQBUFS</CODE 470></A 471> ioctl.</P 472></DD 473><DT 474><SPAN 475CLASS="ERRORCODE" 476>ENOMEM</SPAN 477></DT 478><DD 479><P 480>Not enough physical or virtual memory was available to 481complete the request.</P 482></DD 483></DL 484></DIV 485></DIV 486><DIV 487CLASS="NAVFOOTER" 488><HR 489ALIGN="LEFT" 490WIDTH="100%"><TABLE 491SUMMARY="Footer navigation table" 492WIDTH="100%" 493BORDER="0" 494CELLPADDING="0" 495CELLSPACING="0" 496><TR 497><TD 498WIDTH="33%" 499ALIGN="left" 500VALIGN="top" 501><A 502HREF="r13817.htm" 503ACCESSKEY="P" 504>Prev</A 505></TD 506><TD 507WIDTH="34%" 508ALIGN="center" 509VALIGN="top" 510><A 511HREF="book1.htm" 512ACCESSKEY="H" 513>Home</A 514></TD 515><TD 516WIDTH="33%" 517ALIGN="right" 518VALIGN="top" 519><A 520HREF="r14037.htm" 521ACCESSKEY="N" 522>Next</A 523></TD 524></TR 525><TR 526><TD 527WIDTH="33%" 528ALIGN="left" 529VALIGN="top" 530>ioctl VIDIOC_STREAMON, VIDIOC_STREAMOFF</TD 531><TD 532WIDTH="34%" 533ALIGN="center" 534VALIGN="top" 535><A 536HREF="r7624.htm" 537ACCESSKEY="U" 538>Up</A 539></TD 540><TD 541WIDTH="33%" 542ALIGN="right" 543VALIGN="top" 544>V4L2 munmap()</TD 545></TR 546></TABLE 547></DIV 548></BODY 549></HTML 550> 551