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