1<refentry id="vidioc-g-ctrl">
2  <refmeta>
3    <refentrytitle>ioctl VIDIOC_G_CTRL, VIDIOC_S_CTRL</refentrytitle>
4    &manvol;
5  </refmeta>
6
7  <refnamediv>
8    <refname>VIDIOC_G_CTRL</refname>
9    <refname>VIDIOC_S_CTRL</refname>
10    <refpurpose>Get or set the value of a control</refpurpose>
11  </refnamediv>
12
13  <refsynopsisdiv>
14    <funcsynopsis>
15      <funcprototype>
16	<funcdef>int <function>ioctl</function></funcdef>
17	<paramdef>int <parameter>fd</parameter></paramdef>
18	<paramdef>int <parameter>request</parameter></paramdef>
19	<paramdef>struct v4l2_control
20*<parameter>argp</parameter></paramdef>
21      </funcprototype>
22    </funcsynopsis>
23  </refsynopsisdiv>
24
25  <refsect1>
26    <title>Arguments</title>
27
28    <variablelist>
29      <varlistentry>
30	<term><parameter>fd</parameter></term>
31	<listitem>
32	  <para>&fd;</para>
33	</listitem>
34      </varlistentry>
35      <varlistentry>
36	<term><parameter>request</parameter></term>
37	<listitem>
38	  <para>VIDIOC_G_CTRL, VIDIOC_S_CTRL</para>
39	</listitem>
40      </varlistentry>
41      <varlistentry>
42	<term><parameter>argp</parameter></term>
43	<listitem>
44	  <para></para>
45	</listitem>
46      </varlistentry>
47    </variablelist>
48  </refsect1>
49
50  <refsect1>
51    <title>Description</title>
52
53    <para>To get the current value of a control applications
54initialize the <structfield>id</structfield> field of a struct
55<structname>v4l2_control</structname> and call the
56<constant>VIDIOC_G_CTRL</constant> ioctl with a pointer to this
57structure. To change the value of a control applications initialize
58the <structfield>id</structfield> and <structfield>value</structfield>
59fields of a struct <structname>v4l2_control</structname> and call the
60<constant>VIDIOC_S_CTRL</constant> ioctl.</para>
61
62    <para>When the <structfield>id</structfield> is invalid drivers
63return an &EINVAL;. When the <structfield>value</structfield> is out
64of bounds drivers can choose to take the closest valid value or return
65an &ERANGE;, whatever seems more appropriate. However,
66<constant>VIDIOC_S_CTRL</constant> is a write-only ioctl, it does not
67return the actual new value. If the <structfield>value</structfield>
68is inappropriate for the control (e.g. if it refers to an unsupported
69menu index of a menu control), then &EINVAL; is returned as well.</para>
70
71    <para>These ioctls work only with user controls. For other
72control classes the &VIDIOC-G-EXT-CTRLS;, &VIDIOC-S-EXT-CTRLS; or
73&VIDIOC-TRY-EXT-CTRLS; must be used.</para>
74
75    <table pgwide="1" frame="none" id="v4l2-control">
76      <title>struct <structname>v4l2_control</structname></title>
77      <tgroup cols="3">
78	&cs-str;
79	<tbody valign="top">
80	  <row>
81	    <entry>__u32</entry>
82	    <entry><structfield>id</structfield></entry>
83	    <entry>Identifies the control, set by the
84application.</entry>
85	  </row>
86	  <row>
87	    <entry>__s32</entry>
88	    <entry><structfield>value</structfield></entry>
89	    <entry>New value or current value.</entry>
90	  </row>
91	</tbody>
92      </tgroup>
93    </table>
94  </refsect1>
95
96  <refsect1>
97    &return-value;
98
99    <variablelist>
100      <varlistentry>
101	<term><errorcode>EINVAL</errorcode></term>
102	<listitem>
103	  <para>The &v4l2-control; <structfield>id</structfield> is
104invalid or the <structfield>value</structfield> is inappropriate for
105the given control (i.e. if a menu item is selected that is not supported
106by the driver according to &VIDIOC-QUERYMENU;).</para>
107	</listitem>
108      </varlistentry>
109      <varlistentry>
110	<term><errorcode>ERANGE</errorcode></term>
111	<listitem>
112	  <para>The &v4l2-control; <structfield>value</structfield>
113is out of bounds.</para>
114	</listitem>
115      </varlistentry>
116      <varlistentry>
117	<term><errorcode>EBUSY</errorcode></term>
118	<listitem>
119	  <para>The control is temporarily not changeable, possibly
120because another applications took over control of the device function
121this control belongs to.</para>
122	</listitem>
123      </varlistentry>
124      <varlistentry>
125	<term><errorcode>EACCES</errorcode></term>
126	<listitem>
127	  <para>Attempt to set a read-only control or to get a
128	  write-only control.</para>
129	</listitem>
130      </varlistentry>
131    </variablelist>
132  </refsect1>
133</refentry>
134