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