138 lines · plain
1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later2.. c:namespace:: V4L3 4.. _VIDIOC_S_HW_FREQ_SEEK:5 6***************************7ioctl VIDIOC_S_HW_FREQ_SEEK8***************************9 10Name11====12 13VIDIOC_S_HW_FREQ_SEEK - Perform a hardware frequency seek14 15Synopsis16========17 18.. c:macro:: VIDIOC_S_HW_FREQ_SEEK19 20``int ioctl(int fd, VIDIOC_S_HW_FREQ_SEEK, struct v4l2_hw_freq_seek *argp)``21 22Arguments23=========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 31Description32===========33 34Start a hardware frequency seek from the current frequency. To do this35applications initialize the ``tuner``, ``type``, ``seek_upward``,36``wrap_around``, ``spacing``, ``rangelow`` and ``rangehigh`` fields, and37zero out the ``reserved`` array of a struct38:c:type:`v4l2_hw_freq_seek` and call the39``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 value42to tell the driver to search a specific band. If the struct43:c:type:`v4l2_tuner` ``capability`` field has the44``V4L2_TUNER_CAP_HWSEEK_PROG_LIM`` flag set, these values must fall45within one of the bands returned by46:ref:`VIDIOC_ENUM_FREQ_BANDS`. If the47``V4L2_TUNER_CAP_HWSEEK_PROG_LIM`` flag is not set, then these values48must exactly match those of one of the bands returned by49:ref:`VIDIOC_ENUM_FREQ_BANDS`. If the50current frequency of the tuner does not fall within the selected band it51will 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 is56set.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_seek64 65.. flat-table:: struct v4l2_hw_freq_seek66 :header-rows: 067 :stub-columns: 068 :widths: 1 1 269 70 * - __u3271 - ``tuner``72 - The tuner index number. This is the same value as in the struct73 :c:type:`v4l2_input` ``tuner`` field and the struct74 :c:type:`v4l2_tuner` ``index`` field.75 * - __u3276 - ``type``77 - The tuner type. This is the same value as in the struct78 :c:type:`v4l2_tuner` ``type`` field. See79 :c:type:`v4l2_tuner_type`80 * - __u3281 - ``seek_upward``82 - If non-zero, seek upward from the current frequency, else seek83 downward.84 * - __u3285 - ``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 * - __u3290 - ``spacing``91 - If non-zero, defines the hardware seek resolution in Hz. The92 driver selects the nearest value that is supported by the device.93 If spacing is zero a reasonable default value is used.94 * - __u3295 - ``rangelow``96 - If non-zero, the lowest tunable frequency of the band to search in97 units of 62.5 kHz, or if the struct98 :c:type:`v4l2_tuner` ``capability`` field has the99 ``V4L2_TUNER_CAP_LOW`` flag set, in units of 62.5 Hz or if the100 struct :c:type:`v4l2_tuner` ``capability`` field has101 the ``V4L2_TUNER_CAP_1HZ`` flag set, in units of 1 Hz. If102 ``rangelow`` is zero a reasonable default value is used.103 * - __u32104 - ``rangehigh``105 - If non-zero, the highest tunable frequency of the band to search106 in units of 62.5 kHz, or if the struct107 :c:type:`v4l2_tuner` ``capability`` field has the108 ``V4L2_TUNER_CAP_LOW`` flag set, in units of 62.5 Hz or if the109 struct :c:type:`v4l2_tuner` ``capability`` field has110 the ``V4L2_TUNER_CAP_1HZ`` flag set, in units of 1 Hz. If111 ``rangehigh`` is zero a reasonable default value is used.112 * - __u32113 - ``reserved``\ [5]114 - Reserved for future extensions. Applications must set the array to115 zero.116 117Return Value118============119 120On success 0 is returned, on error -1 and the ``errno`` variable is set121appropriately. The generic error codes are described at the122:ref:`Generic Error Codes <gen-errors>` chapter.123 124EINVAL125 The ``tuner`` index is out of bounds, the ``wrap_around`` value is126 not supported or one of the values in the ``type``, ``rangelow`` or127 ``rangehigh`` fields is wrong.128 129EAGAIN130 Attempted to call ``VIDIOC_S_HW_FREQ_SEEK`` with the filehandle in131 non-blocking mode.132 133ENODATA134 The hardware seek found no channels.135 136EBUSY137 Another hardware seek is already in progress.138