1<refentry id="vidioc-prepare-buf">
2  <refmeta>
3    <refentrytitle>ioctl VIDIOC_PREPARE_BUF</refentrytitle>
4    &manvol;
5  </refmeta>
6
7  <refnamediv>
8    <refname>VIDIOC_PREPARE_BUF</refname>
9    <refpurpose>Prepare a buffer for I/O</refpurpose>
10  </refnamediv>
11
12  <refsynopsisdiv>
13    <funcsynopsis>
14      <funcprototype>
15	<funcdef>int <function>ioctl</function></funcdef>
16	<paramdef>int <parameter>fd</parameter></paramdef>
17	<paramdef>int <parameter>request</parameter></paramdef>
18	<paramdef>struct v4l2_buffer *<parameter>argp</parameter></paramdef>
19      </funcprototype>
20    </funcsynopsis>
21  </refsynopsisdiv>
22
23  <refsect1>
24    <title>Arguments</title>
25
26    <variablelist>
27      <varlistentry>
28	<term><parameter>fd</parameter></term>
29	<listitem>
30	  <para>&fd;</para>
31	</listitem>
32      </varlistentry>
33      <varlistentry>
34	<term><parameter>request</parameter></term>
35	<listitem>
36	  <para>VIDIOC_PREPARE_BUF</para>
37	</listitem>
38      </varlistentry>
39      <varlistentry>
40	<term><parameter>argp</parameter></term>
41	<listitem>
42	  <para></para>
43	</listitem>
44      </varlistentry>
45    </variablelist>
46  </refsect1>
47
48  <refsect1>
49    <title>Description</title>
50
51    <para>Applications can optionally call the
52<constant>VIDIOC_PREPARE_BUF</constant> ioctl to pass ownership of the buffer
53to the driver before actually enqueuing it, using the
54<constant>VIDIOC_QBUF</constant> ioctl, and to prepare it for future I/O.
55Such preparations may include cache invalidation or cleaning. Performing them
56in advance saves time during the actual I/O. In case such cache operations are
57not required, the application can use one of
58<constant>V4L2_BUF_FLAG_NO_CACHE_INVALIDATE</constant> and
59<constant>V4L2_BUF_FLAG_NO_CACHE_CLEAN</constant> flags to skip the respective
60step.</para>
61
62    <para>The <structname>v4l2_buffer</structname> structure is
63specified in <xref linkend="buffer" />.</para>
64  </refsect1>
65
66  <refsect1>
67    &return-value;
68
69    <variablelist>
70      <varlistentry>
71	<term><errorcode>EBUSY</errorcode></term>
72	<listitem>
73	  <para>File I/O is in progress.</para>
74	</listitem>
75      </varlistentry>
76      <varlistentry>
77	<term><errorcode>EINVAL</errorcode></term>
78	<listitem>
79	  <para>The buffer <structfield>type</structfield> is not
80supported, or the <structfield>index</structfield> is out of bounds,
81or no buffers have been allocated yet, or the
82<structfield>userptr</structfield> or
83<structfield>length</structfield> are invalid.</para>
84	</listitem>
85      </varlistentry>
86    </variablelist>
87  </refsect1>
88</refentry>
89