1 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
6 **********************************
7 ioctl VIDIOC_G_CTRL, VIDIOC_S_CTRL
8 **********************************
13 VIDIOC_G_CTRL - VIDIOC_S_CTRL - Get or set the value of a control
18 .. c:macro:: VIDIOC_G_CTRL
20 ``int ioctl(int fd, VIDIOC_G_CTRL, struct v4l2_control *argp)``
22 .. c:macro:: VIDIOC_S_CTRL
24 ``int ioctl(int fd, VIDIOC_S_CTRL, struct v4l2_control *argp)``
30 File descriptor returned by :c:func:`open()`.
33 Pointer to struct :c:type:`v4l2_control`.
38 To get the current value of a control applications initialize the ``id``
39 field 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
41 value of a control applications initialize the ``id`` and ``value``
42 fields of a struct :c:type:`v4l2_control` and call the
43 :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` ioctl.
45 When 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
47 value or return an ``ERANGE`` error code, whatever seems more appropriate.
48 However, :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` is a write-only ioctl, it does not return the
49 actual 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
51 EINVAL error code is returned as well.
53 These 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.
58 .. c:type:: v4l2_control
60 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}|
62 .. flat-table:: struct v4l2_control
69 - Identifies the control, set by the application.
72 - New value or current value.
77 On success 0 is returned, on error -1 and the ``errno`` variable is set
78 appropriately. The generic error codes are described at the
79 :ref:`Generic Error Codes <gen-errors>` chapter.
82 The struct :c:type:`v4l2_control` ``id`` is invalid
83 or the ``value`` is inappropriate for the given control (i.e. if a
84 menu item is selected that is not supported by the driver according
85 to :ref:`VIDIOC_QUERYMENU <VIDIOC_QUERYCTRL>`).
88 The struct :c:type:`v4l2_control` ``value`` is out of
92 The control is temporarily not changeable, possibly because another
93 applications took over control of the device function this control
97 Attempt to set a read-only control or to get a write-only control.
99 Or if there is an attempt to set an inactive control and the driver is
100 not capable of caching the new value until the control is active again.