1.. Permission is granted to copy, distribute and/or modify this
2.. document under the terms of the GNU Free Documentation License,
3.. Version 1.1 or any later version published by the Free Software
4.. Foundation, with no Invariant Sections, no Front-Cover Texts
5.. and no Back-Cover Texts. A copy of the license is included at
6.. Documentation/userspace-api/media/fdl-appendix.rst.
7..
8.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
9
10.. _VIDIOC_G_FREQUENCY:
11
12********************************************
13ioctl VIDIOC_G_FREQUENCY, VIDIOC_S_FREQUENCY
14********************************************
15
16Name
17====
18
19VIDIOC_G_FREQUENCY - VIDIOC_S_FREQUENCY - Get or set tuner or modulator radio frequency
20
21
22Synopsis
23========
24
25.. c:function:: int ioctl( int fd, VIDIOC_G_FREQUENCY, struct v4l2_frequency *argp )
26    :name: VIDIOC_G_FREQUENCY
27
28.. c:function:: int ioctl( int fd, VIDIOC_S_FREQUENCY, const struct v4l2_frequency *argp )
29    :name: VIDIOC_S_FREQUENCY
30
31
32Arguments
33=========
34
35``fd``
36    File descriptor returned by :ref:`open() <func-open>`.
37
38``argp``
39    Pointer to struct :c:type:`v4l2_frequency`.
40
41
42Description
43===========
44
45To get the current tuner or modulator radio frequency applications set
46the ``tuner`` field of a struct
47:c:type:`v4l2_frequency` to the respective tuner or
48modulator number (only input devices have tuners, only output devices
49have modulators), zero out the ``reserved`` array and call the
50:ref:`VIDIOC_G_FREQUENCY <VIDIOC_G_FREQUENCY>` ioctl with a pointer to this structure. The
51driver stores the current frequency in the ``frequency`` field.
52
53To change the current tuner or modulator radio frequency applications
54initialize the ``tuner``, ``type`` and ``frequency`` fields, and the
55``reserved`` array of a struct :c:type:`v4l2_frequency`
56and call the :ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENCY>` ioctl with a pointer to this
57structure. When the requested frequency is not possible the driver
58assumes the closest possible value. However :ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENCY>` is a
59write-only ioctl, it does not return the actual new frequency.
60
61
62.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
63
64.. c:type:: v4l2_frequency
65
66.. flat-table:: struct v4l2_frequency
67    :header-rows:  0
68    :stub-columns: 0
69    :widths:       1 1 2
70
71    * - __u32
72      - ``tuner``
73      - The tuner or modulator index number. This is the same value as in
74	the struct :c:type:`v4l2_input` ``tuner`` field and
75	the struct :c:type:`v4l2_tuner` ``index`` field, or
76	the struct :c:type:`v4l2_output` ``modulator`` field
77	and the struct :c:type:`v4l2_modulator` ``index``
78	field.
79    * - __u32
80      - ``type``
81      - The tuner type. This is the same value as in the struct
82	:c:type:`v4l2_tuner` ``type`` field. The type must be
83	set to ``V4L2_TUNER_RADIO`` for ``/dev/radioX`` device nodes, and
84	to ``V4L2_TUNER_ANALOG_TV`` for all others. Set this field to
85	``V4L2_TUNER_RADIO`` for modulators (currently only radio
86	modulators are supported). See :c:type:`v4l2_tuner_type`
87    * - __u32
88      - ``frequency``
89      - Tuning frequency in units of 62.5 kHz, or if the struct
90	:c:type:`v4l2_tuner` or struct
91	:c:type:`v4l2_modulator` ``capability`` flag
92	``V4L2_TUNER_CAP_LOW`` is set, in units of 62.5 Hz. A 1 Hz unit is
93	used when the ``capability`` flag ``V4L2_TUNER_CAP_1HZ`` is set.
94    * - __u32
95      - ``reserved``\ [8]
96      - Reserved for future extensions. Drivers and applications must set
97	the array to zero.
98
99
100Return Value
101============
102
103On success 0 is returned, on error -1 and the ``errno`` variable is set
104appropriately. The generic error codes are described at the
105:ref:`Generic Error Codes <gen-errors>` chapter.
106
107EINVAL
108    The ``tuner`` index is out of bounds or the value in the ``type``
109    field is wrong.
110
111EBUSY
112    A hardware seek is in progress.
113