1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later 2.. c:namespace:: V4L 3 4.. _VIDIOC_S_HW_FREQ_SEEK: 5 6*************************** 7ioctl VIDIOC_S_HW_FREQ_SEEK 8*************************** 9 10Name 11==== 12 13VIDIOC_S_HW_FREQ_SEEK - Perform a hardware frequency seek 14 15Synopsis 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 22Arguments 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 31Description 32=========== 33 34Start a hardware frequency seek from the current frequency. To do this 35applications initialize the ``tuner``, ``type``, ``seek_upward``, 36``wrap_around``, ``spacing``, ``rangelow`` and ``rangehigh`` fields, and 37zero 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 41The ``rangelow`` and ``rangehigh`` fields can be set to a non-zero value 42to 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 45within 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 48must exactly match those of one of the bands returned by 49:ref:`VIDIOC_ENUM_FREQ_BANDS`. If the 50current frequency of the tuner does not fall within the selected band it 51will be clamped to fit in the band before the seek is started. 52 53If an error is returned, then the original frequency will be restored. 54 55This ioctl is supported if the ``V4L2_CAP_HW_FREQ_SEEK`` capability is 56set. 57 58If this ioctl is called from a non-blocking filehandle, then ``EAGAIN`` 59error 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 117Return Value 118============ 119 120On success 0 is returned, on error -1 and the ``errno`` variable is set 121appropriately. The generic error codes are described at the 122:ref:`Generic Error Codes <gen-errors>` chapter. 123 124EINVAL 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 129EAGAIN 130 Attempted to call ``VIDIOC_S_HW_FREQ_SEEK`` with the filehandle in 131 non-blocking mode. 132 133ENODATA 134 The hardware seek found no channels. 135 136EBUSY 137 Another hardware seek is already in progress. 138