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 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. The field is not applicable to modulators, &ie; ignored
 105 by drivers.</entry>
 106           </row>
 107           <row>
 108             <entry>__u32</entry>
 109             <entry><structfield>frequency</structfield></entry>
 110             <entry>Tuning frequency in units of 62.5 kHz, or if the
 111 &v4l2-tuner; or &v4l2-modulator; <structfield>capabilities</structfield> flag
 112 <constant>V4L2_TUNER_CAP_LOW</constant> is set, in units of 62.5
 113 Hz.</entry>
 114           </row>
 115           <row>
 116             <entry>__u32</entry>
 117             <entry><structfield>reserved</structfield>[8]</entry>
 118             <entry>Reserved for future extensions. Drivers and
 119             applications must set the array to zero.</entry>
 120           </row>
 121         </tbody>
 122       </tgroup>
 123     </table>
 124   </refsect1>
 125
 126   <refsect1>
 127     &return-value;
 128
 129     <variablelist>
 130       <varlistentry>
 131         <term><errorcode>EINVAL</errorcode></term>
 132         <listitem>
 133           <para>The <structfield>tuner</structfield> index is out of
 134 bounds or the value in the <structfield>type</structfield> field is
 135 wrong.</para>
 136         </listitem>
 137       </varlistentry>
 138     </variablelist>
 139   </refsect1>
 140 </refentry>