1 <refentry id=
"vidioc-querybuf">
3 <refentrytitle>ioctl VIDIOC_QUERYBUF
</refentrytitle>
8 <refname>VIDIOC_QUERYBUF
</refname>
9 <refpurpose>Query the status of a buffer
</refpurpose>
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>
24 <title>Arguments
</title>
28 <term><parameter>fd
</parameter></term>
34 <term><parameter>request
</parameter></term>
36 <para>VIDIOC_QUERYBUF
</para>
40 <term><parameter>argp
</parameter></term>
49 <title>Description
</title>
51 <para>This ioctl is part of the
<link linkend=
"mmap">memory
52 mapping
</link> I/O method. It can be used to query the status of a
53 buffer at any time after buffers have been allocated with the
54 &VIDIOC-REQBUFS; ioctl.
</para>
56 <para>Applications set the
<structfield>type
</structfield> field
57 of a &v4l2-buffer; to the same buffer type as was previously used with
58 &v4l2-format;
<structfield>type
</structfield> and &v4l2-requestbuffers;
59 <structfield>type
</structfield>, and the
<structfield>index
</structfield>
60 field. Valid index numbers range from zero
61 to the number of buffers allocated with &VIDIOC-REQBUFS;
62 (&v4l2-requestbuffers;
<structfield>count
</structfield>) minus one.
63 The
<structfield>reserved
</structfield> field should to set to
0.
64 When using the
<link linkend=
"planar-apis">multi-planar API
</link>, the
65 <structfield>m.planes
</structfield> field must contain a userspace pointer to an
66 array of &v4l2-plane; and the
<structfield>length
</structfield> field has
67 to be set to the number of elements in that array.
68 After calling
<constant>VIDIOC_QUERYBUF
</constant> with a pointer to
69 this structure drivers return an error code or fill the rest of
72 <para>In the
<structfield>flags
</structfield> field the
73 <constant>V4L2_BUF_FLAG_MAPPED
</constant>,
74 <constant>V4L2_BUF_FLAG_QUEUED
</constant> and
75 <constant>V4L2_BUF_FLAG_DONE
</constant> flags will be valid. The
76 <structfield>memory
</structfield> field will be set to the current
77 I/O method. For the single-planar API, the
<structfield>m.offset
</structfield>
78 contains the offset of the buffer from the start of the device memory,
79 the
<structfield>length
</structfield> field its size. For the multi-planar API,
80 fields
<structfield>m.mem_offset
</structfield> and
81 <structfield>length
</structfield> in the
<structfield>m.planes
</structfield>
82 array elements will be used instead. The driver may or may not set the remaining
83 fields and flags, they are meaningless in this context.
</para>
85 <para>The
<structname>v4l2_buffer
</structname> structure is
86 specified in
<xref linkend=
"buffer" />.
</para>
94 <term><errorcode>EINVAL
</errorcode></term>
96 <para>The buffer
<structfield>type
</structfield> is not
97 supported, or the
<structfield>index
</structfield> is out of bounds.
</para>