1<refentry id="vidioc-expbuf">
2
3  <refmeta>
4    <refentrytitle>ioctl VIDIOC_EXPBUF</refentrytitle>
5    &manvol;
6  </refmeta>
7
8  <refnamediv>
9    <refname>VIDIOC_EXPBUF</refname>
10    <refpurpose>Export a buffer as a DMABUF file descriptor.</refpurpose>
11  </refnamediv>
12
13  <refsynopsisdiv>
14    <funcsynopsis>
15      <funcprototype>
16	<funcdef>int <function>ioctl</function></funcdef>
17	<paramdef>int <parameter>fd</parameter></paramdef>
18	<paramdef>int <parameter>request</parameter></paramdef>
19	<paramdef>struct v4l2_exportbuffer *<parameter>argp</parameter></paramdef>
20      </funcprototype>
21    </funcsynopsis>
22  </refsynopsisdiv>
23
24  <refsect1>
25    <title>Arguments</title>
26
27    <variablelist>
28      <varlistentry>
29	<term><parameter>fd</parameter></term>
30	<listitem>
31	  <para>&fd;</para>
32	</listitem>
33      </varlistentry>
34      <varlistentry>
35	<term><parameter>request</parameter></term>
36	<listitem>
37	  <para>VIDIOC_EXPBUF</para>
38	</listitem>
39      </varlistentry>
40      <varlistentry>
41	<term><parameter>argp</parameter></term>
42	<listitem>
43	  <para></para>
44	</listitem>
45      </varlistentry>
46    </variablelist>
47  </refsect1>
48
49  <refsect1>
50    <title>Description</title>
51
52    <note>
53      <title>Experimental</title>
54      <para>This is an <link linkend="experimental"> experimental </link>
55      interface and may change in the future.</para>
56    </note>
57
58<para>This ioctl is an extension to the <link linkend="mmap">memory
59mapping</link> I/O method, therefore it is available only for
60<constant>V4L2_MEMORY_MMAP</constant> buffers.  It can be used to export a
61buffer as a DMABUF file at any time after buffers have been allocated with the
62&VIDIOC-REQBUFS; ioctl.</para>
63
64<para> To export a buffer, applications fill &v4l2-exportbuffer;.  The
65<structfield> type </structfield> field is set to the same buffer type as was
66previously used with  &v4l2-requestbuffers;<structfield> type </structfield>.
67Applications must also set the <structfield> index </structfield> field. Valid
68index numbers range from zero to the number of buffers allocated with
69&VIDIOC-REQBUFS; (&v4l2-requestbuffers;<structfield> count </structfield>)
70minus one.  For the multi-planar API, applications set the <structfield> plane
71</structfield> field to the index of the plane to be exported. Valid planes
72range from zero to the maximal number of valid planes for the currently active
73format. For the single-planar API, applications must set <structfield> plane
74</structfield> to zero.  Additional flags may be posted in the <structfield>
75flags </structfield> field.  Refer to a manual for open() for details.
76Currently only O_CLOEXEC, O_RDONLY, O_WRONLY, and O_RDWR are supported.  All
77other fields must be set to zero.
78In the case of multi-planar API, every plane is exported separately using
79multiple <constant> VIDIOC_EXPBUF </constant> calls. </para>
80
81<para> After calling <constant>VIDIOC_EXPBUF</constant> the <structfield> fd
82</structfield> field will be set by a driver.  This is a DMABUF file
83descriptor. The application may pass it to other DMABUF-aware devices. Refer to
84<link linkend="dmabuf">DMABUF importing</link> for details about importing
85DMABUF files into V4L2 nodes. It is recommended to close a DMABUF file when it
86is no longer used to allow the associated memory to be reclaimed. </para>
87  </refsect1>
88
89  <refsect1>
90    <title>Examples</title>
91
92    <example>
93      <title>Exporting a buffer.</title>
94      <programlisting>
95int buffer_export(int v4lfd, &v4l2-buf-type; bt, int index, int *dmafd)
96{
97	&v4l2-exportbuffer; expbuf;
98
99	memset(&amp;expbuf, 0, sizeof(expbuf));
100	expbuf.type = bt;
101	expbuf.index = index;
102	if (ioctl(v4lfd, &VIDIOC-EXPBUF;, &amp;expbuf) == -1) {
103		perror("VIDIOC_EXPBUF");
104		return -1;
105	}
106
107	*dmafd = expbuf.fd;
108
109	return 0;
110}
111      </programlisting>
112    </example>
113
114    <example>
115      <title>Exporting a buffer using the multi-planar API.</title>
116      <programlisting>
117int buffer_export_mp(int v4lfd, &v4l2-buf-type; bt, int index,
118	int dmafd[], int n_planes)
119{
120	int i;
121
122	for (i = 0; i &lt; n_planes; ++i) {
123		&v4l2-exportbuffer; expbuf;
124
125		memset(&amp;expbuf, 0, sizeof(expbuf));
126		expbuf.type = bt;
127		expbuf.index = index;
128		expbuf.plane = i;
129		if (ioctl(v4lfd, &VIDIOC-EXPBUF;, &amp;expbuf) == -1) {
130			perror("VIDIOC_EXPBUF");
131			while (i)
132				close(dmafd[--i]);
133			return -1;
134		}
135		dmafd[i] = expbuf.fd;
136	}
137
138	return 0;
139}
140      </programlisting>
141    </example>
142
143    <table pgwide="1" frame="none" id="v4l2-exportbuffer">
144      <title>struct <structname>v4l2_exportbuffer</structname></title>
145      <tgroup cols="3">
146	&cs-str;
147	<tbody valign="top">
148	  <row>
149	    <entry>__u32</entry>
150	    <entry><structfield>type</structfield></entry>
151	    <entry>Type of the buffer, same as &v4l2-format;
152<structfield>type</structfield> or &v4l2-requestbuffers;
153<structfield>type</structfield>, set by the application. See <xref
154linkend="v4l2-buf-type" /></entry>
155	  </row>
156	  <row>
157	    <entry>__u32</entry>
158	    <entry><structfield>index</structfield></entry>
159	    <entry>Number of the buffer, set by the application. This field is
160only used for <link linkend="mmap">memory mapping</link> I/O and can range from
161zero to the number of buffers allocated with the &VIDIOC-REQBUFS; and/or
162&VIDIOC-CREATE-BUFS; ioctls. </entry>
163	  </row>
164	  <row>
165	    <entry>__u32</entry>
166	    <entry><structfield>plane</structfield></entry>
167	    <entry>Index of the plane to be exported when using the
168multi-planar API. Otherwise this value must be set to zero. </entry>
169	  </row>
170	  <row>
171	    <entry>__u32</entry>
172	    <entry><structfield>flags</structfield></entry>
173	    <entry>Flags for the newly created file, currently only <constant>
174O_CLOEXEC </constant>, <constant>O_RDONLY</constant>, <constant>O_WRONLY
175</constant>, and <constant>O_RDWR</constant> are supported, refer to the manual
176of open() for more details.</entry>
177	  </row>
178	  <row>
179	    <entry>__s32</entry>
180	    <entry><structfield>fd</structfield></entry>
181	    <entry>The DMABUF file descriptor associated with a buffer. Set by
182		the driver.</entry>
183	  </row>
184	  <row>
185	    <entry>__u32</entry>
186	    <entry><structfield>reserved[11]</structfield></entry>
187	    <entry>Reserved field for future use. Must be set to zero.</entry>
188	  </row>
189	</tbody>
190      </tgroup>
191    </table>
192
193  </refsect1>
194
195  <refsect1>
196    &return-value;
197    <variablelist>
198      <varlistentry>
199	<term><errorcode>EINVAL</errorcode></term>
200	<listitem>
201	  <para>A queue is not in MMAP mode or DMABUF exporting is not
202supported or <structfield> flags </structfield> or <structfield> type
203</structfield> or <structfield> index </structfield> or <structfield> plane
204</structfield> fields are invalid.</para>
205	</listitem>
206      </varlistentry>
207    </variablelist>
208  </refsect1>
209
210</refentry>
211