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_QUERYCTRL: 11 12******************************************************************* 13ioctls VIDIOC_QUERYCTRL, VIDIOC_QUERY_EXT_CTRL and VIDIOC_QUERYMENU 14******************************************************************* 15 16Name 17==== 18 19VIDIOC_QUERYCTRL - VIDIOC_QUERY_EXT_CTRL - VIDIOC_QUERYMENU - Enumerate controls and menu control items 20 21 22Synopsis 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 35Arguments 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 46Description 47=========== 48 49To query the attributes of a control applications set the ``id`` field 50of a struct :ref:`v4l2_queryctrl <v4l2-queryctrl>` and call the 51``VIDIOC_QUERYCTRL`` ioctl with a pointer to this structure. The driver 52fills the rest of the structure or returns an ``EINVAL`` error code when the 53``id`` is invalid. 54 55It is possible to enumerate controls by calling ``VIDIOC_QUERYCTRL`` 56with successive ``id`` values starting from ``V4L2_CID_BASE`` up to and 57exclusive ``V4L2_CID_LASTP1``. Drivers may return ``EINVAL`` if a control in 58this range is not supported. Further applications can enumerate private 59controls, which are not defined in this specification, by starting at 60``V4L2_CID_PRIVATE_BASE`` and incrementing ``id`` until the driver 61returns ``EINVAL``. 62 63In both cases, when the driver sets the ``V4L2_CTRL_FLAG_DISABLED`` flag 64in the ``flags`` field this control is permanently disabled and should 65be ignored by the application. [#f1]_ 66 67When the application ORs ``id`` with ``V4L2_CTRL_FLAG_NEXT_CTRL`` the 68driver returns the next supported non-compound control, or ``EINVAL`` if 69there is none. In addition, the ``V4L2_CTRL_FLAG_NEXT_COMPOUND`` flag 70can be specified to enumerate all compound controls (i.e. controls with 71type ≥ ``V4L2_CTRL_COMPOUND_TYPES`` and/or array control, in other words 72controls that contain more than one value). Specify both 73``V4L2_CTRL_FLAG_NEXT_CTRL`` and ``V4L2_CTRL_FLAG_NEXT_COMPOUND`` in 74order to enumerate all controls, compound or not. Drivers which do not 75support these flags yet always return ``EINVAL``. 76 77The ``VIDIOC_QUERY_EXT_CTRL`` ioctl was introduced in order to better 78support controls that can use compound types, and to expose additional 79control 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 84as well. 85 86Additional information is required for menu controls: the names of the 87menu items. To query them applications set the ``id`` and ``index`` 88fields of struct :ref:`v4l2_querymenu <v4l2-querymenu>` and call the 89``VIDIOC_QUERYMENU`` ioctl with a pointer to this structure. The driver 90fills 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``, 94inclusive. 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 103See 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 294 295 * - __u32 296 - ``id`` 297 - Identifies the control, set by the application from the respective 298 struct :ref:`v4l2_queryctrl <v4l2-queryctrl>` ``id``. 299 * - __u32 300 - ``index`` 301 - Index of the menu item, starting at zero, set by the application. 302 * - union { 303 - (anonymous) 304 * - __u8 305 - ``name``\ [32] 306 - Name of the menu item, a NUL-terminated ASCII string. This 307 information is intended for the user. This field is valid for 308 ``V4L2_CTRL_TYPE_MENU`` type controls. 309 * - __s64 310 - ``value`` 311 - Value of the integer menu item. This field is valid for 312 ``V4L2_CTRL_TYPE_INTEGER_MENU`` type controls. 313 * - } 314 - 315 * - __u32 316 - ``reserved`` 317 - Reserved for future extensions. Drivers must set the array to 318 zero. 319 320 321 322.. tabularcolumns:: |p{5.8cm}|p{1.4cm}|p{1.0cm}|p{1.4cm}|p{6.9cm}| 323 324.. c:type:: v4l2_ctrl_type 325 326.. cssclass:: longtable 327 328.. flat-table:: enum v4l2_ctrl_type 329 :header-rows: 1 330 :stub-columns: 0 331 :widths: 30 5 5 5 55 332 333 * - Type 334 - ``minimum`` 335 - ``step`` 336 - ``maximum`` 337 - Description 338 * - ``V4L2_CTRL_TYPE_INTEGER`` 339 - any 340 - any 341 - any 342 - An integer-valued control ranging from minimum to maximum 343 inclusive. The step value indicates the increment between values. 344 * - ``V4L2_CTRL_TYPE_BOOLEAN`` 345 - 0 346 - 1 347 - 1 348 - A boolean-valued control. Zero corresponds to "disabled", and one 349 means "enabled". 350 * - ``V4L2_CTRL_TYPE_MENU`` 351 - ≥ 0 352 - 1 353 - N-1 354 - The control has a menu of N choices. The names of the menu items 355 can be enumerated with the ``VIDIOC_QUERYMENU`` ioctl. 356 * - ``V4L2_CTRL_TYPE_INTEGER_MENU`` 357 - ≥ 0 358 - 1 359 - N-1 360 - The control has a menu of N choices. The values of the menu items 361 can be enumerated with the ``VIDIOC_QUERYMENU`` ioctl. This is 362 similar to ``V4L2_CTRL_TYPE_MENU`` except that instead of strings, 363 the menu items are signed 64-bit integers. 364 * - ``V4L2_CTRL_TYPE_BITMASK`` 365 - 0 366 - n/a 367 - any 368 - A bitmask field. The maximum value is the set of bits that can be 369 used, all other bits are to be 0. The maximum value is interpreted 370 as a __u32, allowing the use of bit 31 in the bitmask. 371 * - ``V4L2_CTRL_TYPE_BUTTON`` 372 - 0 373 - 0 374 - 0 375 - A control which performs an action when set. Drivers must ignore 376 the value passed with ``VIDIOC_S_CTRL`` and return an ``EACCES`` error 377 code on a ``VIDIOC_G_CTRL`` attempt. 378 * - ``V4L2_CTRL_TYPE_INTEGER64`` 379 - any 380 - any 381 - any 382 - A 64-bit integer valued control. Minimum, maximum and step size 383 cannot be queried using ``VIDIOC_QUERYCTRL``. Only 384 ``VIDIOC_QUERY_EXT_CTRL`` can retrieve the 64-bit min/max/step 385 values, they should be interpreted as n/a when using 386 ``VIDIOC_QUERYCTRL``. 387 * - ``V4L2_CTRL_TYPE_STRING`` 388 - ≥ 0 389 - ≥ 1 390 - ≥ 0 391 - The minimum and maximum string lengths. The step size means that 392 the string must be (minimum + N * step) characters long for N ≥ 0. 393 These lengths do not include the terminating zero, so in order to 394 pass a string of length 8 to 395 :ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` you need to 396 set the ``size`` field of struct 397 :c:type:`v4l2_ext_control` to 9. For 398 :ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` you can set 399 the ``size`` field to ``maximum`` + 1. Which character encoding is 400 used will depend on the string control itself and should be part 401 of the control documentation. 402 * - ``V4L2_CTRL_TYPE_CTRL_CLASS`` 403 - n/a 404 - n/a 405 - n/a 406 - This is not a control. When ``VIDIOC_QUERYCTRL`` is called with a 407 control ID equal to a control class code (see :ref:`ctrl-class`) 408 + 1, the ioctl returns the name of the control class and this 409 control type. Older drivers which do not support this feature 410 return an ``EINVAL`` error code. 411 * - ``V4L2_CTRL_TYPE_U8`` 412 - any 413 - any 414 - any 415 - An unsigned 8-bit valued control ranging from minimum to maximum 416 inclusive. The step value indicates the increment between values. 417 * - ``V4L2_CTRL_TYPE_U16`` 418 - any 419 - any 420 - any 421 - An unsigned 16-bit valued control ranging from minimum to maximum 422 inclusive. The step value indicates the increment between values. 423 * - ``V4L2_CTRL_TYPE_U32`` 424 - any 425 - any 426 - any 427 - An unsigned 32-bit valued control ranging from minimum to maximum 428 inclusive. The step value indicates the increment between values. 429 * - ``V4L2_CTRL_TYPE_MPEG2_SLICE_PARAMS`` 430 - n/a 431 - n/a 432 - n/a 433 - A struct :c:type:`v4l2_ctrl_mpeg2_slice_params`, containing MPEG-2 434 slice parameters for stateless video decoders. 435 * - ``V4L2_CTRL_TYPE_MPEG2_QUANTIZATION`` 436 - n/a 437 - n/a 438 - n/a 439 - A struct :c:type:`v4l2_ctrl_mpeg2_quantization`, containing MPEG-2 440 quantization matrices for stateless video decoders. 441 * - ``V4L2_CTRL_TYPE_AREA`` 442 - n/a 443 - n/a 444 - n/a 445 - A struct :c:type:`v4l2_area`, containing the width and the height 446 of a rectangular area. Units depend on the use case. 447 * - ``V4L2_CTRL_TYPE_H264_SPS`` 448 - n/a 449 - n/a 450 - n/a 451 - A struct :c:type:`v4l2_ctrl_h264_sps`, containing H264 452 sequence parameters for stateless video decoders. 453 * - ``V4L2_CTRL_TYPE_H264_PPS`` 454 - n/a 455 - n/a 456 - n/a 457 - A struct :c:type:`v4l2_ctrl_h264_pps`, containing H264 458 picture parameters for stateless video decoders. 459 * - ``V4L2_CTRL_TYPE_H264_SCALING_MATRIX`` 460 - n/a 461 - n/a 462 - n/a 463 - A struct :c:type:`v4l2_ctrl_h264_scaling_matrix`, containing H264 464 scaling matrices for stateless video decoders. 465 * - ``V4L2_CTRL_TYPE_H264_SLICE_PARAMS`` 466 - n/a 467 - n/a 468 - n/a 469 - A struct :c:type:`v4l2_ctrl_h264_slice_params`, containing H264 470 slice parameters for stateless video decoders. 471 * - ``V4L2_CTRL_TYPE_H264_DECODE_PARAMS`` 472 - n/a 473 - n/a 474 - n/a 475 - A struct :c:type:`v4l2_ctrl_h264_decode_params`, containing H264 476 decode parameters for stateless video decoders. 477 * - ``V4L2_CTRL_TYPE_HEVC_SPS`` 478 - n/a 479 - n/a 480 - n/a 481 - A struct :c:type:`v4l2_ctrl_hevc_sps`, containing HEVC Sequence 482 Parameter Set for stateless video decoders. 483 * - ``V4L2_CTRL_TYPE_HEVC_PPS`` 484 - n/a 485 - n/a 486 - n/a 487 - A struct :c:type:`v4l2_ctrl_hevc_pps`, containing HEVC Picture 488 Parameter Set for stateless video decoders. 489 * - ``V4L2_CTRL_TYPE_HEVC_SLICE_PARAMS`` 490 - n/a 491 - n/a 492 - n/a 493 - A struct :c:type:`v4l2_ctrl_hevc_slice_params`, containing HEVC 494 slice parameters for stateless video decoders. 495 496.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| 497 498.. _control-flags: 499 500.. cssclass:: longtable 501 502.. flat-table:: Control Flags 503 :header-rows: 0 504 :stub-columns: 0 505 :widths: 3 1 4 506 507 * - ``V4L2_CTRL_FLAG_DISABLED`` 508 - 0x0001 509 - This control is permanently disabled and should be ignored by the 510 application. Any attempt to change the control will result in an 511 ``EINVAL`` error code. 512 * - ``V4L2_CTRL_FLAG_GRABBED`` 513 - 0x0002 514 - This control is temporarily unchangeable, for example because 515 another application took over control of the respective resource. 516 Such controls may be displayed specially in a user interface. 517 Attempts to change the control may result in an ``EBUSY`` error code. 518 * - ``V4L2_CTRL_FLAG_READ_ONLY`` 519 - 0x0004 520 - This control is permanently readable only. Any attempt to change 521 the control will result in an ``EINVAL`` error code. 522 * - ``V4L2_CTRL_FLAG_UPDATE`` 523 - 0x0008 524 - A hint that changing this control may affect the value of other 525 controls within the same control class. Applications should update 526 their user interface accordingly. 527 * - ``V4L2_CTRL_FLAG_INACTIVE`` 528 - 0x0010 529 - This control is not applicable to the current configuration and 530 should be displayed accordingly in a user interface. For example 531 the flag may be set on a MPEG audio level 2 bitrate control when 532 MPEG audio encoding level 1 was selected with another control. 533 * - ``V4L2_CTRL_FLAG_SLIDER`` 534 - 0x0020 535 - A hint that this control is best represented as a slider-like 536 element in a user interface. 537 * - ``V4L2_CTRL_FLAG_WRITE_ONLY`` 538 - 0x0040 539 - This control is permanently writable only. Any attempt to read the 540 control will result in an ``EACCES`` error code error code. This flag 541 is typically present for relative controls or action controls 542 where writing a value will cause the device to carry out a given 543 action (e. g. motor control) but no meaningful value can be 544 returned. 545 * - ``V4L2_CTRL_FLAG_VOLATILE`` 546 - 0x0080 547 - This control is volatile, which means that the value of the 548 control changes continuously. A typical example would be the 549 current gain value if the device is in auto-gain mode. In such a 550 case the hardware calculates the gain value based on the lighting 551 conditions which can change over time. 552 553 .. note:: 554 555 Setting a new value for a volatile control will be ignored 556 unless 557 :ref:`V4L2_CTRL_FLAG_EXECUTE_ON_WRITE <FLAG_EXECUTE_ON_WRITE>` 558 is also set. 559 Setting a new value for a volatile control will *never* trigger a 560 :ref:`V4L2_EVENT_CTRL_CH_VALUE <ctrl-changes-flags>` event. 561 * - ``V4L2_CTRL_FLAG_HAS_PAYLOAD`` 562 - 0x0100 563 - This control has a pointer type, so its value has to be accessed 564 using one of the pointer fields of struct 565 :c:type:`v4l2_ext_control`. This flag is set 566 for controls that are an array, string, or have a compound type. 567 In all cases you have to set a pointer to memory containing the 568 payload of the control. 569 * .. _FLAG_EXECUTE_ON_WRITE: 570 571 - ``V4L2_CTRL_FLAG_EXECUTE_ON_WRITE`` 572 - 0x0200 573 - The value provided to the control will be propagated to the driver 574 even if it remains constant. This is required when the control 575 represents an action on the hardware. For example: clearing an 576 error flag or triggering the flash. All the controls of the type 577 ``V4L2_CTRL_TYPE_BUTTON`` have this flag set. 578 * .. _FLAG_MODIFY_LAYOUT: 579 580 - ``V4L2_CTRL_FLAG_MODIFY_LAYOUT`` 581 - 0x0400 582 - Changing this control value may modify the layout of the 583 buffer (for video devices) or the media bus format (for sub-devices). 584 585 A typical example would be the ``V4L2_CID_ROTATE`` control. 586 587 Note that typically controls with this flag will also set the 588 ``V4L2_CTRL_FLAG_GRABBED`` flag when buffers are allocated or 589 streaming is in progress since most drivers do not support changing 590 the format in that case. 591 592 593Return Value 594============ 595 596On success 0 is returned, on error -1 and the ``errno`` variable is set 597appropriately. The generic error codes are described at the 598:ref:`Generic Error Codes <gen-errors>` chapter. 599 600EINVAL 601 The struct :ref:`v4l2_queryctrl <v4l2-queryctrl>` ``id`` is 602 invalid. The struct :ref:`v4l2_querymenu <v4l2-querymenu>` ``id`` 603 is invalid or ``index`` is out of range (less than ``minimum`` or 604 greater than ``maximum``) or this particular menu item is not 605 supported by the driver. 606 607EACCES 608 An attempt was made to read a write-only control. 609 610.. [#f1] 611 ``V4L2_CTRL_FLAG_DISABLED`` was intended for two purposes: Drivers 612 can skip predefined controls not supported by the hardware (although 613 returning ``EINVAL`` would do as well), or disable predefined and private 614 controls after hardware detection without the trouble of reordering 615 control arrays and indices (``EINVAL`` cannot be used to skip private 616 controls because it would prematurely end the enumeration). 617