1 .. SPDX-License-Identifier: GFDL-1.1-no-invari !! 1 .. Permission is granted to copy, distribute and/or modify this
2 .. c:namespace:: V4L !! 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
3 9
4 .. _VIDIOC_QUERYBUF: 10 .. _VIDIOC_QUERYBUF:
5 11
6 ********************* 12 *********************
7 ioctl VIDIOC_QUERYBUF 13 ioctl VIDIOC_QUERYBUF
8 ********************* 14 *********************
9 15
10 Name 16 Name
11 ==== 17 ====
12 18
13 VIDIOC_QUERYBUF - Query the status of a buffer 19 VIDIOC_QUERYBUF - Query the status of a buffer
14 20
>> 21
15 Synopsis 22 Synopsis
16 ======== 23 ========
17 24
18 .. c:macro:: VIDIOC_QUERYBUF !! 25 .. c:function:: int ioctl( int fd, VIDIOC_QUERYBUF, struct v4l2_buffer *argp )
>> 26 :name: VIDIOC_QUERYBUF
19 27
20 ``int ioctl(int fd, VIDIOC_QUERYBUF, struct v4 <<
21 28
22 Arguments 29 Arguments
23 ========= 30 =========
24 31
25 ``fd`` 32 ``fd``
26 File descriptor returned by :c:func:`open( !! 33 File descriptor returned by :ref:`open() <func-open>`.
27 34
28 ``argp`` 35 ``argp``
29 Pointer to struct :c:type:`v4l2_buffer`. 36 Pointer to struct :c:type:`v4l2_buffer`.
30 37
>> 38
31 Description 39 Description
32 =========== 40 ===========
33 41
34 This ioctl is part of the :ref:`streaming <mma 42 This ioctl is part of the :ref:`streaming <mmap>` I/O method. It can
35 be used to query the status of a buffer at any 43 be used to query the status of a buffer at any time after buffers have
36 been allocated with the :ref:`VIDIOC_REQBUFS` 44 been allocated with the :ref:`VIDIOC_REQBUFS` ioctl.
37 45
38 Applications set the ``type`` field of a struc 46 Applications set the ``type`` field of a struct
39 :c:type:`v4l2_buffer` to the same buffer type 47 :c:type:`v4l2_buffer` to the same buffer type as was
40 previously used with struct :c:type:`v4l2_form 48 previously used with struct :c:type:`v4l2_format` ``type``
41 and struct :c:type:`v4l2_requestbuffers` ``typ 49 and struct :c:type:`v4l2_requestbuffers` ``type``,
42 and the ``index`` field. Valid index numbers r 50 and the ``index`` field. Valid index numbers range from zero to the
43 number of buffers allocated with 51 number of buffers allocated with
44 :ref:`VIDIOC_REQBUFS` (struct 52 :ref:`VIDIOC_REQBUFS` (struct
45 :c:type:`v4l2_requestbuffers` ``count``) minus 53 :c:type:`v4l2_requestbuffers` ``count``) minus
46 one. The ``reserved`` and ``reserved2`` fields 54 one. The ``reserved`` and ``reserved2`` fields must be set to 0. When
47 using the :ref:`multi-planar API <planar-apis> 55 using the :ref:`multi-planar API <planar-apis>`, the ``m.planes``
48 field must contain a userspace pointer to an a 56 field must contain a userspace pointer to an array of struct
49 :c:type:`v4l2_plane` and the ``length`` field 57 :c:type:`v4l2_plane` and the ``length`` field has to be set
50 to the number of elements in that array. After 58 to the number of elements in that array. After calling
51 :ref:`VIDIOC_QUERYBUF` with a pointer to this 59 :ref:`VIDIOC_QUERYBUF` with a pointer to this structure drivers return an
52 error code or fill the rest of the structure. 60 error code or fill the rest of the structure.
53 61
54 In the ``flags`` field the ``V4L2_BUF_FLAG_MAP 62 In the ``flags`` field the ``V4L2_BUF_FLAG_MAPPED``,
55 ``V4L2_BUF_FLAG_PREPARED``, ``V4L2_BUF_FLAG_QU 63 ``V4L2_BUF_FLAG_PREPARED``, ``V4L2_BUF_FLAG_QUEUED`` and
56 ``V4L2_BUF_FLAG_DONE`` flags will be valid. Th 64 ``V4L2_BUF_FLAG_DONE`` flags will be valid. The ``memory`` field will be
57 set to the current I/O method. For the single- 65 set to the current I/O method. For the single-planar API, the
58 ``m.offset`` contains the offset of the buffer 66 ``m.offset`` contains the offset of the buffer from the start of the
59 device memory, the ``length`` field its size. 67 device memory, the ``length`` field its size. For the multi-planar API,
60 fields ``m.mem_offset`` and ``length`` in the 68 fields ``m.mem_offset`` and ``length`` in the ``m.planes`` array
61 elements will be used instead and the ``length 69 elements will be used instead and the ``length`` field of struct
62 :c:type:`v4l2_buffer` is set to the number of 70 :c:type:`v4l2_buffer` is set to the number of filled-in
63 array elements. The driver may or may not set 71 array elements. The driver may or may not set the remaining fields and
64 flags, they are meaningless in this context. 72 flags, they are meaningless in this context.
65 73
66 The struct :c:type:`v4l2_buffer` structure is 74 The struct :c:type:`v4l2_buffer` structure is specified in
67 :ref:`buffer`. 75 :ref:`buffer`.
>> 76
68 77
69 Return Value 78 Return Value
70 ============ 79 ============
71 80
72 On success 0 is returned, on error -1 and the 81 On success 0 is returned, on error -1 and the ``errno`` variable is set
73 appropriately. The generic error codes are des 82 appropriately. The generic error codes are described at the
74 :ref:`Generic Error Codes <gen-errors>` chapte 83 :ref:`Generic Error Codes <gen-errors>` chapter.
75 84
76 EINVAL 85 EINVAL
77 The buffer ``type`` is not supported, or t 86 The buffer ``type`` is not supported, or the ``index`` is out of
78 bounds. 87 bounds.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.