1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
2.. c:namespace:: V4L
3
4.. _VIDIOC_QUERYCTRL:
5
6*******************************************************************
7ioctls VIDIOC_QUERYCTRL, VIDIOC_QUERY_EXT_CTRL and VIDIOC_QUERYMENU
8*******************************************************************
9
10Name
11====
12
13VIDIOC_QUERYCTRL - VIDIOC_QUERY_EXT_CTRL - VIDIOC_QUERYMENU - Enumerate controls and menu control items
14
15Synopsis
16========
17
18``int ioctl(int fd, int VIDIOC_QUERYCTRL, struct v4l2_queryctrl *argp)``
19
20.. c:macro:: VIDIOC_QUERY_EXT_CTRL
21
22``int ioctl(int fd, VIDIOC_QUERY_EXT_CTRL, struct v4l2_query_ext_ctrl *argp)``
23
24.. c:macro:: VIDIOC_QUERYMENU
25
26``int ioctl(int fd, VIDIOC_QUERYMENU, struct v4l2_querymenu *argp)``
27
28Arguments
29=========
30
31``fd``
32    File descriptor returned by :c:func:`open()`.
33
34``argp``
35    Pointer to struct :c:type:`v4l2_queryctrl`, :c:type:`v4l2_query_ext_ctrl`
36    or :c:type:`v4l2_querymenu` (depending on the ioctl).
37
38Description
39===========
40
41To query the attributes of a control applications set the ``id`` field
42of a struct :ref:`v4l2_queryctrl <v4l2-queryctrl>` and call the
43``VIDIOC_QUERYCTRL`` ioctl with a pointer to this structure. The driver
44fills the rest of the structure or returns an ``EINVAL`` error code when the
45``id`` is invalid.
46
47It is possible to enumerate controls by calling ``VIDIOC_QUERYCTRL``
48with successive ``id`` values starting from ``V4L2_CID_BASE`` up to and
49exclusive ``V4L2_CID_LASTP1``. Drivers may return ``EINVAL`` if a control in
50this range is not supported. Further applications can enumerate private
51controls, which are not defined in this specification, by starting at
52``V4L2_CID_PRIVATE_BASE`` and incrementing ``id`` until the driver
53returns ``EINVAL``.
54
55In both cases, when the driver sets the ``V4L2_CTRL_FLAG_DISABLED`` flag
56in the ``flags`` field this control is permanently disabled and should
57be ignored by the application. [#f1]_
58
59When the application ORs ``id`` with ``V4L2_CTRL_FLAG_NEXT_CTRL`` the
60driver returns the next supported non-compound control, or ``EINVAL`` if
61there is none. In addition, the ``V4L2_CTRL_FLAG_NEXT_COMPOUND`` flag
62can be specified to enumerate all compound controls (i.e. controls with
63type ≥ ``V4L2_CTRL_COMPOUND_TYPES`` and/or array control, in other words
64controls that contain more than one value). Specify both
65``V4L2_CTRL_FLAG_NEXT_CTRL`` and ``V4L2_CTRL_FLAG_NEXT_COMPOUND`` in
66order to enumerate all controls, compound or not. Drivers which do not
67support these flags yet always return ``EINVAL``.
68
69The ``VIDIOC_QUERY_EXT_CTRL`` ioctl was introduced in order to better
70support controls that can use compound types, and to expose additional
71control information that cannot be returned in struct
72:ref:`v4l2_queryctrl <v4l2-queryctrl>` since that structure is full.
73
74``VIDIOC_QUERY_EXT_CTRL`` is used in the same way as
75``VIDIOC_QUERYCTRL``, except that the ``reserved`` array must be zeroed
76as well.
77
78Additional information is required for menu controls: the names of the
79menu items. To query them applications set the ``id`` and ``index``
80fields of struct :ref:`v4l2_querymenu <v4l2-querymenu>` and call the
81``VIDIOC_QUERYMENU`` ioctl with a pointer to this structure. The driver
82fills the rest of the structure or returns an ``EINVAL`` error code when the
83``id`` or ``index`` is invalid. Menu items are enumerated by calling
84``VIDIOC_QUERYMENU`` with successive ``index`` values from struct
85:ref:`v4l2_queryctrl <v4l2-queryctrl>` ``minimum`` to ``maximum``,
86inclusive.
87
88.. note::
89
90   It is possible for ``VIDIOC_QUERYMENU`` to return
91   an ``EINVAL`` error code for some indices between ``minimum`` and
92   ``maximum``. In that case that particular menu item is not supported by
93   this driver. Also note that the ``minimum`` value is not necessarily 0.
94
95See also the examples in :ref:`control`.
96
97.. tabularcolumns:: |p{1.2cm}|p{3.6cm}|p{12.5cm}|
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 application. See
111	:ref:`control-id` for predefined IDs. When the ID is ORed with
112	V4L2_CTRL_FLAG_NEXT_CTRL the driver clears the flag and
113	returns the first control with a higher ID. Drivers which do not
114	support this flag yet always return an ``EINVAL`` error code.
115    * - __u32
116      - ``type``
117      - Type of control, see :c:type:`v4l2_ctrl_type`.
118    * - __u8
119      - ``name``\ [32]
120      - Name of the control, a NUL-terminated ASCII string. This
121	information is intended for the user.
122    * - __s32
123      - ``minimum``
124      - Minimum value, inclusive. This field gives a lower bound for the
125	control. See enum :c:type:`v4l2_ctrl_type` how
126	the minimum value is to be used for each possible control type.
127	Note that this a signed 32-bit value.
128    * - __s32
129      - ``maximum``
130      - Maximum value, inclusive. This field gives an upper bound for the
131	control. See enum :c:type:`v4l2_ctrl_type` how
132	the maximum value is to be used for each possible control type.
133	Note that this a signed 32-bit value.
134    * - __s32
135      - ``step``
136      - This field gives a step size for the control. See enum
137	:c:type:`v4l2_ctrl_type` how the step value is
138	to be used for each possible control type. Note that this an
139	unsigned 32-bit value.
140
141	Generally drivers should not scale hardware control values. It may
142	be necessary for example when the ``name`` or ``id`` imply a
143	particular unit and the hardware actually accepts only multiples
144	of said unit. If so, drivers must take care values are properly
145	rounded when scaling, such that errors will not accumulate on
146	repeated read-write cycles.
147
148	This field gives the smallest change of an integer control
149	actually affecting hardware. Often the information is needed when
150	the user can change controls by keyboard or GUI buttons, rather
151	than a slider. When for example a hardware register accepts values
152	0-511 and the driver reports 0-65535, step should be 128.
153
154	Note that although signed, the step value is supposed to be always
155	positive.
156    * - __s32
157      - ``default_value``
158      - The default value of a ``V4L2_CTRL_TYPE_INTEGER``, ``_BOOLEAN``,
159	``_BITMASK``, ``_MENU`` or ``_INTEGER_MENU`` control. Not valid
160	for other types of controls.
161
162	.. note::
163
164	   Drivers reset controls to their default value only when
165	   the driver is first loaded, never afterwards.
166    * - __u32
167      - ``flags``
168      - Control flags, see :ref:`control-flags`.
169    * - __u32
170      - ``reserved``\ [2]
171      - Reserved for future extensions. Drivers must set the array to
172	zero.
173
174
175.. tabularcolumns:: |p{1.2cm}|p{5.5cm}|p{10.6cm}|
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 application. See
189	:ref:`control-id` for predefined IDs. When the ID is ORed with
190	``V4L2_CTRL_FLAG_NEXT_CTRL`` the driver clears the flag and
191	returns the first non-compound control with a higher ID. When the
192	ID is ORed with ``V4L2_CTRL_FLAG_NEXT_COMPOUND`` the driver clears
193	the flag and returns the first compound control with a higher ID.
194	Set both to get the first control (compound or not) with a higher
195	ID.
196    * - __u32
197      - ``type``
198      - Type of control, see :c:type:`v4l2_ctrl_type`.
199    * - char
200      - ``name``\ [32]
201      - Name of the control, a NUL-terminated ASCII string. This
202	information is intended for the user.
203    * - __s64
204      - ``minimum``
205      - Minimum value, inclusive. This field gives a lower bound for the
206	control. See enum :c:type:`v4l2_ctrl_type` how
207	the minimum value is to be used for each possible control type.
208	Note that this a signed 64-bit value.
209    * - __s64
210      - ``maximum``
211      - Maximum value, inclusive. This field gives an upper bound for the
212	control. See enum :c:type:`v4l2_ctrl_type` how
213	the maximum value is to be used for each possible control type.
214	Note that this a signed 64-bit value.
215    * - __u64
216      - ``step``
217      - This field gives a step size for the control. See enum
218	:c:type:`v4l2_ctrl_type` how the step value is
219	to be used for each possible control type. Note that this an
220	unsigned 64-bit value.
221
222	Generally drivers should not scale hardware control values. It may
223	be necessary for example when the ``name`` or ``id`` imply a
224	particular unit and the hardware actually accepts only multiples
225	of said unit. If so, drivers must take care values are properly
226	rounded when scaling, such that errors will not accumulate on
227	repeated read-write cycles.
228
229	This field gives the smallest change of an integer control
230	actually affecting hardware. Often the information is needed when
231	the user can change controls by keyboard or GUI buttons, rather
232	than a slider. When for example a hardware register accepts values
233	0-511 and the driver reports 0-65535, step should be 128.
234    * - __s64
235      - ``default_value``
236      - The default value of a ``V4L2_CTRL_TYPE_INTEGER``, ``_INTEGER64``,
237	``_BOOLEAN``, ``_BITMASK``, ``_MENU``, ``_INTEGER_MENU``, ``_U8``
238	or ``_U16`` control. Not valid for other types of controls.
239
240	.. note::
241
242	   Drivers reset controls to their default value only when
243	   the driver is first loaded, never afterwards.
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 of the array. Given a char
250	pointer ``p`` to a 3-dimensional array you can find the position
251	of cell ``(z, y, x)`` as follows:
252	``p + ((z * dims[1] + y) * dims[0] + x) * elem_size``.
253	``elem_size`` is always valid, also when the control isn't an
254	array. For string controls ``elem_size`` is equal to
255	``maximum + 1``.
256    * - __u32
257      - ``elems``
258      - The number of elements in the N-dimensional array. If this control
259	is not an array, then ``elems`` is 1. The ``elems`` field can
260	never be 0.
261    * - __u32
262      - ``nr_of_dims``
263      - The number of dimension in the N-dimensional array. If this
264	control is not an array, then this field is 0.
265    * - __u32
266      - ``dims[V4L2_CTRL_MAX_DIMS]``
267      - The size of each dimension. The first ``nr_of_dims`` elements of
268	this array must be non-zero, all remaining elements must be zero.
269    * - __u32
270      - ``reserved``\ [32]
271      - Reserved for future extensions. Applications and drivers must set
272	the array to zero.
273
274
275.. tabularcolumns:: |p{1.2cm}|p{3.0cm}|p{13.1cm}|
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 application from the respective
287	struct :ref:`v4l2_queryctrl <v4l2-queryctrl>` ``id``.
288    * - __u32
289      - ``index``
290      - Index of the menu item, starting at zero, set by the application.
291    * - union {
292      - (anonymous)
293    * - __u8
294      - ``name``\ [32]
295      - Name of the menu item, a NUL-terminated ASCII string. This
296	information is intended for the user. This field is valid for
297	``V4L2_CTRL_TYPE_MENU`` type controls.
298    * - __s64
299      - ``value``
300      - Value of the integer menu item. This field is valid for
301	``V4L2_CTRL_TYPE_INTEGER_MENU`` type controls.
302    * - }
303      -
304    * - __u32
305      - ``reserved``
306      - Reserved for future extensions. Drivers must set the array to
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}|p{1.5cm}|p{6.8cm}|
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 minimum to maximum
334	inclusive. The step value indicates the increment between values.
335    * - ``V4L2_CTRL_TYPE_BOOLEAN``
336      - 0
337      - 1
338      - 1
339      - A boolean-valued control. Zero corresponds to "disabled", and one
340	means "enabled".
341    * - ``V4L2_CTRL_TYPE_MENU``
342      - ≥ 0
343      - 1
344      - N-1
345      - The control has a menu of N choices. The names of the menu items
346	can be enumerated with the ``VIDIOC_QUERYMENU`` ioctl.
347    * - ``V4L2_CTRL_TYPE_INTEGER_MENU``
348      - ≥ 0
349      - 1
350      - N-1
351      - The control has a menu of N choices. The values of the menu items
352	can be enumerated with the ``VIDIOC_QUERYMENU`` ioctl. This is
353	similar to ``V4L2_CTRL_TYPE_MENU`` except that instead of strings,
354	the menu items are signed 64-bit integers.
355    * - ``V4L2_CTRL_TYPE_BITMASK``
356      - 0
357      - n/a
358      - any
359      - A bitmask field. The maximum value is the set of bits that can be
360	used, all other bits are to be 0. The maximum value is interpreted
361	as a __u32, allowing the use of bit 31 in the bitmask.
362    * - ``V4L2_CTRL_TYPE_BUTTON``
363      - 0
364      - 0
365      - 0
366      - A control which performs an action when set. Drivers must ignore
367	the value passed with ``VIDIOC_S_CTRL`` and return an ``EACCES`` error
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. Minimum, maximum and step size
374	cannot be queried using ``VIDIOC_QUERYCTRL``. Only
375	``VIDIOC_QUERY_EXT_CTRL`` can retrieve the 64-bit min/max/step
376	values, they should be interpreted as n/a when using
377	``VIDIOC_QUERYCTRL``.
378    * - ``V4L2_CTRL_TYPE_STRING``
379      - ≥ 0
380      - ≥ 1
381      - ≥ 0
382      - The minimum and maximum string lengths. The step size means that
383	the string must be (minimum + N * step) characters long for N ≥ 0.
384	These lengths do not include the terminating zero, so in order to
385	pass a string of length 8 to
386	:ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` you need to
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_CTRLS>` you can set
390	the ``size`` field to ``maximum`` + 1. Which character encoding is
391	used will depend on the string control itself and should be part
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_QUERYCTRL`` is called with a
398	control ID equal to a control class code (see :ref:`ctrl-class`)
399	+ 1, the ioctl returns the name of the control class and this
400	control type. Older drivers which do not support this feature
401	return an ``EINVAL`` error code.
402    * - ``V4L2_CTRL_TYPE_U8``
403      - any
404      - any
405      - any
406      - An unsigned 8-bit valued control ranging from minimum to maximum
407	inclusive. The step value indicates the increment between values.
408    * - ``V4L2_CTRL_TYPE_U16``
409      - any
410      - any
411      - any
412      - An unsigned 16-bit valued control ranging from minimum to maximum
413	inclusive. The step value indicates the increment between values.
414    * - ``V4L2_CTRL_TYPE_U32``
415      - any
416      - any
417      - any
418      - An unsigned 32-bit valued control ranging from minimum to maximum
419	inclusive. The step value indicates the increment between values.
420    * - ``V4L2_CTRL_TYPE_MPEG2_QUANTISATION``
421      - n/a
422      - n/a
423      - n/a
424      - A struct :c:type:`v4l2_ctrl_mpeg2_quantisation`, containing MPEG-2
425	quantisation matrices for stateless video decoders.
426    * - ``V4L2_CTRL_TYPE_MPEG2_SEQUENCE``
427      - n/a
428      - n/a
429      - n/a
430      - A struct :c:type:`v4l2_ctrl_mpeg2_sequence`, containing MPEG-2
431	sequence parameters for stateless video decoders.
432    * - ``V4L2_CTRL_TYPE_MPEG2_PICTURE``
433      - n/a
434      - n/a
435      - n/a
436      - A struct :c:type:`v4l2_ctrl_mpeg2_picture`, containing MPEG-2
437	picture parameters for stateless video decoders.
438    * - ``V4L2_CTRL_TYPE_AREA``
439      - n/a
440      - n/a
441      - n/a
442      - A struct :c:type:`v4l2_area`, containing the width and the height
443        of a rectangular area. Units depend on the use case.
444    * - ``V4L2_CTRL_TYPE_H264_SPS``
445      - n/a
446      - n/a
447      - n/a
448      - A struct :c:type:`v4l2_ctrl_h264_sps`, containing H264
449	sequence parameters for stateless video decoders.
450    * - ``V4L2_CTRL_TYPE_H264_PPS``
451      - n/a
452      - n/a
453      - n/a
454      - A struct :c:type:`v4l2_ctrl_h264_pps`, containing H264
455	picture parameters for stateless video decoders.
456    * - ``V4L2_CTRL_TYPE_H264_SCALING_MATRIX``
457      - n/a
458      - n/a
459      - n/a
460      - A struct :c:type:`v4l2_ctrl_h264_scaling_matrix`, containing H264
461	scaling matrices for stateless video decoders.
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_params`, containing H264
467	slice parameters for stateless video decoders.
468    * - ``V4L2_CTRL_TYPE_H264_DECODE_PARAMS``
469      - n/a
470      - n/a
471      - n/a
472      - A struct :c:type:`v4l2_ctrl_h264_decode_params`, containing H264
473	decode parameters for stateless video decoders.
474    * - ``V4L2_CTRL_TYPE_FWHT_PARAMS``
475      - n/a
476      - n/a
477      - n/a
478      - A struct :c:type:`v4l2_ctrl_fwht_params`, containing FWHT
479	parameters for stateless video decoders.
480    * - ``V4L2_CTRL_TYPE_HEVC_SPS``
481      - n/a
482      - n/a
483      - n/a
484      - A struct :c:type:`v4l2_ctrl_hevc_sps`, containing HEVC Sequence
485	Parameter Set for stateless video decoders.
486    * - ``V4L2_CTRL_TYPE_HEVC_PPS``
487      - n/a
488      - n/a
489      - n/a
490      - A struct :c:type:`v4l2_ctrl_hevc_pps`, containing HEVC Picture
491	Parameter Set for stateless video decoders.
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_params`, containing HEVC
497	slice parameters for stateless video decoders.
498    * - ``V4L2_CTRL_TYPE_HEVC_SCALING_MATRIX``
499      - n/a
500      - n/a
501      - n/a
502      - A struct :c:type:`v4l2_ctrl_hevc_scaling_matrix`, containing HEVC
503	scaling matrix for stateless video decoders.
504    * - ``V4L2_CTRL_TYPE_VP8_FRAME``
505      - n/a
506      - n/a
507      - n/a
508      - A struct :c:type:`v4l2_ctrl_vp8_frame`, containing VP8
509	frame parameters for stateless video decoders.
510    * - ``V4L2_CTRL_TYPE_HEVC_DECODE_PARAMS``
511      - n/a
512      - n/a
513      - n/a
514      - A struct :c:type:`v4l2_ctrl_hevc_decode_params`, containing HEVC
515	decoding parameters for stateless video decoders.
516    * - ``V4L2_CTRL_TYPE_VP9_COMPRESSED_HDR``
517      - n/a
518      - n/a
519      - n/a
520      - A struct :c:type:`v4l2_ctrl_vp9_compressed_hdr`, containing VP9
521	probabilities updates for stateless video decoders.
522    * - ``V4L2_CTRL_TYPE_VP9_FRAME``
523      - n/a
524      - n/a
525      - n/a
526      - A struct :c:type:`v4l2_ctrl_vp9_frame`, containing VP9
527	frame decode parameters for stateless video decoders.
528
529.. raw:: latex
530
531   \normalsize
532
533.. tabularcolumns:: |p{7.3cm}|p{1.8cm}|p{8.2cm}|
534
535.. cssclass:: longtable
536
537.. _control-flags:
538
539.. flat-table:: Control Flags
540    :header-rows:  0
541    :stub-columns: 0
542    :widths:       3 1 4
543
544    * - ``V4L2_CTRL_FLAG_DISABLED``
545      - 0x0001
546      - This control is permanently disabled and should be ignored by the
547	application. Any attempt to change the control will result in an
548	``EINVAL`` error code.
549    * - ``V4L2_CTRL_FLAG_GRABBED``
550      - 0x0002
551      - This control is temporarily unchangeable, for example because
552	another application took over control of the respective resource.
553	Such controls may be displayed specially in a user interface.
554	Attempts to change the control may result in an ``EBUSY`` error code.
555    * - ``V4L2_CTRL_FLAG_READ_ONLY``
556      - 0x0004
557      - This control is permanently readable only. Any attempt to change
558	the control will result in an ``EINVAL`` error code.
559    * - ``V4L2_CTRL_FLAG_UPDATE``
560      - 0x0008
561      - A hint that changing this control may affect the value of other
562	controls within the same control class. Applications should update
563	their user interface accordingly.
564    * - ``V4L2_CTRL_FLAG_INACTIVE``
565      - 0x0010
566      - This control is not applicable to the current configuration and
567	should be displayed accordingly in a user interface. For example
568	the flag may be set on a MPEG audio level 2 bitrate control when
569	MPEG audio encoding level 1 was selected with another control.
570    * - ``V4L2_CTRL_FLAG_SLIDER``
571      - 0x0020
572      - A hint that this control is best represented as a slider-like
573	element in a user interface.
574    * - ``V4L2_CTRL_FLAG_WRITE_ONLY``
575      - 0x0040
576      - This control is permanently writable only. Any attempt to read the
577	control will result in an ``EACCES`` error code error code. This flag
578	is typically present for relative controls or action controls
579	where writing a value will cause the device to carry out a given
580	action (e. g. motor control) but no meaningful value can be
581	returned.
582    * - ``V4L2_CTRL_FLAG_VOLATILE``
583      - 0x0080
584      - This control is volatile, which means that the value of the
585	control changes continuously. A typical example would be the
586	current gain value if the device is in auto-gain mode. In such a
587	case the hardware calculates the gain value based on the lighting
588	conditions which can change over time.
589
590	.. note::
591
592	   Setting a new value for a volatile control will be ignored
593	   unless
594	   :ref:`V4L2_CTRL_FLAG_EXECUTE_ON_WRITE <FLAG_EXECUTE_ON_WRITE>`
595	   is also set.
596	   Setting a new value for a volatile control will *never* trigger a
597	   :ref:`V4L2_EVENT_CTRL_CH_VALUE <ctrl-changes-flags>` event.
598    * - ``V4L2_CTRL_FLAG_HAS_PAYLOAD``
599      - 0x0100
600      - This control has a pointer type, so its value has to be accessed
601	using one of the pointer fields of struct
602	:c:type:`v4l2_ext_control`. This flag is set
603	for controls that are an array, string, or have a compound type.
604	In all cases you have to set a pointer to memory containing the
605	payload of the control.
606    * .. _FLAG_EXECUTE_ON_WRITE:
607
608      - ``V4L2_CTRL_FLAG_EXECUTE_ON_WRITE``
609      - 0x0200
610      - The value provided to the control will be propagated to the driver
611	even if it remains constant. This is required when the control
612	represents an action on the hardware. For example: clearing an
613	error flag or triggering the flash. All the controls of the type
614	``V4L2_CTRL_TYPE_BUTTON`` have this flag set.
615    * .. _FLAG_MODIFY_LAYOUT:
616
617      - ``V4L2_CTRL_FLAG_MODIFY_LAYOUT``
618      - 0x0400
619      - Changing this control value may modify the layout of the
620        buffer (for video devices) or the media bus format (for sub-devices).
621
622	A typical example would be the ``V4L2_CID_ROTATE`` control.
623
624	Note that typically controls with this flag will also set the
625	``V4L2_CTRL_FLAG_GRABBED`` flag when buffers are allocated or
626	streaming is in progress since most drivers do not support changing
627	the format in that case.
628    * - ``V4L2_CTRL_FLAG_DYNAMIC_ARRAY``
629      - 0x0800
630      - This control is a dynamically sized 1-dimensional array. It
631        behaves the same as a regular array, except that the number
632	of elements as reported by the ``elems`` field is between 1 and
633	``dims[0]``. So setting the control with a differently sized
634	array will change the ``elems`` field when the control is
635	queried afterwards.
636
637Return Value
638============
639
640On success 0 is returned, on error -1 and the ``errno`` variable is set
641appropriately. The generic error codes are described at the
642:ref:`Generic Error Codes <gen-errors>` chapter.
643
644EINVAL
645    The struct :ref:`v4l2_queryctrl <v4l2-queryctrl>` ``id`` is
646    invalid. The struct :ref:`v4l2_querymenu <v4l2-querymenu>` ``id``
647    is invalid or ``index`` is out of range (less than ``minimum`` or
648    greater than ``maximum``) or this particular menu item is not
649    supported by the driver.
650
651EACCES
652    An attempt was made to read a write-only control.
653
654.. [#f1]
655   ``V4L2_CTRL_FLAG_DISABLED`` was intended for two purposes: Drivers
656   can skip predefined controls not supported by the hardware (although
657   returning ``EINVAL`` would do as well), or disable predefined and private
658   controls after hardware detection without the trouble of reordering
659   control arrays and indices (``EINVAL`` cannot be used to skip private
660   controls because it would prematurely end the enumeration).
661