Merge branch 'for-3.3/drivers' of git://git.kernel.dk/linux-block
[linux-2.6.git] / Documentation / DocBook / media / v4l / vidioc-g-frequency.xml
1 <refentry id="vidioc-g-frequency">
2   <refmeta>
3     <refentrytitle>ioctl VIDIOC_G_FREQUENCY, VIDIOC_S_FREQUENCY</refentrytitle>
4     &manvol;
5   </refmeta>
6
7   <refnamediv>
8     <refname>VIDIOC_G_FREQUENCY</refname>
9     <refname>VIDIOC_S_FREQUENCY</refname>
10     <refpurpose>Get or set tuner or modulator radio
11 frequency</refpurpose>
12   </refnamediv>
13
14   <refsynopsisdiv>
15     <funcsynopsis>
16       <funcprototype>
17         <funcdef>int <function>ioctl</function></funcdef>
18         <paramdef>int <parameter>fd</parameter></paramdef>
19         <paramdef>int <parameter>request</parameter></paramdef>
20         <paramdef>struct v4l2_frequency
21 *<parameter>argp</parameter></paramdef>
22       </funcprototype>
23     </funcsynopsis>
24     <funcsynopsis>
25       <funcprototype>
26         <funcdef>int <function>ioctl</function></funcdef>
27         <paramdef>int <parameter>fd</parameter></paramdef>
28         <paramdef>int <parameter>request</parameter></paramdef>
29         <paramdef>const struct v4l2_frequency
30 *<parameter>argp</parameter></paramdef>
31       </funcprototype>
32     </funcsynopsis>
33   </refsynopsisdiv>
34
35   <refsect1>
36     <title>Arguments</title>
37
38     <variablelist>
39       <varlistentry>
40         <term><parameter>fd</parameter></term>
41         <listitem>
42           <para>&fd;</para>
43         </listitem>
44       </varlistentry>
45       <varlistentry>
46         <term><parameter>request</parameter></term>
47         <listitem>
48           <para>VIDIOC_G_FREQUENCY, VIDIOC_S_FREQUENCY</para>
49         </listitem>
50       </varlistentry>
51       <varlistentry>
52         <term><parameter>argp</parameter></term>
53         <listitem>
54           <para></para>
55         </listitem>
56       </varlistentry>
57     </variablelist>
58   </refsect1>
59
60   <refsect1>
61     <title>Description</title>
62
63     <para>To get the current tuner or modulator radio frequency
64 applications set the <structfield>tuner</structfield> field of a
65 &v4l2-frequency; to the respective tuner or modulator number (only
66 input devices have tuners, only output devices have modulators), zero
67 out the <structfield>reserved</structfield> array and
68 call the <constant>VIDIOC_G_FREQUENCY</constant> ioctl with a pointer
69 to this structure. The driver stores the current frequency in the
70 <structfield>frequency</structfield> field.</para>
71
72     <para>To change the current tuner or modulator radio frequency
73 applications initialize the <structfield>tuner</structfield>,
74 <structfield>type</structfield> and
75 <structfield>frequency</structfield> fields, and the
76 <structfield>reserved</structfield> array of a &v4l2-frequency; and
77 call the <constant>VIDIOC_S_FREQUENCY</constant> ioctl with a pointer
78 to this structure. When the requested frequency is not possible the
79 driver assumes the closest possible value. However
80 <constant>VIDIOC_S_FREQUENCY</constant> is a write-only ioctl, it does
81 not return the actual new frequency.</para>
82
83     <table pgwide="1" frame="none" id="v4l2-frequency">
84       <title>struct <structname>v4l2_frequency</structname></title>
85       <tgroup cols="3">
86         &cs-str;
87         <tbody valign="top">
88           <row>
89             <entry>__u32</entry>
90             <entry><structfield>tuner</structfield></entry>
91             <entry>The tuner or modulator index number. This is the
92 same value as in the &v4l2-input; <structfield>tuner</structfield>
93 field and the &v4l2-tuner; <structfield>index</structfield> field, or
94 the &v4l2-output; <structfield>modulator</structfield> field and the
95 &v4l2-modulator; <structfield>index</structfield> field.</entry>
96           </row>
97           <row>
98             <entry>&v4l2-tuner-type;</entry>
99             <entry><structfield>type</structfield></entry>
100             <entry>The tuner type. This is the same value as in the
101 &v4l2-tuner; <structfield>type</structfield> field. The field is not
102 applicable to modulators, &ie; ignored by drivers.</entry>
103           </row>
104           <row>
105             <entry>__u32</entry>
106             <entry><structfield>frequency</structfield></entry>
107             <entry>Tuning frequency in units of 62.5 kHz, or if the
108 &v4l2-tuner; or &v4l2-modulator; <structfield>capabilities</structfield> flag
109 <constant>V4L2_TUNER_CAP_LOW</constant> is set, in units of 62.5
110 Hz.</entry>
111           </row>
112           <row>
113             <entry>__u32</entry>
114             <entry><structfield>reserved</structfield>[8]</entry>
115             <entry>Reserved for future extensions. Drivers and
116             applications must set the array to zero.</entry>
117           </row>
118         </tbody>
119       </tgroup>
120     </table>
121   </refsect1>
122
123   <refsect1>
124     &return-value;
125
126     <variablelist>
127       <varlistentry>
128         <term><errorcode>EINVAL</errorcode></term>
129         <listitem>
130           <para>The <structfield>tuner</structfield> index is out of
131 bounds or the value in the <structfield>type</structfield> field is
132 wrong.</para>
133         </listitem>
134       </varlistentry>
135     </variablelist>
136   </refsect1>
137 </refentry>
138
139 <!--
140 Local Variables:
141 mode: sgml
142 sgml-parent-document: "v4l2.sgml"
143 indent-tabs-mode: nil
144 End:
145 -->