vidioc-s-hw-freq-seek.rst

  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.