1 .. SPDX-License-Identifier: GFDL-1.1-no-invari
2 .. c:namespace:: V4L
3
4 .. _VIDIOC_QUERYCTRL:
5
6 **********************************************
7 ioctls VIDIOC_QUERYCTRL, VIDIOC_QUERY_EXT_CTRL
8 **********************************************
9
10 Name
11 ====
12
13 VIDIOC_QUERYCTRL - VIDIOC_QUERY_EXT_CTRL - VID
14
15 Synopsis
16 ========
17
18 ``int ioctl(int fd, int VIDIOC_QUERYCTRL, stru
19
20 .. c:macro:: VIDIOC_QUERY_EXT_CTRL
21
22 ``int ioctl(int fd, VIDIOC_QUERY_EXT_CTRL, str
23
24 .. c:macro:: VIDIOC_QUERYMENU
25
26 ``int ioctl(int fd, VIDIOC_QUERYMENU, struct v
27
28 Arguments
29 =========
30
31 ``fd``
32 File descriptor returned by :c:func:`open(
33
34 ``argp``
35 Pointer to struct :c:type:`v4l2_queryctrl`
36 or :c:type:`v4l2_querymenu` (depending on
37
38 Description
39 ===========
40
41 To query the attributes of a control applicati
42 of a struct :ref:`v4l2_queryctrl <v4l2-queryct
43 ``VIDIOC_QUERYCTRL`` ioctl with a pointer to t
44 fills the rest of the structure or returns an
45 ``id`` is invalid.
46
47 It is possible to enumerate controls by callin
48 with successive ``id`` values starting from ``
49 exclusive ``V4L2_CID_LASTP1``. Drivers may ret
50 this range is not supported. Further applicati
51 controls, which are not defined in this specif
52 ``V4L2_CID_PRIVATE_BASE`` and incrementing ``i
53 returns ``EINVAL``.
54
55 In both cases, when the driver sets the ``V4L2
56 in the ``flags`` field this control is permane
57 be ignored by the application. [#f1]_
58
59 When the application ORs ``id`` with ``V4L2_CT
60 driver returns the next supported non-compound
61 there is none. In addition, the ``V4L2_CTRL_FL
62 can be specified to enumerate all compound con
63 type ≥ ``V4L2_CTRL_COMPOUND_TYPES`` and/or a
64 controls that contain more than one value). Sp
65 ``V4L2_CTRL_FLAG_NEXT_CTRL`` and ``V4L2_CTRL_F
66 order to enumerate all controls, compound or n
67 support these flags yet always return ``EINVAL
68
69 The ``VIDIOC_QUERY_EXT_CTRL`` ioctl was introd
70 support controls that can use compound types,
71 control information that cannot be returned in
72 :ref:`v4l2_queryctrl <v4l2-queryctrl>` since t
73
74 ``VIDIOC_QUERY_EXT_CTRL`` is used in the same
75 ``VIDIOC_QUERYCTRL``, except that the ``reserv
76 as well.
77
78 Additional information is required for menu co
79 menu items. To query them applications set the
80 fields of struct :ref:`v4l2_querymenu <v4l2-qu
81 ``VIDIOC_QUERYMENU`` ioctl with a pointer to t
82 fills the rest of the structure or returns an
83 ``id`` or ``index`` is invalid. Menu items are
84 ``VIDIOC_QUERYMENU`` with successive ``index``
85 :ref:`v4l2_queryctrl <v4l2-queryctrl>` ``minim
86 inclusive.
87
88 .. note::
89
90 It is possible for ``VIDIOC_QUERYMENU`` to
91 an ``EINVAL`` error code for some indices b
92 ``maximum``. In that case that particular m
93 this driver. Also note that the ``minimum``
94
95 See also the examples in :ref:`control`.
96
97 .. tabularcolumns:: |p{1.2cm}|p{3.6cm}|p{12.5c
98
99 .. _v4l2-queryctrl:
100
101 .. cssclass:: longtable
102
103 .. flat-table:: struct v4l2_queryctrl
104 :header-rows: 0
105 :stub-columns: 0
106 :widths: 1 1 2
107
108 * - __u32
109 - ``id``
110 - Identifies the control, set by the app
111 :ref:`control-id` for predefined IDs.
112 V4L2_CTRL_FLAG_NEXT_CTRL the driver cl
113 returns the first control with a highe
114 support this flag yet always return an
115 * - __u32
116 - ``type``
117 - Type of control, see :c:type:`v4l2_ctr
118 * - __u8
119 - ``name``\ [32]
120 - Name of the control, a NUL-terminated
121 information is intended for the user.
122 * - __s32
123 - ``minimum``
124 - Minimum value, inclusive. This field g
125 control. See enum :c:type:`v4l2_ctrl_t
126 the minimum value is to be used for ea
127 Note that this a signed 32-bit value.
128 * - __s32
129 - ``maximum``
130 - Maximum value, inclusive. This field g
131 control. See enum :c:type:`v4l2_ctrl_t
132 the maximum value is to be used for ea
133 Note that this a signed 32-bit value.
134 * - __s32
135 - ``step``
136 - This field gives a step size for the c
137 :c:type:`v4l2_ctrl_type` how the step
138 to be used for each possible control t
139 unsigned 32-bit value.
140
141 Generally drivers should not scale har
142 be necessary for example when the ``na
143 particular unit and the hardware actua
144 of said unit. If so, drivers must take
145 rounded when scaling, such that errors
146 repeated read-write cycles.
147
148 This field gives the smallest change o
149 actually affecting hardware. Often the
150 the user can change controls by keyboa
151 than a slider. When for example a hard
152 0-511 and the driver reports 0-65535,
153
154 Note that although signed, the step va
155 positive.
156 * - __s32
157 - ``default_value``
158 - The default value of a ``V4L2_CTRL_TYP
159 ``_BITMASK``, ``_MENU`` or ``_INTEGER_
160 for other types of controls.
161
162 .. note::
163
164 Drivers reset controls to their def
165 the driver is first loaded, never a
166 * - __u32
167 - ``flags``
168 - Control flags, see :ref:`control-flags
169 * - __u32
170 - ``reserved``\ [2]
171 - Reserved for future extensions. Driver
172 zero.
173
174
175 .. tabularcolumns:: |p{1.2cm}|p{5.5cm}|p{10.6c
176
177 .. _v4l2-query-ext-ctrl:
178
179 .. cssclass:: longtable
180
181 .. flat-table:: struct v4l2_query_ext_ctrl
182 :header-rows: 0
183 :stub-columns: 0
184 :widths: 1 1 2
185
186 * - __u32
187 - ``id``
188 - Identifies the control, set by the app
189 :ref:`control-id` for predefined IDs.
190 ``V4L2_CTRL_FLAG_NEXT_CTRL`` the drive
191 returns the first non-compound control
192 ID is ORed with ``V4L2_CTRL_FLAG_NEXT_
193 the flag and returns the first compoun
194 Set both to get the first control (com
195 ID.
196 * - __u32
197 - ``type``
198 - Type of control, see :c:type:`v4l2_ctr
199 * - char
200 - ``name``\ [32]
201 - Name of the control, a NUL-terminated
202 information is intended for the user.
203 * - __s64
204 - ``minimum``
205 - Minimum value, inclusive. This field g
206 control. See enum :c:type:`v4l2_ctrl_t
207 the minimum value is to be used for ea
208 Note that this a signed 64-bit value.
209 * - __s64
210 - ``maximum``
211 - Maximum value, inclusive. This field g
212 control. See enum :c:type:`v4l2_ctrl_t
213 the maximum value is to be used for ea
214 Note that this a signed 64-bit value.
215 * - __u64
216 - ``step``
217 - This field gives a step size for the c
218 :c:type:`v4l2_ctrl_type` how the step
219 to be used for each possible control t
220 unsigned 64-bit value.
221
222 Generally drivers should not scale har
223 be necessary for example when the ``na
224 particular unit and the hardware actua
225 of said unit. If so, drivers must take
226 rounded when scaling, such that errors
227 repeated read-write cycles.
228
229 This field gives the smallest change o
230 actually affecting hardware. Often the
231 the user can change controls by keyboa
232 than a slider. When for example a hard
233 0-511 and the driver reports 0-65535,
234 * - __s64
235 - ``default_value``
236 - The default value of a ``V4L2_CTRL_TYP
237 ``_BOOLEAN``, ``_BITMASK``, ``_MENU``,
238 or ``_U16`` control. Not valid for oth
239
240 .. note::
241
242 Drivers reset controls to their def
243 the driver is first loaded, never a
244 * - __u32
245 - ``flags``
246 - Control flags, see :ref:`control-flags
247 * - __u32
248 - ``elem_size``
249 - The size in bytes of a single element
250 pointer ``p`` to a 3-dimensional array
251 of cell ``(z, y, x)`` as follows:
252 ``p + ((z * dims[1] + y) * dims[0] + x
253 ``elem_size`` is always valid, also wh
254 array. For string controls ``elem_size
255 ``maximum + 1``.
256 * - __u32
257 - ``elems``
258 - The number of elements in the N-dimens
259 is not an array, then ``elems`` is 1.
260 never be 0.
261 * - __u32
262 - ``nr_of_dims``
263 - The number of dimension in the N-dimen
264 control is not an array, then this fie
265 * - __u32
266 - ``dims[V4L2_CTRL_MAX_DIMS]``
267 - The size of each dimension. The first
268 this array must be non-zero, all remai
269 * - __u32
270 - ``reserved``\ [32]
271 - Reserved for future extensions. Applic
272 the array to zero.
273
274
275 .. tabularcolumns:: |p{1.2cm}|p{3.0cm}|p{13.1c
276
277 .. _v4l2-querymenu:
278
279 .. flat-table:: struct v4l2_querymenu
280 :header-rows: 0
281 :stub-columns: 0
282 :widths: 1 1 2
283
284 * - __u32
285 - ``id``
286 - Identifies the control, set by the app
287 struct :ref:`v4l2_queryctrl <v4l2-quer
288 * - __u32
289 - ``index``
290 - Index of the menu item, starting at ze
291 * - union {
292 - (anonymous)
293 * - __u8
294 - ``name``\ [32]
295 - Name of the menu item, a NUL-terminate
296 information is intended for the user.
297 ``V4L2_CTRL_TYPE_MENU`` type controls.
298 * - __s64
299 - ``value``
300 - Value of the integer menu item. This f
301 ``V4L2_CTRL_TYPE_INTEGER_MENU`` type c
302 * - }
303 -
304 * - __u32
305 - ``reserved``
306 - Reserved for future extensions. Driver
307 zero.
308
309 .. c:type:: v4l2_ctrl_type
310
311 .. raw:: latex
312
313 \footnotesize
314
315 .. tabularcolumns:: |p{6.5cm}|p{1.5cm}|p{1.1cm
316
317 .. cssclass:: longtable
318
319 .. flat-table:: enum v4l2_ctrl_type
320 :header-rows: 1
321 :stub-columns: 0
322 :widths: 30 5 5 5 55
323
324 * - Type
325 - ``minimum``
326 - ``step``
327 - ``maximum``
328 - Description
329 * - ``V4L2_CTRL_TYPE_INTEGER``
330 - any
331 - any
332 - any
333 - An integer-valued control ranging from
334 inclusive. The step value indicates th
335 * - ``V4L2_CTRL_TYPE_BOOLEAN``
336 - 0
337 - 1
338 - 1
339 - A boolean-valued control. Zero corresp
340 means "enabled".
341 * - ``V4L2_CTRL_TYPE_MENU``
342 - ≥ 0
343 - 1
344 - N-1
345 - The control has a menu of N choices. T
346 can be enumerated with the ``VIDIOC_QU
347 * - ``V4L2_CTRL_TYPE_INTEGER_MENU``
348 - ≥ 0
349 - 1
350 - N-1
351 - The control has a menu of N choices. T
352 can be enumerated with the ``VIDIOC_QU
353 similar to ``V4L2_CTRL_TYPE_MENU`` exc
354 the menu items are signed 64-bit integ
355 * - ``V4L2_CTRL_TYPE_BITMASK``
356 - 0
357 - n/a
358 - any
359 - A bitmask field. The maximum value is
360 used, all other bits are to be 0. The
361 as a __u32, allowing the use of bit 31
362 * - ``V4L2_CTRL_TYPE_BUTTON``
363 - 0
364 - 0
365 - 0
366 - A control which performs an action whe
367 the value passed with ``VIDIOC_S_CTRL`
368 code on a ``VIDIOC_G_CTRL`` attempt.
369 * - ``V4L2_CTRL_TYPE_INTEGER64``
370 - any
371 - any
372 - any
373 - A 64-bit integer valued control. Minim
374 cannot be queried using ``VIDIOC_QUERY
375 ``VIDIOC_QUERY_EXT_CTRL`` can retrieve
376 values, they should be interpreted as
377 ``VIDIOC_QUERYCTRL``.
378 * - ``V4L2_CTRL_TYPE_STRING``
379 - ≥ 0
380 - ≥ 1
381 - ≥ 0
382 - The minimum and maximum string lengths
383 the string must be (minimum + N * step
384 These lengths do not include the termi
385 pass a string of length 8 to
386 :ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT
387 set the ``size`` field of struct
388 :c:type:`v4l2_ext_control` to 9. For
389 :ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT
390 the ``size`` field to ``maximum`` + 1.
391 used will depend on the string control
392 of the control documentation.
393 * - ``V4L2_CTRL_TYPE_CTRL_CLASS``
394 - n/a
395 - n/a
396 - n/a
397 - This is not a control. When ``VIDIOC_Q
398 control ID equal to a control class co
399 + 1, the ioctl returns the name of the
400 control type. Older drivers which do n
401 return an ``EINVAL`` error code.
402 * - ``V4L2_CTRL_TYPE_U8``
403 - any
404 - any
405 - any
406 - An unsigned 8-bit valued control rangi
407 inclusive. The step value indicates th
408 * - ``V4L2_CTRL_TYPE_U16``
409 - any
410 - any
411 - any
412 - An unsigned 16-bit valued control rang
413 inclusive. The step value indicates th
414 * - ``V4L2_CTRL_TYPE_U32``
415 - any
416 - any
417 - any
418 - An unsigned 32-bit valued control rang
419 inclusive. The step value indicates th
420 * - ``V4L2_CTRL_TYPE_MPEG2_QUANTISATION``
421 - n/a
422 - n/a
423 - n/a
424 - A struct :c:type:`v4l2_ctrl_mpeg2_quan
425 quantisation matrices for stateless vi
426 * - ``V4L2_CTRL_TYPE_MPEG2_SEQUENCE``
427 - n/a
428 - n/a
429 - n/a
430 - A struct :c:type:`v4l2_ctrl_mpeg2_sequ
431 sequence parameters for stateless vide
432 * - ``V4L2_CTRL_TYPE_MPEG2_PICTURE``
433 - n/a
434 - n/a
435 - n/a
436 - A struct :c:type:`v4l2_ctrl_mpeg2_pict
437 picture parameters for stateless video
438 * - ``V4L2_CTRL_TYPE_AREA``
439 - n/a
440 - n/a
441 - n/a
442 - A struct :c:type:`v4l2_area`, containi
443 of a rectangular area. Units depend on
444 * - ``V4L2_CTRL_TYPE_H264_SPS``
445 - n/a
446 - n/a
447 - n/a
448 - A struct :c:type:`v4l2_ctrl_h264_sps`,
449 sequence parameters for stateless vide
450 * - ``V4L2_CTRL_TYPE_H264_PPS``
451 - n/a
452 - n/a
453 - n/a
454 - A struct :c:type:`v4l2_ctrl_h264_pps`,
455 picture parameters for stateless video
456 * - ``V4L2_CTRL_TYPE_H264_SCALING_MATRIX``
457 - n/a
458 - n/a
459 - n/a
460 - A struct :c:type:`v4l2_ctrl_h264_scali
461 scaling matrices for stateless video d
462 * - ``V4L2_CTRL_TYPE_H264_SLICE_PARAMS``
463 - n/a
464 - n/a
465 - n/a
466 - A struct :c:type:`v4l2_ctrl_h264_slice
467 slice parameters for stateless video d
468 * - ``V4L2_CTRL_TYPE_H264_DECODE_PARAMS``
469 - n/a
470 - n/a
471 - n/a
472 - A struct :c:type:`v4l2_ctrl_h264_decod
473 decode parameters for stateless video
474 * - ``V4L2_CTRL_TYPE_FWHT_PARAMS``
475 - n/a
476 - n/a
477 - n/a
478 - A struct :c:type:`v4l2_ctrl_fwht_param
479 parameters for stateless video decoder
480 * - ``V4L2_CTRL_TYPE_HEVC_SPS``
481 - n/a
482 - n/a
483 - n/a
484 - A struct :c:type:`v4l2_ctrl_hevc_sps`,
485 Parameter Set for stateless video deco
486 * - ``V4L2_CTRL_TYPE_HEVC_PPS``
487 - n/a
488 - n/a
489 - n/a
490 - A struct :c:type:`v4l2_ctrl_hevc_pps`,
491 Parameter Set for stateless video deco
492 * - ``V4L2_CTRL_TYPE_HEVC_SLICE_PARAMS``
493 - n/a
494 - n/a
495 - n/a
496 - A struct :c:type:`v4l2_ctrl_hevc_slice
497 slice parameters for stateless video d
498 * - ``V4L2_CTRL_TYPE_HEVC_SCALING_MATRIX``
499 - n/a
500 - n/a
501 - n/a
502 - A struct :c:type:`v4l2_ctrl_hevc_scali
503 scaling matrix for stateless video dec
504 * - ``V4L2_CTRL_TYPE_VP8_FRAME``
505 - n/a
506 - n/a
507 - n/a
508 - A struct :c:type:`v4l2_ctrl_vp8_frame`
509 frame parameters for stateless video d
510 * - ``V4L2_CTRL_TYPE_HEVC_DECODE_PARAMS``
511 - n/a
512 - n/a
513 - n/a
514 - A struct :c:type:`v4l2_ctrl_hevc_decod
515 decoding parameters for stateless vide
516 * - ``V4L2_CTRL_TYPE_VP9_COMPRESSED_HDR``
517 - n/a
518 - n/a
519 - n/a
520 - A struct :c:type:`v4l2_ctrl_vp9_compre
521 probabilities updates for stateless vi
522 * - ``V4L2_CTRL_TYPE_VP9_FRAME``
523 - n/a
524 - n/a
525 - n/a
526 - A struct :c:type:`v4l2_ctrl_vp9_frame`
527 frame decode parameters for stateless
528 * - ``V4L2_CTRL_TYPE_AV1_SEQUENCE``
529 - n/a
530 - n/a
531 - n/a
532 - A struct :c:type:`v4l2_ctrl_av1_sequen
533 decoding parameters for stateless vide
534 * - ``V4L2_CTRL_TYPE_AV1_TILE_GROUP_ENTRY`
535 - n/a
536 - n/a
537 - n/a
538 - A struct :c:type:`v4l2_ctrl_av1_tile_g
539 OBU decoding parameters for stateless
540 * - ``V4L2_CTRL_TYPE_AV1_FRAME``
541 - n/a
542 - n/a
543 - n/a
544 - A struct :c:type:`v4l2_ctrl_av1_frame`
545 Header OBU decoding parameters for sta
546 * - ``V4L2_CTRL_TYPE_AV1_FILM_GRAIN``
547 - n/a
548 - n/a
549 - n/a
550 - A struct :c:type:`v4l2_ctrl_av1_film_g
551 parameters for stateless video decoder
552
553 .. raw:: latex
554
555 \normalsize
556
557 .. tabularcolumns:: |p{7.3cm}|p{1.8cm}|p{8.2cm
558
559 .. cssclass:: longtable
560
561 .. _control-flags:
562
563 .. flat-table:: Control Flags
564 :header-rows: 0
565 :stub-columns: 0
566 :widths: 3 1 4
567
568 * - ``V4L2_CTRL_FLAG_DISABLED``
569 - 0x0001
570 - This control is permanently disabled a
571 application. Any attempt to change the
572 ``EINVAL`` error code.
573 * - ``V4L2_CTRL_FLAG_GRABBED``
574 - 0x0002
575 - This control is temporarily unchangeab
576 another application took over control
577 Such controls may be displayed special
578 Attempts to change the control may res
579 * - ``V4L2_CTRL_FLAG_READ_ONLY``
580 - 0x0004
581 - This control is permanently readable o
582 the control will result in an ``EINVAL
583 * - ``V4L2_CTRL_FLAG_UPDATE``
584 - 0x0008
585 - A hint that changing this control may
586 controls within the same control class
587 their user interface accordingly.
588 * - ``V4L2_CTRL_FLAG_INACTIVE``
589 - 0x0010
590 - This control is not applicable to the
591 should be displayed accordingly in a u
592 the flag may be set on a MPEG audio le
593 MPEG audio encoding level 1 was select
594 * - ``V4L2_CTRL_FLAG_SLIDER``
595 - 0x0020
596 - A hint that this control is best repre
597 element in a user interface.
598 * - ``V4L2_CTRL_FLAG_WRITE_ONLY``
599 - 0x0040
600 - This control is permanently writable o
601 control will result in an ``EACCES`` e
602 is typically present for relative cont
603 where writing a value will cause the d
604 action (e. g. motor control) but no me
605 returned.
606 * - ``V4L2_CTRL_FLAG_VOLATILE``
607 - 0x0080
608 - This control is volatile, which means
609 control changes continuously. A typica
610 current gain value if the device is in
611 case the hardware calculates the gain
612 conditions which can change over time.
613
614 .. note::
615
616 Setting a new value for a volatile
617 unless
618 :ref:`V4L2_CTRL_FLAG_EXECUTE_ON_WRI
619 is also set.
620 Setting a new value for a volatile
621 :ref:`V4L2_EVENT_CTRL_CH_VALUE <ctr
622 * - ``V4L2_CTRL_FLAG_HAS_PAYLOAD``
623 - 0x0100
624 - This control has a pointer type, so it
625 using one of the pointer fields of str
626 :c:type:`v4l2_ext_control`. This flag
627 for controls that are an array, string
628 In all cases you have to set a pointer
629 payload of the control.
630 * .. _FLAG_EXECUTE_ON_WRITE:
631
632 - ``V4L2_CTRL_FLAG_EXECUTE_ON_WRITE``
633 - 0x0200
634 - The value provided to the control will
635 even if it remains constant. This is r
636 represents an action on the hardware.
637 error flag or triggering the flash. Al
638 ``V4L2_CTRL_TYPE_BUTTON`` have this fl
639 * .. _FLAG_MODIFY_LAYOUT:
640
641 - ``V4L2_CTRL_FLAG_MODIFY_LAYOUT``
642 - 0x0400
643 - Changing this control value may modify
644 buffer (for video devices) or the medi
645
646 A typical example would be the ``V4L2_
647
648 Note that typically controls with this
649 ``V4L2_CTRL_FLAG_GRABBED`` flag when b
650 streaming is in progress since most dr
651 the format in that case.
652 * - ``V4L2_CTRL_FLAG_DYNAMIC_ARRAY``
653 - 0x0800
654 - This control is a dynamically sized 1-
655 behaves the same as a regular array, e
656 of elements as reported by the ``elems
657 ``dims[0]``. So setting the control wi
658 array will change the ``elems`` field
659 queried afterwards.
660
661 Return Value
662 ============
663
664 On success 0 is returned, on error -1 and the
665 appropriately. The generic error codes are des
666 :ref:`Generic Error Codes <gen-errors>` chapte
667
668 EINVAL
669 The struct :ref:`v4l2_queryctrl <v4l2-quer
670 invalid. The struct :ref:`v4l2_querymenu <
671 is invalid or ``index`` is out of range (l
672 greater than ``maximum``) or this particul
673 supported by the driver.
674
675 EACCES
676 An attempt was made to read a write-only c
677
678 .. [#f1]
679 ``V4L2_CTRL_FLAG_DISABLED`` was intended fo
680 can skip predefined controls not supported
681 returning ``EINVAL`` would do as well), or
682 controls after hardware detection without t
683 control arrays and indices (``EINVAL`` cann
684 controls because it would prematurely end t
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.