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>__u32</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 type must be set
 102 to <constant>V4L2_TUNER_RADIO</constant> for <filename>/dev/radioX</filename>
 103 device nodes, and to <constant>V4L2_TUNER_ANALOG_TV</constant>
 104 for all others. Set this field to <constant>V4L2_TUNER_RADIO</constant> for
 105 modulators (currently only radio modulators are supported).
 106 See <xref linkend="v4l2-tuner-type" /></entry>
 107           </row>
 108           <row>
 109             <entry>__u32</entry>
 110             <entry><structfield>frequency</structfield></entry>
 111             <entry>Tuning frequency in units of 62.5 kHz, or if the
 112 &v4l2-tuner; or &v4l2-modulator; <structfield>capability</structfield> flag
 113 <constant>V4L2_TUNER_CAP_LOW</constant> is set, in units of 62.5
 114 Hz. A 1 Hz unit is used when the <structfield>capability</structfield> flag
 115 <constant>V4L2_TUNER_CAP_1HZ</constant> is set.</entry>
 116           </row>
 117           <row>
 118             <entry>__u32</entry>
 119             <entry><structfield>reserved</structfield>[8]</entry>
 120             <entry>Reserved for future extensions. Drivers and
 121             applications must set the array to zero.</entry>
 122           </row>
 123         </tbody>
 124       </tgroup>
 125     </table>
 126   </refsect1>
 127
 128   <refsect1>
 129     &return-value;
 130
 131     <variablelist>
 132       <varlistentry>
 133         <term><errorcode>EINVAL</errorcode></term>
 134         <listitem>
 135           <para>The <structfield>tuner</structfield> index is out of
 136 bounds or the value in the <structfield>type</structfield> field is
 137 wrong.</para>
 138         </listitem>
 139       </varlistentry>
 140       <varlistentry>
 141         <term><errorcode>EBUSY</errorcode></term>
 142         <listitem>
 143           <para>A hardware seek is in progress.</para>
 144         </listitem>
 145       </varlistentry>
 146     </variablelist>
 147   </refsect1>
 148 </refentry>