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_ENUM_FREQ_BANDS:
11
12****************************
13ioctl VIDIOC_ENUM_FREQ_BANDS
14****************************
15
16Name
17====
18
19VIDIOC_ENUM_FREQ_BANDS - Enumerate supported frequency bands
20
21
22Synopsis
23========
24
25.. c:function:: int ioctl( int fd, VIDIOC_ENUM_FREQ_BANDS, struct v4l2_frequency_band *argp )
26    :name: VIDIOC_ENUM_FREQ_BANDS
27
28
29Arguments
30=========
31
32``fd``
33    File descriptor returned by :ref:`open() <func-open>`.
34
35``argp``
36    Pointer to struct :c:type:`v4l2_frequency_band`.
37
38
39Description
40===========
41
42Enumerates the frequency bands that a tuner or modulator supports. To do
43this applications initialize the ``tuner``, ``type`` and ``index``
44fields, and zero out the ``reserved`` array of a struct
45:c:type:`v4l2_frequency_band` and call the
46:ref:`VIDIOC_ENUM_FREQ_BANDS` ioctl with a pointer to this structure.
47
48This ioctl is supported if the ``V4L2_TUNER_CAP_FREQ_BANDS`` capability
49of the corresponding tuner/modulator is set.
50
51
52.. tabularcolumns:: |p{2.9cm}|p{2.9cm}|p{5.8cm}|p{2.9cm}|p{3.0cm}|
53
54.. c:type:: v4l2_frequency_band
55
56.. flat-table:: struct v4l2_frequency_band
57    :header-rows:  0
58    :stub-columns: 0
59    :widths:       1 1 2 1 1
60
61    * - __u32
62      - ``tuner``
63      - The tuner or modulator index number. This is the same value as in
64	the struct :c:type:`v4l2_input` ``tuner`` field and
65	the struct :c:type:`v4l2_tuner` ``index`` field, or
66	the struct :c:type:`v4l2_output` ``modulator`` field
67	and the struct :c:type:`v4l2_modulator` ``index``
68	field.
69    * - __u32
70      - ``type``
71      - The tuner type. This is the same value as in the struct
72	:c:type:`v4l2_tuner` ``type`` field. The type must be
73	set to ``V4L2_TUNER_RADIO`` for ``/dev/radioX`` device nodes, and
74	to ``V4L2_TUNER_ANALOG_TV`` for all others. Set this field to
75	``V4L2_TUNER_RADIO`` for modulators (currently only radio
76	modulators are supported). See :c:type:`v4l2_tuner_type`
77    * - __u32
78      - ``index``
79      - Identifies the frequency band, set by the application.
80    * - __u32
81      - ``capability``
82      - :cspan:`2` The tuner/modulator capability flags for this
83	frequency band, see :ref:`tuner-capability`. The
84	``V4L2_TUNER_CAP_LOW`` or ``V4L2_TUNER_CAP_1HZ`` capability must
85	be the same for all frequency bands of the selected
86	tuner/modulator. So either all bands have that capability set, or
87	none of them have that capability.
88    * - __u32
89      - ``rangelow``
90      - :cspan:`2` The lowest tunable frequency in units of 62.5 kHz, or
91	if the ``capability`` flag ``V4L2_TUNER_CAP_LOW`` is set, in units
92	of 62.5 Hz, for this frequency band. A 1 Hz unit is used when the
93	``capability`` flag ``V4L2_TUNER_CAP_1HZ`` is set.
94    * - __u32
95      - ``rangehigh``
96      - :cspan:`2` The highest tunable frequency in units of 62.5 kHz,
97	or if the ``capability`` flag ``V4L2_TUNER_CAP_LOW`` is set, in
98	units of 62.5 Hz, for this frequency band. A 1 Hz unit is used
99	when the ``capability`` flag ``V4L2_TUNER_CAP_1HZ`` is set.
100    * - __u32
101      - ``modulation``
102      - :cspan:`2` The supported modulation systems of this frequency
103	band. See :ref:`band-modulation`.
104
105	.. note::
106
107	   Currently only one modulation system per frequency band
108	   is supported. More work will need to be done if multiple
109	   modulation systems are possible. Contact the linux-media
110	   mailing list
111	   (`https://linuxtv.org/lists.php <https://linuxtv.org/lists.php>`__)
112	   if you need such functionality.
113    * - __u32
114      - ``reserved``\ [9]
115      - Reserved for future extensions.
116
117	Applications and drivers must set the array to zero.
118
119
120
121.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
122
123.. _band-modulation:
124
125.. flat-table:: Band Modulation Systems
126    :header-rows:  0
127    :stub-columns: 0
128    :widths:       3 1 4
129
130    * - ``V4L2_BAND_MODULATION_VSB``
131      - 0x02
132      - Vestigial Sideband modulation, used for analog TV.
133    * - ``V4L2_BAND_MODULATION_FM``
134      - 0x04
135      - Frequency Modulation, commonly used for analog radio.
136    * - ``V4L2_BAND_MODULATION_AM``
137      - 0x08
138      - Amplitude Modulation, commonly used for analog radio.
139
140
141Return Value
142============
143
144On success 0 is returned, on error -1 and the ``errno`` variable is set
145appropriately. The generic error codes are described at the
146:ref:`Generic Error Codes <gen-errors>` chapter.
147
148EINVAL
149    The ``tuner`` or ``index`` is out of bounds or the ``type`` field is
150    wrong.
151