Merge branch 'for-3.3/drivers' of git://git.kernel.dk/linux-block
[linux-2.6.git] / Documentation / DocBook / media / v4l / vidioc-g-ctrl.xml
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
54 initialize 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
57 structure. To change the value of a control applications initialize
58 the <structfield>id</structfield> and <structfield>value</structfield>
59 fields 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
63 return an &EINVAL;. When the <structfield>value</structfield> is out
64 of bounds drivers can choose to take the closest valid value or return
65 an &ERANGE;, whatever seems more appropriate. However,
66 <constant>VIDIOC_S_CTRL</constant> is a write-only ioctl, it does not
67 return the actual new value.</para>
68
69     <para>These ioctls work only with user controls. For other
70 control classes the &VIDIOC-G-EXT-CTRLS;, &VIDIOC-S-EXT-CTRLS; or
71 &VIDIOC-TRY-EXT-CTRLS; must be used.</para>
72
73     <table pgwide="1" frame="none" id="v4l2-control">
74       <title>struct <structname>v4l2_control</structname></title>
75       <tgroup cols="3">
76         &cs-str;
77         <tbody valign="top">
78           <row>
79             <entry>__u32</entry>
80             <entry><structfield>id</structfield></entry>
81             <entry>Identifies the control, set by the
82 application.</entry>
83           </row>
84           <row>
85             <entry>__s32</entry>
86             <entry><structfield>value</structfield></entry>
87             <entry>New value or current value.</entry>
88           </row>
89         </tbody>
90       </tgroup>
91     </table>
92   </refsect1>
93
94   <refsect1>
95     &return-value;
96
97     <variablelist>
98       <varlistentry>
99         <term><errorcode>EINVAL</errorcode></term>
100         <listitem>
101           <para>The &v4l2-control; <structfield>id</structfield> is
102 invalid.</para>
103         </listitem>
104       </varlistentry>
105       <varlistentry>
106         <term><errorcode>ERANGE</errorcode></term>
107         <listitem>
108           <para>The &v4l2-control; <structfield>value</structfield>
109 is out of bounds.</para>
110         </listitem>
111       </varlistentry>
112       <varlistentry>
113         <term><errorcode>EBUSY</errorcode></term>
114         <listitem>
115           <para>The control is temporarily not changeable, possibly
116 because another applications took over control of the device function
117 this control belongs to.</para>
118         </listitem>
119       </varlistentry>
120       <varlistentry>
121         <term><errorcode>EACCES</errorcode></term>
122         <listitem>
123           <para>Attempt to set a read-only control or to get a
124           write-only control.</para>
125         </listitem>
126       </varlistentry>
127     </variablelist>
128   </refsect1>
129 </refentry>
130
131 <!--
132 Local Variables:
133 mode: sgml
134 sgml-parent-document: "v4l2.sgml"
135 indent-tabs-mode: nil
136 End:
137 -->