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&nbsp;--&nbsp;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 &lt;unistd.h&gt;
101#include &lt;sys/mman.h&gt;</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&nbsp;<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.&nbsp;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.&nbsp;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&nbsp;<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.&nbsp;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