1.. Permission is granted to copy, distribute and/or modify this
2.. document under the terms of the GNU Free Documentation License,
3.. Version 1.1 or any later version published by the Free Software
4.. Foundation, with no Invariant Sections, no Front-Cover Texts
5.. and no Back-Cover Texts. A copy of the license is included at
6.. Documentation/userspace-api/media/fdl-appendix.rst.
7..
8.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
9
10.. _VIDIOC_QUERYBUF:
11
12*********************
13ioctl VIDIOC_QUERYBUF
14*********************
15
16Name
17====
18
19VIDIOC_QUERYBUF - Query the status of a buffer
20
21
22Synopsis
23========
24
25.. c:function:: int ioctl( int fd, VIDIOC_QUERYBUF, struct v4l2_buffer *argp )
26    :name: VIDIOC_QUERYBUF
27
28
29Arguments
30=========
31
32``fd``
33    File descriptor returned by :ref:`open() <func-open>`.
34
35``argp``
36    Pointer to struct :c:type:`v4l2_buffer`.
37
38
39Description
40===========
41
42This ioctl is part of the :ref:`streaming <mmap>` I/O method. It can
43be used to query the status of a buffer at any time after buffers have
44been allocated with the :ref:`VIDIOC_REQBUFS` ioctl.
45
46Applications set the ``type`` field of a struct
47:c:type:`v4l2_buffer` to the same buffer type as was
48previously used with struct :c:type:`v4l2_format` ``type``
49and struct :c:type:`v4l2_requestbuffers` ``type``,
50and the ``index`` field. Valid index numbers range from zero to the
51number of buffers allocated with
52:ref:`VIDIOC_REQBUFS` (struct
53:c:type:`v4l2_requestbuffers` ``count``) minus
54one. The ``reserved`` and ``reserved2`` fields must be set to 0. When
55using the :ref:`multi-planar API <planar-apis>`, the ``m.planes``
56field must contain a userspace pointer to an array of struct
57:c:type:`v4l2_plane` and the ``length`` field has to be set
58to the number of elements in that array. After calling
59:ref:`VIDIOC_QUERYBUF` with a pointer to this structure drivers return an
60error code or fill the rest of the structure.
61
62In the ``flags`` field the ``V4L2_BUF_FLAG_MAPPED``,
63``V4L2_BUF_FLAG_PREPARED``, ``V4L2_BUF_FLAG_QUEUED`` and
64``V4L2_BUF_FLAG_DONE`` flags will be valid. The ``memory`` field will be
65set to the current I/O method. For the single-planar API, the
66``m.offset`` contains the offset of the buffer from the start of the
67device memory, the ``length`` field its size. For the multi-planar API,
68fields ``m.mem_offset`` and ``length`` in the ``m.planes`` array
69elements will be used instead and the ``length`` field of struct
70:c:type:`v4l2_buffer` is set to the number of filled-in
71array elements. The driver may or may not set the remaining fields and
72flags, they are meaningless in this context.
73
74The struct :c:type:`v4l2_buffer` structure is specified in
75:ref:`buffer`.
76
77
78Return Value
79============
80
81On success 0 is returned, on error -1 and the ``errno`` variable is set
82appropriately. The generic error codes are described at the
83:ref:`Generic Error Codes <gen-errors>` chapter.
84
85EINVAL
86    The buffer ``type`` is not supported, or the ``index`` is out of
87    bounds.
88