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