0001 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
0002 .. c:namespace:: V4L
0003
0004 .. _VIDIOC_G_CTRL:
0005
0006 **********************************
0007 ioctl VIDIOC_G_CTRL, VIDIOC_S_CTRL
0008 **********************************
0009
0010 Name
0011 ====
0012
0013 VIDIOC_G_CTRL - VIDIOC_S_CTRL - Get or set the value of a control
0014
0015 Synopsis
0016 ========
0017
0018 .. c:macro:: VIDIOC_G_CTRL
0019
0020 ``int ioctl(int fd, VIDIOC_G_CTRL, struct v4l2_control *argp)``
0021
0022 .. c:macro:: VIDIOC_S_CTRL
0023
0024 ``int ioctl(int fd, VIDIOC_S_CTRL, struct v4l2_control *argp)``
0025
0026 Arguments
0027 =========
0028
0029 ``fd``
0030 File descriptor returned by :c:func:`open()`.
0031
0032 ``argp``
0033 Pointer to struct :c:type:`v4l2_control`.
0034
0035 Description
0036 ===========
0037
0038 To get the current value of a control applications initialize the ``id``
0039 field of a struct :c:type:`v4l2_control` and call the
0040 :ref:`VIDIOC_G_CTRL <VIDIOC_G_CTRL>` ioctl with a pointer to this structure. To change the
0041 value of a control applications initialize the ``id`` and ``value``
0042 fields of a struct :c:type:`v4l2_control` and call the
0043 :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` ioctl.
0044
0045 When the ``id`` is invalid drivers return an ``EINVAL`` error code. When the
0046 ``value`` is out of bounds drivers can choose to take the closest valid
0047 value or return an ``ERANGE`` error code, whatever seems more appropriate.
0048 However, :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` is a write-only ioctl, it does not return the
0049 actual new value. If the ``value`` is inappropriate for the control
0050 (e.g. if it refers to an unsupported menu index of a menu control), then
0051 EINVAL error code is returned as well.
0052
0053 These ioctls work only with user controls. For other control classes the
0054 :ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>`,
0055 :ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` or
0056 :ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` must be used.
0057
0058 .. c:type:: v4l2_control
0059
0060 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}|
0061
0062 .. flat-table:: struct v4l2_control
0063 :header-rows: 0
0064 :stub-columns: 0
0065 :widths: 1 1 2
0066
0067 * - __u32
0068 - ``id``
0069 - Identifies the control, set by the application.
0070 * - __s32
0071 - ``value``
0072 - New value or current value.
0073
0074 Return Value
0075 ============
0076
0077 On success 0 is returned, on error -1 and the ``errno`` variable is set
0078 appropriately. The generic error codes are described at the
0079 :ref:`Generic Error Codes <gen-errors>` chapter.
0080
0081 EINVAL
0082 The struct :c:type:`v4l2_control` ``id`` is invalid
0083 or the ``value`` is inappropriate for the given control (i.e. if a
0084 menu item is selected that is not supported by the driver according
0085 to :ref:`VIDIOC_QUERYMENU <VIDIOC_QUERYCTRL>`).
0086
0087 ERANGE
0088 The struct :c:type:`v4l2_control` ``value`` is out of
0089 bounds.
0090
0091 EBUSY
0092 The control is temporarily not changeable, possibly because another
0093 applications took over control of the device function this control
0094 belongs to.
0095
0096 EACCES
0097 Attempt to set a read-only control or to get a write-only control.
0098
0099 Or if there is an attempt to set an inactive control and the driver is
0100 not capable of caching the new value until the control is active again.
