summaryrefslogtreecommitdiff
path: root/Documentation/DocBook/v4l/vidioc-g-ctrl.xml
blob: 8b5e6ff7f3df7a6340c6f01486ba9de3b731fc2f (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
<refentry id="vidioc-g-ctrl">
  <refmeta>
    <refentrytitle>ioctl VIDIOC_G_CTRL, VIDIOC_S_CTRL</refentrytitle>
    &manvol;
  </refmeta>

  <refnamediv>
    <refname>VIDIOC_G_CTRL</refname>
    <refname>VIDIOC_S_CTRL</refname>
    <refpurpose>Get or set the value of a control</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <funcsynopsis>
      <funcprototype>
	<funcdef>int <function>ioctl</function></funcdef>
	<paramdef>int <parameter>fd</parameter></paramdef>
	<paramdef>int <parameter>request</parameter></paramdef>
	<paramdef>struct v4l2_control
*<parameter>argp</parameter></paramdef>
      </funcprototype>
    </funcsynopsis>
  </refsynopsisdiv>

  <refsect1>
    <title>Arguments</title>

    <variablelist>
      <varlistentry>
	<term><parameter>fd</parameter></term>
	<listitem>
	  <para>&fd;</para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><parameter>request</parameter></term>
	<listitem>
	  <para>VIDIOC_G_CTRL, VIDIOC_S_CTRL</para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><parameter>argp</parameter></term>
	<listitem>
	  <para></para>
	</listitem>
      </varlistentry>
    </variablelist>
  </refsect1>

  <refsect1>
    <title>Description</title>

    <para>To get the current value of a control applications
initialize the <structfield>id</structfield> field of a struct
<structname>v4l2_control</structname> and call the
<constant>VIDIOC_G_CTRL</constant> ioctl with a pointer to this
structure. To change the value of a control applications initialize
the <structfield>id</structfield> and <structfield>value</structfield>
fields of a struct <structname>v4l2_control</structname> and call the
<constant>VIDIOC_S_CTRL</constant> ioctl.</para>

    <para>When the <structfield>id</structfield> is invalid drivers
return an &EINVAL;. When the <structfield>value</structfield> is out
of bounds drivers can choose to take the closest valid value or return
an &ERANGE;, whatever seems more appropriate. However,
<constant>VIDIOC_S_CTRL</constant> is a write-only ioctl, it does not
return the actual new value.</para>

    <para>These ioctls work only with user controls. For other
control classes the &VIDIOC-G-EXT-CTRLS;, &VIDIOC-S-EXT-CTRLS; or
&VIDIOC-TRY-EXT-CTRLS; must be used.</para>

    <table pgwide="1" frame="none" id="v4l2-control">
      <title>struct <structname>v4l2_control</structname></title>
      <tgroup cols="3">
	&cs-str;
	<tbody valign="top">
	  <row>
	    <entry>__u32</entry>
	    <entry><structfield>id</structfield></entry>
	    <entry>Identifies the control, set by the
application.</entry>
	  </row>
	  <row>
	    <entry>__s32</entry>
	    <entry><structfield>value</structfield></entry>
	    <entry>New value or current value.</entry>
	  </row>
	</tbody>
      </tgroup>
    </table>
  </refsect1>

  <refsect1>
    &return-value;

    <variablelist>
      <varlistentry>
	<term><errorcode>EINVAL</errorcode></term>
	<listitem>
	  <para>The &v4l2-control; <structfield>id</structfield> is
invalid.</para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><errorcode>ERANGE</errorcode></term>
	<listitem>
	  <para>The &v4l2-control; <structfield>value</structfield>
is out of bounds.</para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><errorcode>EBUSY</errorcode></term>
	<listitem>
	  <para>The control is temporarily not changeable, possibly
because another applications took over control of the device function
this control belongs to.</para>
	</listitem>
      </varlistentry>
    </variablelist>
  </refsect1>
</refentry>

<!--
Local Variables:
mode: sgml
sgml-parent-document: "v4l2.sgml"
indent-tabs-mode: nil
End:
-->