Documentation/media/uapi/v4l/vidioc-queryctrl.rst

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