[deliverable/linux.git] / Documentation / linux_tv / media / v4l / vidioc-g-frequency.rst

.. -*- coding: utf-8; mode: rst -*-

.. _VIDIOC_G_FREQUENCY:

********************************************
ioctl VIDIOC_G_FREQUENCY, VIDIOC_S_FREQUENCY
********************************************

*man VIDIOC_G_FREQUENCY(2)*

VIDIOC_S_FREQUENCY
Get or set tuner or modulator radio frequency


Synopsis
========

.. c:function:: int ioctl( int fd, int request, struct v4l2_frequency *argp )

.. c:function:: int ioctl( int fd, int request, const struct v4l2_frequency *argp )

Arguments
=========

``fd``
    File descriptor returned by :ref:`open() <func-open>`.

``request``
    VIDIOC_G_FREQUENCY, VIDIOC_S_FREQUENCY

``argp``


Description
===========

To get the current tuner or modulator radio frequency applications set
the ``tuner`` field of a struct
:ref:`v4l2_frequency <v4l2-frequency>` to the respective tuner or
modulator number (only input devices have tuners, only output devices
have modulators), zero out the ``reserved`` array and call the
:ref:`VIDIOC_G_FREQUENCY <VIDIOC_G_FREQUENCY>` ioctl with a pointer to this structure. The
driver stores the current frequency in the ``frequency`` field.

To change the current tuner or modulator radio frequency applications
initialize the ``tuner``, ``type`` and ``frequency`` fields, and the
``reserved`` array of a struct :ref:`v4l2_frequency <v4l2-frequency>`
and call the :ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENCY>` ioctl with a pointer to this
structure. When the requested frequency is not possible the driver
assumes the closest possible value. However :ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENCY>` is a
write-only ioctl, it does not return the actual new frequency.


.. _v4l2-frequency:

.. flat-table:: struct v4l2_frequency
    :header-rows:  0
    :stub-columns: 0
    :widths:       1 1 2


    -  .. row 1

       -  __u32

       -  ``tuner``

       -  The tuner or modulator index number. This is the same value as in
          the struct :ref:`v4l2_input <v4l2-input>` ``tuner`` field and
          the struct :ref:`v4l2_tuner <v4l2-tuner>` ``index`` field, or
          the struct :ref:`v4l2_output <v4l2-output>` ``modulator`` field
          and the struct :ref:`v4l2_modulator <v4l2-modulator>` ``index``
          field.

    -  .. row 2

       -  __u32

       -  ``type``

       -  The tuner type. This is the same value as in the struct
          :ref:`v4l2_tuner <v4l2-tuner>` ``type`` field. The type must be
          set to ``V4L2_TUNER_RADIO`` for ``/dev/radioX`` device nodes, and
          to ``V4L2_TUNER_ANALOG_TV`` for all others. Set this field to
          ``V4L2_TUNER_RADIO`` for modulators (currently only radio
          modulators are supported). See :ref:`v4l2-tuner-type`

    -  .. row 3

       -  __u32

       -  ``frequency``

       -  Tuning frequency in units of 62.5 kHz, or if the struct
          :ref:`v4l2_tuner <v4l2-tuner>` or struct
          :ref:`v4l2_modulator <v4l2-modulator>` ``capability`` flag
          ``V4L2_TUNER_CAP_LOW`` is set, in units of 62.5 Hz. A 1 Hz unit is
          used when the ``capability`` flag ``V4L2_TUNER_CAP_1HZ`` is set.

    -  .. row 4

       -  __u32

       -  ``reserved``\ [8]

       -  Reserved for future extensions. Drivers and applications must set
          the array to zero.


Return Value
============

On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.

EINVAL
    The ``tuner`` index is out of bounds or the value in the ``type``
    field is wrong.

EBUSY
    A hardware seek is in progress.


.. ------------------------------------------------------------------------------
.. This file was automatically converted from DocBook-XML with the dbxml
.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
.. from the linux kernel, refer to:
..
.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
.. ------------------------------------------------------------------------------
Commit	Line	Data
5377d91f MH	1	.. -- coding: utf-8; mode: rst --
5377d91f MH	2
af4a4d0d	3	.. _VIDIOC_G_FREQUENCY:
5377d91f MH	4
	5	********************************************
	6	ioctl VIDIOC_G_FREQUENCY, VIDIOC_S_FREQUENCY
	7	********************************************
	8
	9	man VIDIOC_G_FREQUENCY(2)
	10
	11	VIDIOC_S_FREQUENCY
	12	Get or set tuner or modulator radio frequency
	13
	14
	15	Synopsis
	16	========
	17
	18	.. c:function:: int ioctl( int fd, int request, struct v4l2_frequency *argp )
	19
	20	.. c:function:: int ioctl( int fd, int request, const struct v4l2_frequency *argp )
	21
	22	Arguments
	23	=========
	24
	25	``fd``
	26	File descriptor returned by :ref:`open() <func-open>`.
	27
	28	``request``
	29	VIDIOC_G_FREQUENCY, VIDIOC_S_FREQUENCY
	30
	31	``argp``
	32
	33
	34	Description
	35	===========
	36
	37	To get the current tuner or modulator radio frequency applications set
	38	the ``tuner`` field of a struct
	39	:ref:`v4l2_frequency <v4l2-frequency>` to the respective tuner or
	40	modulator number (only input devices have tuners, only output devices
	41	have modulators), zero out the ``reserved`` array and call the
4e03cb76	42	:ref:`VIDIOC_G_FREQUENCY <VIDIOC_G_FREQUENCY>` ioctl with a pointer to this structure. The
5377d91f MH	43	driver stores the current frequency in the ``frequency`` field.
	44
	45	To change the current tuner or modulator radio frequency applications
	46	initialize the ``tuner``, ``type`` and ``frequency`` fields, and the
	47	``reserved`` array of a struct :ref:`v4l2_frequency <v4l2-frequency>`
2212ff25	48	and call the :ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENCY>` ioctl with a pointer to this
5377d91f	49	structure. When the requested frequency is not possible the driver
2212ff25	50	assumes the closest possible value. However :ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENCY>` is a
5377d91f MH	51	write-only ioctl, it does not return the actual new frequency.
	52
	53
	54	.. _v4l2-frequency:
	55
	56	.. flat-table:: struct v4l2_frequency
	57	:header-rows: 0
	58	:stub-columns: 0
	59	:widths: 1 1 2
	60
	61
	62	- .. row 1
	63
	64	- __u32
	65
	66	- ``tuner``
	67
	68	- The tuner or modulator index number. This is the same value as in
	69	the struct :ref:`v4l2_input <v4l2-input>` ``tuner`` field and
	70	the struct :ref:`v4l2_tuner <v4l2-tuner>` ``index`` field, or
	71	the struct :ref:`v4l2_output <v4l2-output>` ``modulator`` field
	72	and the struct :ref:`v4l2_modulator <v4l2-modulator>` ``index``
	73	field.
	74
	75	- .. row 2
	76
	77	- __u32
	78
	79	- ``type``
	80
	81	- The tuner type. This is the same value as in the struct
	82	:ref:`v4l2_tuner <v4l2-tuner>` ``type`` field. The type must be
	83	set to ``V4L2_TUNER_RADIO`` for ``/dev/radioX`` device nodes, and
	84	to ``V4L2_TUNER_ANALOG_TV`` for all others. Set this field to
	85	``V4L2_TUNER_RADIO`` for modulators (currently only radio
	86	modulators are supported). See :ref:`v4l2-tuner-type`
	87
	88	- .. row 3
	89
	90	- __u32
	91
	92	- ``frequency``
	93
	94	- Tuning frequency in units of 62.5 kHz, or if the struct
	95	:ref:`v4l2_tuner <v4l2-tuner>` or struct
	96	:ref:`v4l2_modulator <v4l2-modulator>` ``capability`` flag
	97	``V4L2_TUNER_CAP_LOW`` is set, in units of 62.5 Hz. A 1 Hz unit is
	98	used when the ``capability`` flag ``V4L2_TUNER_CAP_1HZ`` is set.
	99
	100	- .. row 4
	101
	102	- __u32
	103
	104	- ``reserved``\ [8]
	105
	106	- Reserved for future extensions. Drivers and applications must set
	107	the array to zero.
	108
	109
	110
	111	Return Value
	112	============
	113
	114	On success 0 is returned, on error -1 and the ``errno`` variable is set
115	appropriately. The generic error codes are described at the
116	:ref:`Generic Error Codes <gen-errors>` chapter.
117
118	EINVAL
119	The ``tuner`` index is out of bounds or the value in the ``type``
120	field is wrong.
121
122	EBUSY
123	A hardware seek is in progress.
124
125
126	.. ------------------------------------------------------------------------------
127	.. This file was automatically converted from DocBook-XML with the dbxml
128	.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
129	.. from the linux kernel, refer to:
130	..
131	.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
132	.. ------------------------------------------------------------------------------