Commit | Line | Data |
---|---|---|
8e080c2e MCC |
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> | |
82f7b59c SA |
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> | |
8e080c2e MCC |
127 | </variablelist> |
128 | </refsect1> | |
129 | </refentry> |