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