1 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
2 .. c:namespace:: V4L
3
4 .. _VIDIOC_S_HW_FREQ_SEEK:
5
6 ***************************
7 ioctl VIDIOC_S_HW_FREQ_SEEK
8 ***************************
9
10 Name
11 ====
12
13 VIDIOC_S_HW_FREQ_SEEK - Perform a hardware frequency seek
14
15 Synopsis
16 ========
17
18 .. c:macro:: VIDIOC_S_HW_FREQ_SEEK
19
20 ``int ioctl(int fd, VIDIOC_S_HW_FREQ_SEEK, struct v4l2_hw_freq_seek *argp)``
21
22 Arguments
23 =========
24
25 ``fd``
26 File descriptor returned by :c:func:`open()`.
27
28 ``argp``
29 Pointer to struct :c:type:`v4l2_hw_freq_seek`.
30
31 Description
32 ===========
33
34 Start a hardware frequency seek from the current frequency. To do this
35 applications initialize the ``tuner``, ``type``, ``seek_upward``,
36 ``wrap_around``, ``spacing``, ``rangelow`` and ``rangehigh`` fields, and
37 zero out the ``reserved`` array of a struct
38 :c:type:`v4l2_hw_freq_seek` and call the
39 ``VIDIOC_S_HW_FREQ_SEEK`` ioctl with a pointer to this structure.
40
41 The ``rangelow`` and ``rangehigh`` fields can be set to a non-zero value
42 to tell the driver to search a specific band. If the struct
43 :c:type:`v4l2_tuner` ``capability`` field has the
44 ``V4L2_TUNER_CAP_HWSEEK_PROG_LIM`` flag set, these values must fall
45 within one of the bands returned by
46 :ref:`VIDIOC_ENUM_FREQ_BANDS`. If the
47 ``V4L2_TUNER_CAP_HWSEEK_PROG_LIM`` flag is not set, then these values
48 must exactly match those of one of the bands returned by
49 :ref:`VIDIOC_ENUM_FREQ_BANDS`. If the
50 current frequency of the tuner does not fall within the selected band it
51 will be clamped to fit in the band before the seek is started.
52
53 If an error is returned, then the original frequency will be restored.
54
55 This ioctl is supported if the ``V4L2_CAP_HW_FREQ_SEEK`` capability is
56 set.
57
58 If this ioctl is called from a non-blocking filehandle, then ``EAGAIN``
59 error code is returned and no seek takes place.
60
61 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}|
62
63 .. c:type:: v4l2_hw_freq_seek
64
65 .. flat-table:: struct v4l2_hw_freq_seek
66 :header-rows: 0
67 :stub-columns: 0
68 :widths: 1 1 2
69
70 * - __u32
71 - ``tuner``
72 - The tuner index number. This is the same value as in the struct
73 :c:type:`v4l2_input` ``tuner`` field and the struct
74 :c:type:`v4l2_tuner` ``index`` field.
75 * - __u32
76 - ``type``
77 - The tuner type. This is the same value as in the struct
78 :c:type:`v4l2_tuner` ``type`` field. See
79 :c:type:`v4l2_tuner_type`
80 * - __u32
81 - ``seek_upward``
82 - If non-zero, seek upward from the current frequency, else seek
83 downward.
84 * - __u32
85 - ``wrap_around``
86 - If non-zero, wrap around when at the end of the frequency range,
87 else stop seeking. The struct :c:type:`v4l2_tuner`
88 ``capability`` field will tell you what the hardware supports.
89 * - __u32
90 - ``spacing``
91 - If non-zero, defines the hardware seek resolution in Hz. The
92 driver selects the nearest value that is supported by the device.
93 If spacing is zero a reasonable default value is used.
94 * - __u32
95 - ``rangelow``
96 - If non-zero, the lowest tunable frequency of the band to search in
97 units of 62.5 kHz, or if the struct
98 :c:type:`v4l2_tuner` ``capability`` field has the
99 ``V4L2_TUNER_CAP_LOW`` flag set, in units of 62.5 Hz or if the
100 struct :c:type:`v4l2_tuner` ``capability`` field has
101 the ``V4L2_TUNER_CAP_1HZ`` flag set, in units of 1 Hz. If
102 ``rangelow`` is zero a reasonable default value is used.
103 * - __u32
104 - ``rangehigh``
105 - If non-zero, the highest tunable frequency of the band to search
106 in units of 62.5 kHz, or if the struct
107 :c:type:`v4l2_tuner` ``capability`` field has the
108 ``V4L2_TUNER_CAP_LOW`` flag set, in units of 62.5 Hz or if the
109 struct :c:type:`v4l2_tuner` ``capability`` field has
110 the ``V4L2_TUNER_CAP_1HZ`` flag set, in units of 1 Hz. If
111 ``rangehigh`` is zero a reasonable default value is used.
112 * - __u32
113 - ``reserved``\ [5]
114 - Reserved for future extensions. Applications must set the array to
115 zero.
116
117 Return Value
118 ============
119
120 On success 0 is returned, on error -1 and the ``errno`` variable is set
121 appropriately. The generic error codes are described at the
122 :ref:`Generic Error Codes <gen-errors>` chapter.
123
124 EINVAL
125 The ``tuner`` index is out of bounds, the ``wrap_around`` value is
126 not supported or one of the values in the ``type``, ``rangelow`` or
127 ``rangehigh`` fields is wrong.
128
129 EAGAIN
130 Attempted to call ``VIDIOC_S_HW_FREQ_SEEK`` with the filehandle in
131 non-blocking mode.
132
133 ENODATA
134 The hardware seek found no channels.
135
136 EBUSY
137 Another hardware seek is already in progress.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.