1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later 2 3.. _VIDIOC_G_CTRL: 4 5********************************** 6ioctl VIDIOC_G_CTRL, VIDIOC_S_CTRL 7********************************** 8 9Name 10==== 11 12VIDIOC_G_CTRL - VIDIOC_S_CTRL - Get or set the value of a control 13 14 15Synopsis 16======== 17 18.. c:function:: int ioctl( int fd, VIDIOC_G_CTRL, struct v4l2_control *argp ) 19 :name: VIDIOC_G_CTRL 20 21.. c:function:: int ioctl( int fd, VIDIOC_S_CTRL, struct v4l2_control *argp ) 22 :name: VIDIOC_S_CTRL 23 24 25Arguments 26========= 27 28``fd`` 29 File descriptor returned by :ref:`open() <func-open>`. 30 31``argp`` 32 Pointer to struct :c:type:`v4l2_control`. 33 34 35Description 36=========== 37 38To get the current value of a control applications initialize the ``id`` 39field of a struct :c:type:`v4l2_control` and call the 40:ref:`VIDIOC_G_CTRL <VIDIOC_G_CTRL>` ioctl with a pointer to this structure. To change the 41value of a control applications initialize the ``id`` and ``value`` 42fields of a struct :c:type:`v4l2_control` and call the 43:ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` ioctl. 44 45When the ``id`` is invalid drivers return an ``EINVAL`` error code. When the 46``value`` is out of bounds drivers can choose to take the closest valid 47value or return an ``ERANGE`` error code, whatever seems more appropriate. 48However, :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` is a write-only ioctl, it does not return the 49actual new value. If the ``value`` is inappropriate for the control 50(e.g. if it refers to an unsupported menu index of a menu control), then 51EINVAL error code is returned as well. 52 53These ioctls work only with user controls. For other control classes the 54:ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>`, 55:ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` or 56:ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` must be used. 57 58 59.. c:type:: v4l2_control 60 61.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| 62 63.. flat-table:: struct v4l2_control 64 :header-rows: 0 65 :stub-columns: 0 66 :widths: 1 1 2 67 68 * - __u32 69 - ``id`` 70 - Identifies the control, set by the application. 71 * - __s32 72 - ``value`` 73 - New value or current value. 74 75 76Return Value 77============ 78 79On success 0 is returned, on error -1 and the ``errno`` variable is set 80appropriately. The generic error codes are described at the 81:ref:`Generic Error Codes <gen-errors>` chapter. 82 83EINVAL 84 The struct :c:type:`v4l2_control` ``id`` is invalid 85 or the ``value`` is inappropriate for the given control (i.e. if a 86 menu item is selected that is not supported by the driver according 87 to :ref:`VIDIOC_QUERYMENU <VIDIOC_QUERYCTRL>`). 88 89ERANGE 90 The struct :c:type:`v4l2_control` ``value`` is out of 91 bounds. 92 93EBUSY 94 The control is temporarily not changeable, possibly because another 95 applications took over control of the device function this control 96 belongs to. 97 98EACCES 99 Attempt to set a read-only control or to get a write-only control. 100