0001 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
0002 .. c:namespace:: V4L
0003
0004 .. _VIDIOC_S_HW_FREQ_SEEK:
0005
0006 ***************************
0007 ioctl VIDIOC_S_HW_FREQ_SEEK
0008 ***************************
0009
0010 Name
0011 ====
0012
0013 VIDIOC_S_HW_FREQ_SEEK - Perform a hardware frequency seek
0014
0015 Synopsis
0016 ========
0017
0018 .. c:macro:: VIDIOC_S_HW_FREQ_SEEK
0019
0020 ``int ioctl(int fd, VIDIOC_S_HW_FREQ_SEEK, struct v4l2_hw_freq_seek *argp)``
0021
0022 Arguments
0023 =========
0024
0025 ``fd``
0026 File descriptor returned by :c:func:`open()`.
0027
0028 ``argp``
0029 Pointer to struct :c:type:`v4l2_hw_freq_seek`.
0030
0031 Description
0032 ===========
0033
0034 Start a hardware frequency seek from the current frequency. To do this
0035 applications initialize the ``tuner``, ``type``, ``seek_upward``,
0036 ``wrap_around``, ``spacing``, ``rangelow`` and ``rangehigh`` fields, and
0037 zero out the ``reserved`` array of a struct
0038 :c:type:`v4l2_hw_freq_seek` and call the
0039 ``VIDIOC_S_HW_FREQ_SEEK`` ioctl with a pointer to this structure.
0040
0041 The ``rangelow`` and ``rangehigh`` fields can be set to a non-zero value
0042 to tell the driver to search a specific band. If the struct
0043 :c:type:`v4l2_tuner` ``capability`` field has the
0044 ``V4L2_TUNER_CAP_HWSEEK_PROG_LIM`` flag set, these values must fall
0045 within one of the bands returned by
0046 :ref:`VIDIOC_ENUM_FREQ_BANDS`. If the
0047 ``V4L2_TUNER_CAP_HWSEEK_PROG_LIM`` flag is not set, then these values
0048 must exactly match those of one of the bands returned by
0049 :ref:`VIDIOC_ENUM_FREQ_BANDS`. If the
0050 current frequency of the tuner does not fall within the selected band it
0051 will be clamped to fit in the band before the seek is started.
0052
0053 If an error is returned, then the original frequency will be restored.
0054
0055 This ioctl is supported if the ``V4L2_CAP_HW_FREQ_SEEK`` capability is
0056 set.
0057
0058 If this ioctl is called from a non-blocking filehandle, then ``EAGAIN``
0059 error code is returned and no seek takes place.
0060
0061 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}|
0062
0063 .. c:type:: v4l2_hw_freq_seek
0064
0065 .. flat-table:: struct v4l2_hw_freq_seek
0066 :header-rows: 0
0067 :stub-columns: 0
0068 :widths: 1 1 2
0069
0070 * - __u32
0071 - ``tuner``
0072 - The tuner index number. This is the same value as in the struct
0073 :c:type:`v4l2_input` ``tuner`` field and the struct
0074 :c:type:`v4l2_tuner` ``index`` field.
0075 * - __u32
0076 - ``type``
0077 - The tuner type. This is the same value as in the struct
0078 :c:type:`v4l2_tuner` ``type`` field. See
0079 :c:type:`v4l2_tuner_type`
0080 * - __u32
0081 - ``seek_upward``
0082 - If non-zero, seek upward from the current frequency, else seek
0083 downward.
0084 * - __u32
0085 - ``wrap_around``
0086 - If non-zero, wrap around when at the end of the frequency range,
0087 else stop seeking. The struct :c:type:`v4l2_tuner`
0088 ``capability`` field will tell you what the hardware supports.
0089 * - __u32
0090 - ``spacing``
0091 - If non-zero, defines the hardware seek resolution in Hz. The
0092 driver selects the nearest value that is supported by the device.
0093 If spacing is zero a reasonable default value is used.
0094 * - __u32
0095 - ``rangelow``
0096 - If non-zero, the lowest tunable frequency of the band to search in
0097 units of 62.5 kHz, or if the struct
0098 :c:type:`v4l2_tuner` ``capability`` field has the
0099 ``V4L2_TUNER_CAP_LOW`` flag set, in units of 62.5 Hz or if the
0100 struct :c:type:`v4l2_tuner` ``capability`` field has
0101 the ``V4L2_TUNER_CAP_1HZ`` flag set, in units of 1 Hz. If
0102 ``rangelow`` is zero a reasonable default value is used.
0103 * - __u32
0104 - ``rangehigh``
0105 - If non-zero, the highest tunable frequency of the band to search
0106 in units of 62.5 kHz, or if the struct
0107 :c:type:`v4l2_tuner` ``capability`` field has the
0108 ``V4L2_TUNER_CAP_LOW`` flag set, in units of 62.5 Hz or if the
0109 struct :c:type:`v4l2_tuner` ``capability`` field has
0110 the ``V4L2_TUNER_CAP_1HZ`` flag set, in units of 1 Hz. If
0111 ``rangehigh`` is zero a reasonable default value is used.
0112 * - __u32
0113 - ``reserved``\ [5]
0114 - Reserved for future extensions. Applications must set the array to
0115 zero.
0116
0117 Return Value
0118 ============
0119
0120 On success 0 is returned, on error -1 and the ``errno`` variable is set
0121 appropriately. The generic error codes are described at the
0122 :ref:`Generic Error Codes <gen-errors>` chapter.
0123
0124 EINVAL
0125 The ``tuner`` index is out of bounds, the ``wrap_around`` value is
0126 not supported or one of the values in the ``type``, ``rangelow`` or
0127 ``rangehigh`` fields is wrong.
0128
0129 EAGAIN
0130 Attempted to call ``VIDIOC_S_HW_FREQ_SEEK`` with the filehandle in
0131 non-blocking mode.
0132
0133 ENODATA
0134 The hardware seek found no channels.
0135
0136 EBUSY
0137 Another hardware seek is already in progress.
