code:
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
.. c:namespace:: V4L

.. _VIDIOC_G_SLICED_VBI_CAP:

*****************************
ioctl VIDIOC_G_SLICED_VBI_CAP
*****************************

Name
====

VIDIOC_G_SLICED_VBI_CAP - Query sliced VBI capabilities

Synopsis
========

.. c:macro:: VIDIOC_G_SLICED_VBI_CAP

``int ioctl(int fd, VIDIOC_G_SLICED_VBI_CAP, struct v4l2_sliced_vbi_cap *argp)``

Arguments
=========

``fd``
    File descriptor returned by :c:func:`open()`.

``argp``
    Pointer to struct :c:type:`v4l2_sliced_vbi_cap`.

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

To find out which data services are supported by a sliced VBI capture or
output device, applications initialize the ``type`` field of a struct
:c:type:`v4l2_sliced_vbi_cap`, clear the
``reserved`` array and call the :ref:`VIDIOC_G_SLICED_VBI_CAP <VIDIOC_G_SLICED_VBI_CAP>` ioctl. The
driver fills in the remaining fields or returns an ``EINVAL`` error code if
the sliced VBI API is unsupported or ``type`` is invalid.

.. note::

   The ``type`` field was added, and the ioctl changed from read-only
   to write-read, in Linux 2.6.19.

.. c:type:: v4l2_sliced_vbi_cap

.. tabularcolumns:: |p{1.4cm}|p{4.4cm}|p{4.5cm}|p{3.6cm}|p{3.6cm}|

.. flat-table:: struct v4l2_sliced_vbi_cap
    :header-rows:  0
    :stub-columns: 0
    :widths:       3 3 2 2 2

    * - __u16
      - ``service_set``
      - :cspan:`2` A set of all data services supported by the driver.

	Equal to the union of all elements of the ``service_lines`` array.
    * - __u16
      - ``service_lines``\ [2][24]
      - :cspan:`2` Each element of this array contains a set of data
	services the hardware can look for or insert into a particular
	scan line. Data services are defined in :ref:`vbi-services`.
	Array indices map to ITU-R line numbers\ [#f1]_ as follows:
    * -
      -
      - Element
      - 525 line systems
      - 625 line systems
    * -
      -
      - ``service_lines``\ [0][1]
      - 1
      - 1
    * -
      -
      - ``service_lines``\ [0][23]
      - 23
      - 23
    * -
      -
      - ``service_lines``\ [1][1]
      - 264
      - 314
    * -
      -
      - ``service_lines``\ [1][23]
      - 286
      - 336
    * -
    * -
      -
      - :cspan:`2` The number of VBI lines the hardware can capture or
	output per frame, or the number of services it can identify on a
	given line may be limited. For example on PAL line 16 the hardware
	may be able to look for a VPS or Teletext signal, but not both at
	the same time. Applications can learn about these limits using the
	:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl as described in
	:ref:`sliced`.
    * -
    * -
      -
      - :cspan:`2` Drivers must set ``service_lines`` [0][0] and
	``service_lines``\ [1][0] to zero.
    * - __u32
      - ``type``
      - Type of the data stream, see :c:type:`v4l2_buf_type`. Should be
	``V4L2_BUF_TYPE_SLICED_VBI_CAPTURE`` or
	``V4L2_BUF_TYPE_SLICED_VBI_OUTPUT``.
    * - __u32
      - ``reserved``\ [3]
      - :cspan:`2` This array is reserved for future extensions.

	Applications and drivers must set it to zero.

.. [#f1]

   See also :ref:`vbi-525` and :ref:`vbi-625`.

.. raw:: latex

    \scriptsize

.. tabularcolumns:: |p{3.9cm}|p{1.0cm}|p{2.0cm}|p{3.0cm}|p{7.0cm}|

.. _vbi-services:

.. flat-table:: Sliced VBI services
    :header-rows:  1
    :stub-columns: 0
    :widths:       2 1 1 2 2

    * - Symbol
      - Value
      - Reference
      - Lines, usually
      - Payload
    * - ``V4L2_SLICED_TELETEXT_B`` (Teletext System B)
      - 0x0001
      - :ref:`ets300706`,

	:ref:`itu653`
      - PAL/SECAM line 7-22, 320-335 (second field 7-22)
      - Last 42 of the 45 byte Teletext packet, that is without clock
	run-in and framing code, lsb first transmitted.
    * - ``V4L2_SLICED_VPS``
      - 0x0400
      - :ref:`ets300231`
      - PAL line 16
      - Byte number 3 to 15 according to Figure 9 of ETS 300 231, lsb
	first transmitted.
    * - ``V4L2_SLICED_CAPTION_525``
      - 0x1000
      - :ref:`cea608`
      - NTSC line 21, 284 (second field 21)
      - Two bytes in transmission order, including parity bit, lsb first
	transmitted.
    * - ``V4L2_SLICED_WSS_625``
      - 0x4000
      - :ref:`en300294`,

	:ref:`itu1119`
      - PAL/SECAM line 23
      - See :ref:`v4l2-sliced-vbi-cap-wss-625-payload` below.
    * - ``V4L2_SLICED_VBI_525``
      - 0x1000
      - :cspan:`2` Set of services applicable to 525 line systems.
    * - ``V4L2_SLICED_VBI_625``
      - 0x4401
      - :cspan:`2` Set of services applicable to 625 line systems.

.. raw:: latex

    \normalsize

.. _v4l2-sliced-vbi-cap-wss-625-payload:

V4L2_SLICED_VBI_CAP WSS_625 payload
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The payload for ``V4L2_SLICED_WSS_625`` is:

	    +-----+------------------+-----------------------+
	    |Byte |        0         |           1           |
	    +-----+--------+---------+-----------+-----------+
	    |     | msb    | lsb     | msb       | lsb       |
	    |     +-+-+-+--+--+-+-+--+--+-+--+---+---+--+-+--+
	    | Bit |7|6|5|4 | 3|2|1|0 | x|x|13|12 | 11|10|9|8 |
	    +-----+-+-+-+--+--+-+-+--+--+-+--+---+---+--+-+--+

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 value in the ``type`` field is wrong.


code:
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
.. c:namespace:: V4L

.. _VIDIOC_G_STD:

**************************************************************************
ioctl VIDIOC_G_STD, VIDIOC_S_STD, VIDIOC_SUBDEV_G_STD, VIDIOC_SUBDEV_S_STD
**************************************************************************

Name
====

VIDIOC_G_STD - VIDIOC_S_STD - VIDIOC_SUBDEV_G_STD - VIDIOC_SUBDEV_S_STD - Query or select the video standard of the current input

Synopsis
========

.. c:macro:: VIDIOC_G_STD

``int ioctl(int fd, VIDIOC_G_STD, v4l2_std_id *argp)``

.. c:macro:: VIDIOC_S_STD

``int ioctl(int fd, VIDIOC_S_STD, const v4l2_std_id *argp)``

.. c:macro:: VIDIOC_SUBDEV_G_STD

``int ioctl(int fd, VIDIOC_SUBDEV_G_STD, v4l2_std_id *argp)``

.. c:macro:: VIDIOC_SUBDEV_S_STD

``int ioctl(int fd, VIDIOC_SUBDEV_S_STD, const v4l2_std_id *argp)``

Arguments
=========

``fd``
    File descriptor returned by :c:func:`open()`.

``argp``
    Pointer to :c:type:`v4l2_std_id`.

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

To query and select the current video standard applications use the
:ref:`VIDIOC_G_STD <VIDIOC_G_STD>` and :ref:`VIDIOC_S_STD <VIDIOC_G_STD>` ioctls which take a pointer to a
:ref:`v4l2_std_id <v4l2-std-id>` type as argument. :ref:`VIDIOC_G_STD <VIDIOC_G_STD>`
can return a single flag or a set of flags as in struct
:c:type:`v4l2_standard` field ``id``. The flags must be
unambiguous such that they appear in only one enumerated
struct :c:type:`v4l2_standard` structure.

:ref:`VIDIOC_S_STD <VIDIOC_G_STD>` accepts one or more flags, being a write-only ioctl it
does not return the actual new standard as :ref:`VIDIOC_G_STD <VIDIOC_G_STD>` does. When
no flags are given or the current input does not support the requested
standard the driver returns an ``EINVAL`` error code. When the standard set
is ambiguous drivers may return ``EINVAL`` or choose any of the requested
standards. If the current input or output does not support standard
video timings (e.g. if :ref:`VIDIOC_ENUMINPUT`
does not set the ``V4L2_IN_CAP_STD`` flag), then ``ENODATA`` error code is
returned.

Calling ``VIDIOC_SUBDEV_S_STD`` on a subdev device node that has been registered
in read-only mode is not allowed. An error is returned and the errno variable is
set to ``-EPERM``.

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 :ref:`VIDIOC_S_STD <VIDIOC_G_STD>` parameter was unsuitable.

ENODATA
    Standard video timings are not supported for this input or output.

EPERM
    ``VIDIOC_SUBDEV_S_STD`` has been called on a read-only subdevice.

repo_name: angery/linux


code:
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
.. c:namespace:: V4L

.. _VIDIOC_G_TUNER:

************************************
ioctl VIDIOC_G_TUNER, VIDIOC_S_TUNER
************************************

Name
====

VIDIOC_G_TUNER - VIDIOC_S_TUNER - Get or set tuner attributes

Synopsis
========

.. c:macro:: VIDIOC_G_TUNER

``int ioctl(int fd, VIDIOC_G_TUNER, struct v4l2_tuner *argp)``

.. c:macro:: VIDIOC_S_TUNER

``int ioctl(int fd, VIDIOC_S_TUNER, const struct v4l2_tuner *argp)``

Arguments
=========

``fd``
    File descriptor returned by :c:func:`open()`.

``argp``
    Pointer to struct :c:type:`v4l2_tuner`.

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

To query the attributes of a tuner applications initialize the ``index``
field and zero out the ``reserved`` array of a struct
:c:type:`v4l2_tuner` and call the ``VIDIOC_G_TUNER`` ioctl
with a pointer to this structure. Drivers fill the rest of the structure
or return an ``EINVAL`` error code when the index is out of bounds. To
enumerate all tuners applications shall begin at index zero,
incrementing by one until the driver returns ``EINVAL``.

Tuners have two writable properties, the audio mode and the radio
frequency. To change the audio mode, applications initialize the
``index``, ``audmode`` and ``reserved`` fields and call the
``VIDIOC_S_TUNER`` ioctl. This will *not* change the current tuner,
which is determined by the current video input. Drivers may choose a
different audio mode if the requested mode is invalid or unsupported.
Since this is a write-only ioctl, it does not return the actually
selected audio mode.

:ref:`SDR <sdr>` specific tuner types are ``V4L2_TUNER_SDR`` and
``V4L2_TUNER_RF``. For SDR devices ``audmode`` field must be initialized
to zero. The term 'tuner' means SDR receiver in this context.

To change the radio frequency the
:ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENCY>` ioctl is available.

 .. tabularcolumns:: |p{1.3cm}|p{3.0cm}|p{7.0cm}|p{5.8cm}|

.. c:type:: v4l2_tuner

.. cssclass:: longtable

.. flat-table:: struct v4l2_tuner
    :header-rows:  0
    :stub-columns: 0

    * - __u32
      - ``index``
      - :cspan:`1` Identifies the tuner, set by the application.
    * - __u8
      - ``name``\ [32]
      - :cspan:`1`

	Name of the tuner, a NUL-terminated ASCII string.

	This information is intended for the user.
    * - __u32
      - ``type``
      - :cspan:`1` Type of the tuner, see :c:type:`v4l2_tuner_type`.
    * - __u32
      - ``capability``
      - :cspan:`1`

	Tuner capability flags, see :ref:`tuner-capability`. Audio flags
	indicate the ability to decode audio subprograms. They will *not*
	change, for example with the current video standard.

	When the structure refers to a radio tuner the
	``V4L2_TUNER_CAP_LANG1``, ``V4L2_TUNER_CAP_LANG2`` and
	``V4L2_TUNER_CAP_NORM`` flags can't be used.

	If multiple frequency bands are supported, then ``capability`` is
	the union of all ``capability`` fields of each struct
	:c:type:`v4l2_frequency_band`.
    * - __u32
      - ``rangelow``
      - :cspan:`1` The lowest tunable frequency in units of 62.5 kHz, or
	if the ``capability`` flag ``V4L2_TUNER_CAP_LOW`` is set, in units
	of 62.5 Hz, or if the ``capability`` flag ``V4L2_TUNER_CAP_1HZ``
	is set, in units of 1 Hz. If multiple frequency bands are
	supported, then ``rangelow`` is the lowest frequency of all the
	frequency bands.
    * - __u32
      - ``rangehigh``
      - :cspan:`1` The highest tunable frequency in units of 62.5 kHz,
	or if the ``capability`` flag ``V4L2_TUNER_CAP_LOW`` is set, in
	units of 62.5 Hz, or if the ``capability`` flag
	``V4L2_TUNER_CAP_1HZ`` is set, in units of 1 Hz. If multiple
	frequency bands are supported, then ``rangehigh`` is the highest
	frequency of all the frequency bands.
    * - __u32
      - ``rxsubchans``
      - :cspan:`1`

	Some tuners or audio decoders can determine the received audio
	subprograms by analyzing audio carriers, pilot tones or other
	indicators. To pass this information drivers set flags defined in
	:ref:`tuner-rxsubchans` in this field. For example:
    * -
      -
      - ``V4L2_TUNER_SUB_MONO``
      - receiving mono audio
    * -
      -
      - ``STEREO | SAP``
      - receiving stereo audio and a secondary audio program
    * -
      -
      - ``MONO | STEREO``
      - receiving mono or stereo audio, the hardware cannot distinguish
    * -
      -
      - ``LANG1 | LANG2``
      - receiving bilingual audio
    * -
      -
      - ``MONO | STEREO | LANG1 | LANG2``
      - receiving mono, stereo or bilingual audio
    * -
      -
      - :cspan:`1`

	When the ``V4L2_TUNER_CAP_STEREO``, ``_LANG1``, ``_LANG2`` or
	``_SAP`` flag is cleared in the ``capability`` field, the
	corresponding ``V4L2_TUNER_SUB_`` flag must not be set here.

	This field is valid only if this is the tuner of the current video
	input, or when the structure refers to a radio tuner.
    * - __u32
      - ``audmode``
      - :cspan:`1`

	The selected audio mode, see :ref:`tuner-audmode` for valid
	values. The audio mode does not affect audio subprogram detection,
	and like a :ref:`control` it does not automatically
	change unless the requested mode is invalid or unsupported. See
	:ref:`tuner-matrix` for possible results when the selected and
	received audio programs do not match.

	Currently this is the only field of struct
	struct :c:type:`v4l2_tuner` applications can change.
    * - __u32
      - ``signal``
      - :cspan:`1` The signal strength if known.

	Ranging from 0 to 65535. Higher values indicate a better signal.
    * - __s32
      - ``afc``
      - :cspan:`1` Automatic frequency control.

	When the ``afc`` value is negative, the frequency is too
	low, when positive too high.
    * - __u32
      - ``reserved``\ [4]
      - :cspan:`1` Reserved for future extensions.

	Drivers and applications must set the array to zero.

.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}|

.. c:type:: v4l2_tuner_type

.. flat-table:: enum v4l2_tuner_type
    :header-rows:  0
    :stub-columns: 0
    :widths:       3 1 6

    * - ``V4L2_TUNER_RADIO``
      - 1
      - Tuner supports radio
    * - ``V4L2_TUNER_ANALOG_TV``
      - 2
      - Tuner supports analog TV
    * - ``V4L2_TUNER_SDR``
      - 4
      - Tuner controls the A/D and/or D/A block of a
	Software Digital Radio (SDR)
    * - ``V4L2_TUNER_RF``
      - 5
      - Tuner controls the RF part of a Software Digital Radio (SDR)

.. tabularcolumns:: |p{7.0cm}|p{2.2cm}|p{8.1cm}|

.. _tuner-capability:

.. cssclass:: longtable

.. flat-table:: Tuner and Modulator Capability Flags
    :header-rows:  0
    :stub-columns: 0
    :widths:       3 1 4

    * - ``V4L2_TUNER_CAP_LOW``
      - 0x0001
      - When set, tuning frequencies are expressed in units of 62.5 Hz
	instead of 62.5 kHz.
    * - ``V4L2_TUNER_CAP_NORM``
      - 0x0002
      - This is a multi-standard tuner; the video standard can or must be
	switched. (B/G PAL tuners for example are typically not considered
	multi-standard because the video standard is automatically
	determined from the frequency band.) The set of supported video
	standards is available from the struct
	:c:type:`v4l2_input` pointing to this tuner, see the
	description of ioctl :ref:`VIDIOC_ENUMINPUT`
	for details. Only ``V4L2_TUNER_ANALOG_TV`` tuners can have this
	capability.
    * - ``V4L2_TUNER_CAP_HWSEEK_BOUNDED``
      - 0x0004
      - If set, then this tuner supports the hardware seek functionality
	where the seek stops when it reaches the end of the frequency
	range.
    * - ``V4L2_TUNER_CAP_HWSEEK_WRAP``
      - 0x0008
      - If set, then this tuner supports the hardware seek functionality
	where the seek wraps around when it reaches the end of the
	frequency range.
    * - ``V4L2_TUNER_CAP_STEREO``
      - 0x0010
      - Stereo audio reception is supported.
    * - ``V4L2_TUNER_CAP_LANG1``
      - 0x0040
      - Reception of the primary language of a bilingual audio program is
	supported. Bilingual audio is a feature of two-channel systems,
	transmitting the primary language monaural on the main audio
	carrier and a secondary language monaural on a second carrier.
	Only ``V4L2_TUNER_ANALOG_TV`` tuners can have this capability.
    * - ``V4L2_TUNER_CAP_LANG2``
      - 0x0020
      - Reception of the secondary language of a bilingual audio program
	is supported. Only ``V4L2_TUNER_ANALOG_TV`` tuners can have this
	capability.
    * - ``V4L2_TUNER_CAP_SAP``
      - 0x0020
      - Reception of a secondary audio program is supported. This is a
	feature of the BTSC system which accompanies the NTSC video
	standard. Two audio carriers are available for mono or stereo
	transmissions of a primary language, and an independent third
	carrier for a monaural secondary language. Only
	``V4L2_TUNER_ANALOG_TV`` tuners can have this capability.

	.. note::

	   The ``V4L2_TUNER_CAP_LANG2`` and ``V4L2_TUNER_CAP_SAP``
	   flags are synonyms. ``V4L2_TUNER_CAP_SAP`` applies when the tuner
	   supports the ``V4L2_STD_NTSC_M`` video standard.
    * - ``V4L2_TUNER_CAP_RDS``
      - 0x0080
      - RDS capture is supported. This capability is only valid for radio
	tuners.
    * - ``V4L2_TUNER_CAP_RDS_BLOCK_IO``
      - 0x0100
      - The RDS data is passed as unparsed RDS blocks.
    * - ``V4L2_TUNER_CAP_RDS_CONTROLS``
      - 0x0200
      - The RDS data is parsed by the hardware and set via controls.
    * - ``V4L2_TUNER_CAP_FREQ_BANDS``
      - 0x0400
      - The :ref:`VIDIOC_ENUM_FREQ_BANDS`
	ioctl can be used to enumerate the available frequency bands.
    * - ``V4L2_TUNER_CAP_HWSEEK_PROG_LIM``
      - 0x0800
      - The range to search when using the hardware seek functionality is
	programmable, see
	:ref:`VIDIOC_S_HW_FREQ_SEEK` for
	details.
    * - ``V4L2_TUNER_CAP_1HZ``
      - 0x1000
      - When set, tuning frequencies are expressed in units of 1 Hz
	instead of 62.5 kHz.

.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}|

.. _tuner-rxsubchans:

.. flat-table:: Tuner Audio Reception Flags
    :header-rows:  0
    :stub-columns: 0
    :widths:       3 1 4

    * - ``V4L2_TUNER_SUB_MONO``
      - 0x0001
      - The tuner receives a mono audio signal.
    * - ``V4L2_TUNER_SUB_STEREO``
      - 0x0002
      - The tuner receives a stereo audio signal.
    * - ``V4L2_TUNER_SUB_LANG1``
      - 0x0008
      - The tuner receives the primary language of a bilingual audio
	signal. Drivers must clear this flag when the current video
	standard is ``V4L2_STD_NTSC_M``.
    * - ``V4L2_TUNER_SUB_LANG2``
      - 0x0004
      - The tuner receives the secondary language of a bilingual audio
	signal (or a second audio program).
    * - ``V4L2_TUNER_SUB_SAP``
      - 0x0004
      - The tuner receives a Second Audio Program.

	.. note::

	   The ``V4L2_TUNER_SUB_LANG2`` and ``V4L2_TUNER_SUB_SAP``
	   flags are synonyms. The ``V4L2_TUNER_SUB_SAP`` flag applies
	   when the current video standard is ``V4L2_STD_NTSC_M``.
    * - ``V4L2_TUNER_SUB_RDS``
      - 0x0010
      - The tuner receives an RDS channel.

.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}|

.. _tuner-audmode:

.. flat-table:: Tuner Audio Modes
    :header-rows:  0
    :stub-columns: 0
    :widths:       3 1 4

    * - ``V4L2_TUNER_MODE_MONO``
      - 0
      - Play mono audio. When the tuner receives a stereo signal this a
	down-mix of the left and right channel. When the tuner receives a
	bilingual or SAP signal this mode selects the primary language.
    * - ``V4L2_TUNER_MODE_STEREO``
      - 1
      - Play stereo audio. When the tuner receives bilingual audio it may
	play different languages on the left and right channel or the
	primary language is played on both channels.

	Playing different languages in this mode is deprecated. New
	drivers should do this only in ``MODE_LANG1_LANG2``.

	When the tuner receives no stereo signal or does not support
	stereo reception the driver shall fall back to ``MODE_MONO``.
    * - ``V4L2_TUNER_MODE_LANG1``
      - 3
      - Play the primary language, mono or stereo. Only
	``V4L2_TUNER_ANALOG_TV`` tuners support this mode.
    * - ``V4L2_TUNER_MODE_LANG2``
      - 2
      - Play the secondary language, mono. When the tuner receives no
	bilingual audio or SAP, or their reception is not supported the
	driver shall fall back to mono or stereo mode. Only
	``V4L2_TUNER_ANALOG_TV`` tuners support this mode.
    * - ``V4L2_TUNER_MODE_SAP``
      - 2
      - Play the Second Audio Program. When the tuner receives no
	bilingual audio or SAP, or their reception is not supported the
	driver shall fall back to mono or stereo mode. Only
	``V4L2_TUNER_ANALOG_TV`` tuners support this mode.

	.. note:: The ``V4L2_TUNER_MODE_LANG2`` and ``V4L2_TUNER_MODE_SAP``
	   are synonyms.
    * - ``V4L2_TUNER_MODE_LANG1_LANG2``
      - 4
      - Play the primary language on the left channel, the secondary
	language on the right channel. When the tuner receives no
	bilingual audio or SAP, it shall fall back to ``MODE_LANG1`` or
	``MODE_MONO``. Only ``V4L2_TUNER_ANALOG_TV`` tuners support this
	mode.

.. raw:: latex

    \scriptsize

.. tabularcolumns:: |p{1.5cm}|p{1.5cm}|p{2.9cm}|p{2.9cm}|p{2.9cm}|p{2.9cm}|

.. _tuner-matrix:

.. flat-table:: Tuner Audio Matrix
    :header-rows:  2
    :stub-columns: 0
    :widths: 7 7 14 14 14 14

    * -
      - :cspan:`4` Selected ``V4L2_TUNER_MODE_``
    * - Received ``V4L2_TUNER_SUB_``
      - ``MONO``
      - ``STEREO``
      - ``LANG1``
      - ``LANG2 = SAP``
      - ``LANG1_LANG2``\ [#f1]_
    * - ``MONO``
      - Mono
      - Mono/Mono
      - Mono
      - Mono
      - Mono/Mono
    * - ``MONO | SAP``
      - Mono
      - Mono/Mono
      - Mono
      - SAP
      - Mono/SAP (preferred) or Mono/Mono
    * - ``STEREO``
      - L+R
      - L/R
      - Stereo L/R (preferred) or Mono L+R
      - Stereo L/R (preferred) or Mono L+R
      - L/R (preferred) or L+R/L+R
    * - ``STEREO | SAP``
      - L+R
      - L/R
      - Stereo L/R (preferred) or Mono L+R
      - SAP
      - L+R/SAP (preferred) or L/R or L+R/L+R
    * - ``LANG1 | LANG2``
      - Language 1
      - Lang1/Lang2 (deprecated\ [#f2]_) or Lang1/Lang1
      - Language 1
      - Language 2
      - Lang1/Lang2 (preferred) or Lang1/Lang1

.. raw:: latex

    \normalsize

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 struct :c:type:`v4l2_tuner` ``index`` is out of
    bounds.

.. [#f1]
   This mode has been added in Linux 2.6.17 and may not be supported by
   older drivers.

.. [#f2]
   Playback of both languages in ``MODE_STEREO`` is deprecated. In the
   future drivers should produce only the primary language in this mode.
   Applications should request ``MODE_LANG1_LANG2`` to record both
   languages or a stereo signal.


code:
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
.. c:namespace:: V4L

.. _VIDIOC_LOG_STATUS:

***********************
ioctl VIDIOC_LOG_STATUS
***********************

Name
====

VIDIOC_LOG_STATUS - Log driver status information

Synopsis
========

.. c:macro:: VIDIOC_LOG_STATUS

``int ioctl(int fd, VIDIOC_LOG_STATUS)``

Arguments
=========

``fd``
    File descriptor returned by :c:func:`open()`.

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

As the video/audio devices become more complicated it becomes harder to
debug problems. When this ioctl is called the driver will output the
current device status to the kernel log. This is particular useful when
dealing with problems like no sound, no video and incorrectly tuned
channels. Also many modern devices autodetect video and audio standards
and this ioctl will report what the device thinks what the standard is.
Mismatches may give an indication where the problem is.

This ioctl is optional and not all drivers support it. It was introduced
in Linux 2.6.15.

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.


code:
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
.. c:namespace:: V4L

.. _VIDIOC_OVERLAY:

********************
ioctl VIDIOC_OVERLAY
********************

Name
====

VIDIOC_OVERLAY - Start or stop video overlay

Synopsis
========

.. c:macro:: VIDIOC_OVERLAY

``int ioctl(int fd, VIDIOC_OVERLAY, const int *argp)``

Arguments
=========

``fd``
    File descriptor returned by :c:func:`open()`.

``argp``
    Pointer to an integer.

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

This ioctl is part of the :ref:`video overlay <overlay>` I/O method.
Applications call :ref:`VIDIOC_OVERLAY` to start or stop the overlay. It
takes a pointer to an integer which must be set to zero by the
application to stop overlay, to one to start.

Drivers do not support :ref:`VIDIOC_STREAMON` or
:ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` with
``V4L2_BUF_TYPE_VIDEO_OVERLAY``.

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 overlay parameters have not been set up. See :ref:`overlay`
    for the necessary steps.


code:
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
.. c:namespace:: V4L

.. _VIDIOC_PREPARE_BUF:

************************
ioctl VIDIOC_PREPARE_BUF
************************

Name
====

VIDIOC_PREPARE_BUF - Prepare a buffer for I/O

Synopsis
========

.. c:macro:: VIDIOC_PREPARE_BUF

``int ioctl(int fd, VIDIOC_PREPARE_BUF, struct v4l2_buffer *argp)``

Arguments
=========

``fd``
    File descriptor returned by :c:func:`open()`.

``argp``
    Pointer to struct :c:type:`v4l2_buffer`.

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

Applications can optionally call the :ref:`VIDIOC_PREPARE_BUF` ioctl to
pass ownership of the buffer to the driver before actually enqueuing it,
using the :ref:`VIDIOC_QBUF <VIDIOC_QBUF>` ioctl, and to prepare it for future I/O. Such
preparations may include cache invalidation or cleaning. Performing them
in advance saves time during the actual I/O.

The struct :c:type:`v4l2_buffer` structure is specified in
:ref:`buffer`.

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.

EBUSY
    File I/O is in progress.

EINVAL
    The buffer ``type`` is not supported, or the ``index`` is out of
    bounds, or no buffers have been allocated yet, or the ``userptr`` or
    ``length`` are invalid.


code:
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
.. c:namespace:: V4L

.. _VIDIOC_QBUF:

*******************************
ioctl VIDIOC_QBUF, VIDIOC_DQBUF
*******************************

Name
====

VIDIOC_QBUF - VIDIOC_DQBUF - Exchange a buffer with the driver

Synopsis
========

.. c:macro:: VIDIOC_QBUF

``int ioctl(int fd, VIDIOC_QBUF, struct v4l2_buffer *argp)``

.. c:macro:: VIDIOC_DQBUF

``int ioctl(int fd, VIDIOC_DQBUF, struct v4l2_buffer *argp)``

Arguments
=========

``fd``
    File descriptor returned by :c:func:`open()`.

``argp``
    Pointer to struct :c:type:`v4l2_buffer`.

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

Applications call the ``VIDIOC_QBUF`` ioctl to enqueue an empty
(capturing) or filled (output) buffer in the driver's incoming queue.
The semantics depend on the selected I/O method.

To enqueue a buffer applications set the ``type`` field of a struct
:c:type:`v4l2_buffer` to the same buffer type as was
previously used with struct :c:type:`v4l2_format` ``type``
and struct :c:type:`v4l2_requestbuffers` ``type``.
Applications must also set the ``index`` field. Valid index numbers
range from zero to the number of buffers allocated with
:ref:`VIDIOC_REQBUFS` (struct
:c:type:`v4l2_requestbuffers` ``count``) minus
one. The contents of the struct :c:type:`v4l2_buffer` returned
by a :ref:`VIDIOC_QUERYBUF` ioctl will do as well.
When the buffer is intended for output (``type`` is
``V4L2_BUF_TYPE_VIDEO_OUTPUT``, ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``,
or ``V4L2_BUF_TYPE_VBI_OUTPUT``) applications must also initialize the
``bytesused``, ``field`` and ``timestamp`` fields, see :ref:`buffer`
for details. Applications must also set ``flags`` to 0. The
``reserved2`` and ``reserved`` fields must be set to 0. When using the
:ref:`multi-planar API <planar-apis>`, the ``m.planes`` field must
contain a userspace pointer to a filled-in array of struct
:c:type:`v4l2_plane` and the ``length`` field must be set
to the number of elements in that array.

To enqueue a :ref:`memory mapped <mmap>` buffer applications set the
``memory`` field to ``V4L2_MEMORY_MMAP``. When ``VIDIOC_QBUF`` is called
with a pointer to this structure the driver sets the
``V4L2_BUF_FLAG_MAPPED`` and ``V4L2_BUF_FLAG_QUEUED`` flags and clears
the ``V4L2_BUF_FLAG_DONE`` flag in the ``flags`` field, or it returns an
``EINVAL`` error code.

To enqueue a :ref:`user pointer <userp>` buffer applications set the
``memory`` field to ``V4L2_MEMORY_USERPTR``, the ``m.userptr`` field to
the address of the buffer and ``length`` to its size. When the
multi-planar API is used, ``m.userptr`` and ``length`` members of the
passed array of struct :c:type:`v4l2_plane` have to be used
instead. When ``VIDIOC_QBUF`` is called with a pointer to this structure
the driver sets the ``V4L2_BUF_FLAG_QUEUED`` flag and clears the
``V4L2_BUF_FLAG_MAPPED`` and ``V4L2_BUF_FLAG_DONE`` flags in the
``flags`` field, or it returns an error code. This ioctl locks the
memory pages of the buffer in physical memory, they cannot be swapped
out to disk. Buffers remain locked until dequeued, until the
:ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` or
:ref:`VIDIOC_REQBUFS` ioctl is called, or until the
device is closed.

To enqueue a :ref:`DMABUF <dmabuf>` buffer applications set the
``memory`` field to ``V4L2_MEMORY_DMABUF`` and the ``m.fd`` field to a
file descriptor associated with a DMABUF buffer. When the multi-planar
API is used the ``m.fd`` fields of the passed array of struct
:c:type:`v4l2_plane` have to be used instead. When
``VIDIOC_QBUF`` is called with a pointer to this structure the driver
sets the ``V4L2_BUF_FLAG_QUEUED`` flag and clears the
``V4L2_BUF_FLAG_MAPPED`` and ``V4L2_BUF_FLAG_DONE`` flags in the
``flags`` field, or it returns an error code. This ioctl locks the
buffer. Locking a buffer means passing it to a driver for a hardware
access (usually DMA). If an application accesses (reads/writes) a locked
buffer then the result is undefined. Buffers remain locked until
dequeued, until the :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` or
:ref:`VIDIOC_REQBUFS` ioctl is called, or until the
device is closed.

The ``request_fd`` field can be used with the ``VIDIOC_QBUF`` ioctl to specify
the file descriptor of a :ref:`request <media-request-api>`, if requests are
in use. Setting it means that the buffer will not be passed to the driver
until the request itself is queued. Also, the driver will apply any
settings associated with the request for this buffer. This field will
be ignored unless the ``V4L2_BUF_FLAG_REQUEST_FD`` flag is set.
If the device does not support requests, then ``EBADR`` will be returned.
If requests are supported but an invalid request file descriptor is given,
then ``EINVAL`` will be returned.

.. caution::
   It is not allowed to mix queuing requests with queuing buffers directly.
   ``EBUSY`` will be returned if the first buffer was queued directly and
   then the application tries to queue a request, or vice versa. After
   closing the file descriptor, calling
   :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` or calling :ref:`VIDIOC_REQBUFS`
   the check for this will be reset.

   For :ref:`memory-to-memory devices <mem2mem>` you can specify the
   ``request_fd`` only for output buffers, not for capture buffers. Attempting
   to specify this for a capture buffer will result in an ``EBADR`` error.

Applications call the ``VIDIOC_DQBUF`` ioctl to dequeue a filled
(capturing) or displayed (output) buffer from the driver's outgoing
queue. They just set the ``type``, ``memory`` and ``reserved`` fields of
a struct :c:type:`v4l2_buffer` as above, when
``VIDIOC_DQBUF`` is called with a pointer to this structure the driver
fills all remaining fields or returns an error code. The driver may also
set ``V4L2_BUF_FLAG_ERROR`` in the ``flags`` field. It indicates a
non-critical (recoverable) streaming error. In such case the application
may continue as normal, but should be aware that data in the dequeued
buffer might be corrupted. When using the multi-planar API, the planes
array must be passed in as well.

If the application sets the ``memory`` field to ``V4L2_MEMORY_DMABUF`` to
dequeue a :ref:`DMABUF <dmabuf>` buffer, the driver fills the ``m.fd`` field
with a file descriptor numerically the same as the one given to ``VIDIOC_QBUF``
when the buffer was enqueued. No new file descriptor is created at dequeue time
and the value is only for the application convenience. When the multi-planar
API is used the ``m.fd`` fields of the passed array of struct
:c:type:`v4l2_plane` are filled instead.

By default ``VIDIOC_DQBUF`` blocks when no buffer is in the outgoing
queue. When the ``O_NONBLOCK`` flag was given to the
:c:func:`open()` function, ``VIDIOC_DQBUF`` returns
immediately with an ``EAGAIN`` error code when no buffer is available.

The struct :c:type:`v4l2_buffer` structure is specified in
:ref:`buffer`.

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.

EAGAIN
    Non-blocking I/O has been selected using ``O_NONBLOCK`` and no
    buffer was in the outgoing queue.

EINVAL
    The buffer ``type`` is not supported, or the ``index`` is out of
    bounds, or no buffers have been allocated yet, or the ``userptr`` or
    ``length`` are invalid, or the ``V4L2_BUF_FLAG_REQUEST_FD`` flag was
    set but the given ``request_fd`` was invalid, or ``m.fd`` was
    an invalid DMABUF file descriptor.

EIO
    ``VIDIOC_DQBUF`` failed due to an internal error. Can also indicate
    temporary problems like signal loss.

    .. note::

       The driver might dequeue an (empty) buffer despite returning
       an error, or even stop capturing. Reusing such buffer may be unsafe
       though and its details (e.g. ``index``) may not be returned either.
       It is recommended that drivers indicate recoverable errors by setting
       the ``V4L2_BUF_FLAG_ERROR`` and returning 0 instead. In that case the
       application should be able to safely reuse the buffer and continue
       streaming.

EPIPE
    ``VIDIOC_DQBUF`` returns this on an empty capture queue for mem2mem
    codecs if a buffer with the ``V4L2_BUF_FLAG_LAST`` was already
    dequeued and no new buffers are expected to become available.

EBADR
    The ``V4L2_BUF_FLAG_REQUEST_FD`` flag was set but the device does not
    support requests for the given buffer type, or
    the ``V4L2_BUF_FLAG_REQUEST_FD`` flag was not set but the device requires
    that the buffer is part of a request.

EBUSY
    The first buffer was queued via a request, but the application now tries
    to queue it directly, or vice versa (it is not permitted to mix the two
    APIs).


code:
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
.. c:namespace:: V4L

.. _VIDIOC_QUERY_DV_TIMINGS:

*****************************
ioctl VIDIOC_QUERY_DV_TIMINGS
*****************************

Name
====

VIDIOC_QUERY_DV_TIMINGS - VIDIOC_SUBDEV_QUERY_DV_TIMINGS - Sense the DV preset received by the current input

Synopsis
========

.. c:macro:: VIDIOC_QUERY_DV_TIMINGS

``int ioctl(int fd, VIDIOC_QUERY_DV_TIMINGS, struct v4l2_dv_timings *argp)``

.. c:macro:: VIDIOC_SUBDEV_QUERY_DV_TIMINGS

``int ioctl(int fd, VIDIOC_SUBDEV_QUERY_DV_TIMINGS, struct v4l2_dv_timings *argp)``

Arguments
=========

``fd``
    File descriptor returned by :c:func:`open()`.

``argp``
    Pointer to struct :c:type:`v4l2_dv_timings`.

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

The hardware may be able to detect the current DV timings automatically,
similar to sensing the video standard. To do so, applications call
:ref:`VIDIOC_QUERY_DV_TIMINGS` with a pointer to a struct
:c:type:`v4l2_dv_timings`. Once the hardware detects
the timings, it will fill in the timings structure.

.. note::

   Drivers shall *not* switch timings automatically if new
   timings are detected. Instead, drivers should send the
   ``V4L2_EVENT_SOURCE_CHANGE`` event (if they support this) and expect
   that userspace will take action by calling :ref:`VIDIOC_QUERY_DV_TIMINGS`.
   The reason is that new timings usually mean different buffer sizes as
   well, and you cannot change buffer sizes on the fly. In general,
   applications that receive the Source Change event will have to call
   :ref:`VIDIOC_QUERY_DV_TIMINGS`, and if the detected timings are valid they
   will have to stop streaming, set the new timings, allocate new buffers
   and start streaming again.

If the timings could not be detected because there was no signal, then
ENOLINK is returned. If a signal was detected, but it was unstable and
the receiver could not lock to the signal, then ``ENOLCK`` is returned. If
the receiver could lock to the signal, but the format is unsupported
(e.g. because the pixelclock is out of range of the hardware
capabilities), then the driver fills in whatever timings it could find
and returns ``ERANGE``. In that case the application can call
:ref:`VIDIOC_DV_TIMINGS_CAP` to compare the
found timings with the hardware's capabilities in order to give more
precise feedback to the user.

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.

ENODATA
    Digital video timings are not supported for this input or output.

ENOLINK
    No timings could be detected because no signal was found.

ENOLCK
    The signal was unstable and the hardware could not lock on to it.

ERANGE
    Timings were found, but they are out of range of the hardware
    capabilities.


code:
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
.. c:namespace:: V4L

.. _VIDIOC_QUERYBUF:

*********************
ioctl VIDIOC_QUERYBUF
*********************

Name
====

VIDIOC_QUERYBUF - Query the status of a buffer

Synopsis
========

.. c:macro:: VIDIOC_QUERYBUF

``int ioctl(int fd, VIDIOC_QUERYBUF, struct v4l2_buffer *argp)``

Arguments
=========

``fd``
    File descriptor returned by :c:func:`open()`.

``argp``
    Pointer to struct :c:type:`v4l2_buffer`.

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

This ioctl is part of the :ref:`streaming <mmap>` I/O method. It can
be used to query the status of a buffer at any time after buffers have
been allocated with the :ref:`VIDIOC_REQBUFS` ioctl.

Applications set the ``type`` field of a struct
:c:type:`v4l2_buffer` to the same buffer type as was
previously used with struct :c:type:`v4l2_format` ``type``
and struct :c:type:`v4l2_requestbuffers` ``type``,
and the ``index`` field. Valid index numbers range from zero to the
number of buffers allocated with
:ref:`VIDIOC_REQBUFS` (struct
:c:type:`v4l2_requestbuffers` ``count``) minus
one. The ``reserved`` and ``reserved2`` fields must be set to 0. When
using the :ref:`multi-planar API <planar-apis>`, the ``m.planes``
field must contain a userspace pointer to an array of struct
:c:type:`v4l2_plane` and the ``length`` field has to be set
to the number of elements in that array. After calling
:ref:`VIDIOC_QUERYBUF` with a pointer to this structure drivers return an
error code or fill the rest of the structure.

In the ``flags`` field the ``V4L2_BUF_FLAG_MAPPED``,
``V4L2_BUF_FLAG_PREPARED``, ``V4L2_BUF_FLAG_QUEUED`` and
``V4L2_BUF_FLAG_DONE`` flags will be valid. The ``memory`` field will be
set to the current I/O method. For the single-planar API, the
``m.offset`` contains the offset of the buffer from the start of the
device memory, the ``length`` field its size. For the multi-planar API,
fields ``m.mem_offset`` and ``length`` in the ``m.planes`` array
elements will be used instead and the ``length`` field of struct
:c:type:`v4l2_buffer` is set to the number of filled-in
array elements. The driver may or may not set the remaining fields and
flags, they are meaningless in this context.

The struct :c:type:`v4l2_buffer` structure is specified in
:ref:`buffer`.

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 buffer ``type`` is not supported, or the ``index`` is out of
    bounds.


code:
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
.. c:namespace:: V4L

.. _VIDIOC_QUERYCAP:

*********************
ioctl VIDIOC_QUERYCAP
*********************

Name
====

VIDIOC_QUERYCAP - Query device capabilities

Synopsis
========

.. c:macro:: VIDIOC_QUERYCAP

``int ioctl(int fd, VIDIOC_QUERYCAP, struct v4l2_capability *argp)``

Arguments
=========

``fd``
    File descriptor returned by :c:func:`open()`.

``argp``
    Pointer to struct :c:type:`v4l2_capability`.

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

All V4L2 devices support the ``VIDIOC_QUERYCAP`` ioctl. It is used to
identify kernel devices compatible with this specification and to obtain
information about driver and hardware capabilities. The ioctl takes a
pointer to a struct :c:type:`v4l2_capability` which is
filled by the driver. When the driver is not compatible with this
specification the ioctl returns an ``EINVAL`` error code.

.. c:type:: v4l2_capability

.. tabularcolumns:: |p{1.4cm}|p{2.8cm}|p{13.1cm}|

.. cssclass:: longtable

.. flat-table:: struct v4l2_capability
    :header-rows:  0
    :stub-columns: 0
    :widths:       3 4 20

    * - __u8
      - ``driver``\ [16]
      - Name of the driver, a unique NUL-terminated ASCII string. For
	example: "bttv". Driver specific applications can use this
	information to verify the driver identity. It is also useful to
	work around known bugs, or to identify drivers in error reports.

	Storing strings in fixed sized arrays is bad practice but
	unavoidable here. Drivers and applications should take precautions
	to never read or write beyond the end of the array and to make
	sure the strings are properly NUL-terminated.
    * - __u8
      - ``card``\ [32]
      - Name of the device, a NUL-terminated UTF-8 string. For example:
	"Yoyodyne TV/FM". One driver may support different brands or
	models of video hardware. This information is intended for users,
	for example in a menu of available devices. Since multiple TV
	cards of the same brand may be installed which are supported by
	the same driver, this name should be combined with the character
	device file name (e. g. ``/dev/video2``) or the ``bus_info``
	string to avoid ambiguities.
    * - __u8
      - ``bus_info``\ [32]
      - Location of the device in the system, a NUL-terminated ASCII
	string. For example: "PCI:0000:05:06.0". This information is
	intended for users, to distinguish multiple identical devices. If
	no such information is available the field must simply count the
	devices controlled by the driver ("platform:vivid-000"). The
	bus_info must start with "PCI:" for PCI boards, "PCIe:" for PCI
	Express boards, "usb-" for USB devices, "I2C:" for i2c devices,
	"ISA:" for ISA devices, "parport" for parallel port devices and
	"platform:" for platform devices.
    * - __u32
      - ``version``
      - Version number of the driver.

	Starting with kernel 3.1, the version reported is provided by the
	V4L2 subsystem following the kernel numbering scheme. However, it
	may not always return the same version as the kernel if, for
	example, a stable or distribution-modified kernel uses the V4L2
	stack from a newer kernel.

	The version number is formatted using the ``KERNEL_VERSION()``
	macro. For example if the media stack corresponds to the V4L2
	version shipped with Kernel 4.14, it would be equivalent to:
    * - :cspan:`2`

	``#define KERNEL_VERSION(a,b,c) (((a) << 16) + ((b) << 8) + (c))``

	``__u32 version = KERNEL_VERSION(4, 14, 0);``

	``printf ("Version: %u.%u.%u\\n",``

	``(version >> 16) & 0xFF, (version >> 8) & 0xFF, version & 0xFF);``
    * - __u32
      - ``capabilities``
      - Available capabilities of the physical device as a whole, see
	:ref:`device-capabilities`. The same physical device can export
	multiple devices in /dev (e.g. /dev/videoX, /dev/vbiY and
	/dev/radioZ). The ``capabilities`` field should contain a union of
	all capabilities available around the several V4L2 devices
	exported to userspace. For all those devices the ``capabilities``
	field returns the same set of capabilities. This allows
	applications to open just one of the devices (typically the video
	device) and discover whether video, vbi and/or radio are also
	supported.
    * - __u32
      - ``device_caps``
      - Device capabilities of the opened device, see
	:ref:`device-capabilities`. Should contain the available
	capabilities of that specific device node. So, for example,
	``device_caps`` of a radio device will only contain radio related
	capabilities and no video or vbi capabilities. This field is only
	set if the ``capabilities`` field contains the
	``V4L2_CAP_DEVICE_CAPS`` capability. Only the ``capabilities``
	field can have the ``V4L2_CAP_DEVICE_CAPS`` capability,
	``device_caps`` will never set ``V4L2_CAP_DEVICE_CAPS``.
    * - __u32
      - ``reserved``\ [3]
      - Reserved for future extensions. Drivers must set this array to
	zero.

.. tabularcolumns:: |p{7.0cm}|p{2.6cm}|p{7.7cm}|

.. _device-capabilities:

.. cssclass:: longtable

.. flat-table:: Device Capabilities Flags
    :header-rows:  0
    :stub-columns: 0
    :widths:       3 1 4

    * - ``V4L2_CAP_VIDEO_CAPTURE``
      - 0x00000001
      - The device supports the single-planar API through the
	:ref:`Video Capture <capture>` interface.
    * - ``V4L2_CAP_VIDEO_CAPTURE_MPLANE``
      - 0x00001000
      - The device supports the :ref:`multi-planar API <planar-apis>`
	through the :ref:`Video Capture <capture>` interface.
    * - ``V4L2_CAP_VIDEO_OUTPUT``
      - 0x00000002
      - The device supports the single-planar API through the
	:ref:`Video Output <output>` interface.
    * - ``V4L2_CAP_VIDEO_OUTPUT_MPLANE``
      - 0x00002000
      - The device supports the :ref:`multi-planar API <planar-apis>`
	through the :ref:`Video Output <output>` interface.
    * - ``V4L2_CAP_VIDEO_M2M``
      - 0x00008000
      - The device supports the single-planar API through the Video
	Memory-To-Memory interface.
    * - ``V4L2_CAP_VIDEO_M2M_MPLANE``
      - 0x00004000
      - The device supports the :ref:`multi-planar API <planar-apis>`
	through the Video Memory-To-Memory interface.
    * - ``V4L2_CAP_VIDEO_OVERLAY``
      - 0x00000004
      - The device supports the :ref:`Video Overlay <overlay>`
	interface. A video overlay device typically stores captured images
	directly in the video memory of a graphics card, with hardware
	clipping and scaling.
    * - ``V4L2_CAP_VBI_CAPTURE``
      - 0x00000010
      - The device supports the :ref:`Raw VBI Capture <raw-vbi>`
	interface, providing Teletext and Closed Caption data.
    * - ``V4L2_CAP_VBI_OUTPUT``
      - 0x00000020
      - The device supports the :ref:`Raw VBI Output <raw-vbi>`
	interface.
    * - ``V4L2_CAP_SLICED_VBI_CAPTURE``
      - 0x00000040
      - The device supports the :ref:`Sliced VBI Capture <sliced>`
	interface.
    * - ``V4L2_CAP_SLICED_VBI_OUTPUT``
      - 0x00000080
      - The device supports the :ref:`Sliced VBI Output <sliced>`
	interface.
    * - ``V4L2_CAP_RDS_CAPTURE``
      - 0x00000100
      - The device supports the :ref:`RDS <rds>` capture interface.
    * - ``V4L2_CAP_VIDEO_OUTPUT_OVERLAY``
      - 0x00000200
      - The device supports the :ref:`Video Output Overlay <osd>` (OSD)
	interface. Unlike the *Video Overlay* interface, this is a
	secondary function of video output devices and overlays an image
	onto an outgoing video signal. When the driver sets this flag, it
	must clear the ``V4L2_CAP_VIDEO_OVERLAY`` flag and vice
	versa. [#f1]_
    * - ``V4L2_CAP_HW_FREQ_SEEK``
      - 0x00000400
      - The device supports the
	:ref:`VIDIOC_S_HW_FREQ_SEEK` ioctl
	for hardware frequency seeking.
    * - ``V4L2_CAP_RDS_OUTPUT``
      - 0x00000800
      - The device supports the :ref:`RDS <rds>` output interface.
    * - ``V4L2_CAP_TUNER``
      - 0x00010000
      - The device has some sort of tuner to receive RF-modulated video
	signals. For more information about tuner programming see
	:ref:`tuner`.
    * - ``V4L2_CAP_AUDIO``
      - 0x00020000
      - The device has audio inputs or outputs. It may or may not support
	audio recording or playback, in PCM or compressed formats. PCM
	audio support must be implemented as ALSA or OSS interface. For
	more information on audio inputs and outputs see :ref:`audio`.
    * - ``V4L2_CAP_RADIO``
      - 0x00040000
      - This is a radio receiver.
    * - ``V4L2_CAP_MODULATOR``
      - 0x00080000
      - The device has some sort of modulator to emit RF-modulated
	video/audio signals. For more information about modulator
	programming see :ref:`tuner`.
    * - ``V4L2_CAP_SDR_CAPTURE``
      - 0x00100000
      - The device supports the :ref:`SDR Capture <sdr>` interface.
    * - ``V4L2_CAP_EXT_PIX_FORMAT``
      - 0x00200000
      - The device supports the struct
	:c:type:`v4l2_pix_format` extended fields.
    * - ``V4L2_CAP_SDR_OUTPUT``
      - 0x00400000
      - The device supports the :ref:`SDR Output <sdr>` interface.
    * - ``V4L2_CAP_META_CAPTURE``
      - 0x00800000
      - The device supports the :ref:`metadata` capture interface.
    * - ``V4L2_CAP_READWRITE``
      - 0x01000000
      - The device supports the :c:func:`read()` and/or
	:c:func:`write()` I/O methods.
    * - ``V4L2_CAP_STREAMING``
      - 0x04000000
      - The device supports the :ref:`streaming <mmap>` I/O method.
    * - ``V4L2_CAP_META_OUTPUT``
      - 0x08000000
      - The device supports the :ref:`metadata` output interface.
    * - ``V4L2_CAP_TOUCH``
      - 0x10000000
      - This is a touch device.
    * - ``V4L2_CAP_IO_MC``
      - 0x20000000
      - There is only one input and/or output seen from userspace. The whole
        video topology configuration, including which I/O entity is routed to
        the input/output, is configured by userspace via the Media Controller.
        See :ref:`media_controller`.
    * - ``V4L2_CAP_DEVICE_CAPS``
      - 0x80000000
      - The driver fills the ``device_caps`` field. This capability can
	only appear in the ``capabilities`` field and never in the
	``device_caps`` field.

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.

.. [#f1]
   The struct :c:type:`v4l2_framebuffer` lacks an
   enum :c:type:`v4l2_buf_type` field, therefore the
   type of overlay is implied by the driver capabilities.


code:
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
.. c:namespace:: V4L

.. _VIDIOC_QUERYCTRL:

*******************************************************************
ioctls VIDIOC_QUERYCTRL, VIDIOC_QUERY_EXT_CTRL and VIDIOC_QUERYMENU
*******************************************************************

Name
====

VIDIOC_QUERYCTRL - VIDIOC_QUERY_EXT_CTRL - VIDIOC_QUERYMENU - Enumerate controls and menu control items

Synopsis
========

``int ioctl(int fd, int VIDIOC_QUERYCTRL, struct v4l2_queryctrl *argp)``

.. c:macro:: VIDIOC_QUERY_EXT_CTRL

``int ioctl(int fd, VIDIOC_QUERY_EXT_CTRL, struct v4l2_query_ext_ctrl *argp)``

.. c:macro:: VIDIOC_QUERYMENU

``int ioctl(int fd, VIDIOC_QUERYMENU, struct v4l2_querymenu *argp)``

Arguments
=========

``fd``
    File descriptor returned by :c:func:`open()`.

``argp``
    Pointer to struct :c:type:`v4l2_queryctrl`, :c:type:`v4l2_query_ext_ctrl`
    or :c:type:`v4l2_querymenu` (depending on the ioctl).

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

To query the attributes of a control applications set the ``id`` field
of a struct :ref:`v4l2_queryctrl <v4l2-queryctrl>` and call the
``VIDIOC_QUERYCTRL`` ioctl with a pointer to this structure. The driver
fills the rest of the structure or returns an ``EINVAL`` error code when the
``id`` is invalid.

It is possible to enumerate controls by calling ``VIDIOC_QUERYCTRL``
with successive ``id`` values starting from ``V4L2_CID_BASE`` up to and
exclusive ``V4L2_CID_LASTP1``. Drivers may return ``EINVAL`` if a control in
this range is not supported. Further applications can enumerate private
controls, which are not defined in this specification, by starting at
``V4L2_CID_PRIVATE_BASE`` and incrementing ``id`` until the driver
returns ``EINVAL``.

In both cases, when the driver sets the ``V4L2_CTRL_FLAG_DISABLED`` flag
in the ``flags`` field this control is permanently disabled and should
be ignored by the application. [#f1]_

When the application ORs ``id`` with ``V4L2_CTRL_FLAG_NEXT_CTRL`` the
driver returns the next supported non-compound control, or ``EINVAL`` if
there is none. In addition, the ``V4L2_CTRL_FLAG_NEXT_COMPOUND`` flag
can be specified to enumerate all compound controls (i.e. controls with
type ≥ ``V4L2_CTRL_COMPOUND_TYPES`` and/or array control, in other words
controls that contain more than one value). Specify both
``V4L2_CTRL_FLAG_NEXT_CTRL`` and ``V4L2_CTRL_FLAG_NEXT_COMPOUND`` in
order to enumerate all controls, compound or not. Drivers which do not
support these flags yet always return ``EINVAL``.

The ``VIDIOC_QUERY_EXT_CTRL`` ioctl was introduced in order to better
support controls that can use compound types, and to expose additional
control information that cannot be returned in struct
:ref:`v4l2_queryctrl <v4l2-queryctrl>` since that structure is full.

``VIDIOC_QUERY_EXT_CTRL`` is used in the same way as
``VIDIOC_QUERYCTRL``, except that the ``reserved`` array must be zeroed
as well.

Additional information is required for menu controls: the names of the
menu items. To query them applications set the ``id`` and ``index``
fields of struct :ref:`v4l2_querymenu <v4l2-querymenu>` and call the
``VIDIOC_QUERYMENU`` ioctl with a pointer to this structure. The driver
fills the rest of the structure or returns an ``EINVAL`` error code when the
``id`` or ``index`` is invalid. Menu items are enumerated by calling
``VIDIOC_QUERYMENU`` with successive ``index`` values from struct
:ref:`v4l2_queryctrl <v4l2-queryctrl>` ``minimum`` to ``maximum``,
inclusive.

.. note::

   It is possible for ``VIDIOC_QUERYMENU`` to return
   an ``EINVAL`` error code for some indices between ``minimum`` and
   ``maximum``. In that case that particular menu item is not supported by
   this driver. Also note that the ``minimum`` value is not necessarily 0.

See also the examples in :ref:`control`.

.. tabularcolumns:: |p{1.2cm}|p{3.6cm}|p{12.5cm}|

.. _v4l2-queryctrl:

.. cssclass:: longtable

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

    * - __u32
      - ``id``
      - Identifies the control, set by the application. See
	:ref:`control-id` for predefined IDs. When the ID is ORed with
	V4L2_CTRL_FLAG_NEXT_CTRL the driver clears the flag and
	returns the first control with a higher ID. Drivers which do not
	support this flag yet always return an ``EINVAL`` error code.
    * - __u32
      - ``type``
      - Type of control, see :c:type:`v4l2_ctrl_type`.
    * - __u8
      - ``name``\ [32]
      - Name of the control, a NUL-terminated ASCII string. This
	information is intended for the user.
    * - __s32
      - ``minimum``
      - Minimum value, inclusive. This field gives a lower bound for the
	control. See enum :c:type:`v4l2_ctrl_type` how
	the minimum value is to be used for each possible control type.
	Note that this a signed 32-bit value.
    * - __s32
      - ``maximum``
      - Maximum value, inclusive. This field gives an upper bound for the
	control. See enum :c:type:`v4l2_ctrl_type` how
	the maximum value is to be used for each possible control type.
	Note that this a signed 32-bit value.
    * - __s32
      - ``step``
      - This field gives a step size for the control. See enum
	:c:type:`v4l2_ctrl_type` how the step value is
	to be used for each possible control type. Note that this an
	unsigned 32-bit value.

	Generally drivers should not scale hardware control values. It may
	be necessary for example when the ``name`` or ``id`` imply a
	particular unit and the hardware actually accepts only multiples
	of said unit. If so, drivers must take care values are properly
	rounded when scaling, such that errors will not accumulate on
	repeated read-write cycles.

	This field gives the smallest change of an integer control
	actually affecting hardware. Often the information is needed when
	the user can change controls by keyboard or GUI buttons, rather
	than a slider. When for example a hardware register accepts values
	0-511 and the driver reports 0-65535, step should be 128.

	Note that although signed, the step value is supposed to be always
	positive.
    * - __s32
      - ``default_value``
      - The default value of a ``V4L2_CTRL_TYPE_INTEGER``, ``_BOOLEAN``,
	``_BITMASK``, ``_MENU`` or ``_INTEGER_MENU`` control. Not valid
	for other types of controls.

	.. note::

	   Drivers reset controls to their default value only when
	   the driver is first loaded, never afterwards.
    * - __u32
      - ``flags``
      - Control flags, see :ref:`control-flags`.
    * - __u32
      - ``reserved``\ [2]
      - Reserved for future extensions. Drivers must set the array to
	zero.

.. tabularcolumns:: |p{1.2cm}|p{5.5cm}|p{10.6cm}|

.. _v4l2-query-ext-ctrl:

.. cssclass:: longtable

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

    * - __u32
      - ``id``
      - Identifies the control, set by the application. See
	:ref:`control-id` for predefined IDs. When the ID is ORed with
	``V4L2_CTRL_FLAG_NEXT_CTRL`` the driver clears the flag and
	returns the first non-compound control with a higher ID. When the
	ID is ORed with ``V4L2_CTRL_FLAG_NEXT_COMPOUND`` the driver clears
	the flag and returns the first compound control with a higher ID.
	Set both to get the first control (compound or not) with a higher
	ID.
    * - __u32
      - ``type``
      - Type of control, see :c:type:`v4l2_ctrl_type`.
    * - char
      - ``name``\ [32]
      - Name of the control, a NUL-terminated ASCII string. This
	information is intended for the user.
    * - __s64
      - ``minimum``
      - Minimum value, inclusive. This field gives a lower bound for the
	control. See enum :c:type:`v4l2_ctrl_type` how
	the minimum value is to be used for each possible control type.
	Note that this a signed 64-bit value.
    * - __s64
      - ``maximum``
      - Maximum value, inclusive. This field gives an upper bound for the
	control. See enum :c:type:`v4l2_ctrl_type` how
	the maximum value is to be used for each possible control type.
	Note that this a signed 64-bit value.
    * - __u64
      - ``step``
      - This field gives a step size for the control. See enum
	:c:type:`v4l2_ctrl_type` how the step value is
	to be used for each possible control type. Note that this an
	unsigned 64-bit value.

	Generally drivers should not scale hardware control values. It may
	be necessary for example when the ``name`` or ``id`` imply a
	particular unit and the hardware actually accepts only multiples
	of said unit. If so, drivers must take care values are properly
	rounded when scaling, such that errors will not accumulate on
	repeated read-write cycles.

	This field gives the smallest change of an integer control
	actually affecting hardware. Often the information is needed when
	the user can change controls by keyboard or GUI buttons, rather
	than a slider. When for example a hardware register accepts values
	0-511 and the driver reports 0-65535, step should be 128.
    * - __s64
      - ``default_value``
      - The default value of a ``V4L2_CTRL_TYPE_INTEGER``, ``_INTEGER64``,
	``_BOOLEAN``, ``_BITMASK``, ``_MENU``, ``_INTEGER_MENU``, ``_U8``
	or ``_U16`` control. Not valid for other types of controls.

	.. note::

	   Drivers reset controls to their default value only when
	   the driver is first loaded, never afterwards.
    * - __u32
      - ``flags``
      - Control flags, see :ref:`control-flags`.
    * - __u32
      - ``elem_size``
      - The size in bytes of a single element of the array. Given a char
	pointer ``p`` to a 3-dimensional array you can find the position
	of cell ``(z, y, x)`` as follows:
	``p + ((z * dims[1] + y) * dims[0] + x) * elem_size``.
	``elem_size`` is always valid, also when the control isn't an
	array. For string controls ``elem_size`` is equal to
	``maximum + 1``.
    * - __u32
      - ``elems``
      - The number of elements in the N-dimensional array. If this control
	is not an array, then ``elems`` is 1. The ``elems`` field can
	never be 0.
    * - __u32
      - ``nr_of_dims``
      - The number of dimension in the N-dimensional array. If this
	control is not an array, then this field is 0.
    * - __u32
      - ``dims[V4L2_CTRL_MAX_DIMS]``
      - The size of each dimension. The first ``nr_of_dims`` elements of
	this array must be non-zero, all remaining elements must be zero.
    * - __u32
      - ``reserved``\ [32]
      - Reserved for future extensions. Applications and drivers must set
	the array to zero.

.. tabularcolumns:: |p{1.2cm}|p{3.0cm}|p{13.1cm}|

.. _v4l2-querymenu:

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

    * - __u32
      - ``id``
      - Identifies the control, set by the application from the respective
	struct :ref:`v4l2_queryctrl <v4l2-queryctrl>` ``id``.
    * - __u32
      - ``index``
      - Index of the menu item, starting at zero, set by the application.
    * - union {
      - (anonymous)
    * - __u8
      - ``name``\ [32]
      - Name of the menu item, a NUL-terminated ASCII string. This
	information is intended for the user. This field is valid for
	``V4L2_CTRL_TYPE_MENU`` type controls.
    * - __s64
      - ``value``
      - Value of the integer menu item. This field is valid for
	``V4L2_CTRL_TYPE_INTEGER_MENU`` type controls.
    * - }
      -
    * - __u32
      - ``reserved``
      - Reserved for future extensions. Drivers must set the array to
	zero.

.. c:type:: v4l2_ctrl_type

.. raw:: latex

   \footnotesize

.. tabularcolumns:: |p{6.5cm}|p{1.5cm}|p{1.1cm}|p{1.5cm}|p{6.8cm}|

.. cssclass:: longtable

.. flat-table:: enum v4l2_ctrl_type
    :header-rows:  1
    :stub-columns: 0
    :widths:       30 5 5 5 55

    * - Type
      - ``minimum``
      - ``step``
      - ``maximum``
      - Description
    * - ``V4L2_CTRL_TYPE_INTEGER``
      - any
      - any
      - any
      - An integer-valued control ranging from minimum to maximum
	inclusive. The step value indicates the increment between values.
    * - ``V4L2_CTRL_TYPE_BOOLEAN``
      - 0
      - 1
      - 1
      - A boolean-valued control. Zero corresponds to "disabled", and one
	means "enabled".
    * - ``V4L2_CTRL_TYPE_MENU``
      - ≥ 0
      - 1
      - N-1
      - The control has a menu of N choices. The names of the menu items
	can be enumerated with the ``VIDIOC_QUERYMENU`` ioctl.
    * - ``V4L2_CTRL_TYPE_INTEGER_MENU``
      - ≥ 0
      - 1
      - N-1
      - The control has a menu of N choices. The values of the menu items
	can be enumerated with the ``VIDIOC_QUERYMENU`` ioctl. This is
	similar to ``V4L2_CTRL_TYPE_MENU`` except that instead of strings,
	the menu items are signed 64-bit integers.
    * - ``V4L2_CTRL_TYPE_BITMASK``
      - 0
      - n/a
      - any
      - A bitmask field. The maximum value is the set of bits that can be
	used, all other bits are to be 0. The maximum value is interpreted
	as a __u32, allowing the use of bit 31 in the bitmask.
    * - ``V4L2_CTRL_TYPE_BUTTON``
      - 0
      - 0
      - 0
      - A control which performs an action when set. Drivers must ignore
	the value passed with ``VIDIOC_S_CTRL`` and return an ``EACCES`` error
	code on a ``VIDIOC_G_CTRL`` attempt.
    * - ``V4L2_CTRL_TYPE_INTEGER64``
      - any
      - any
      - any
      - A 64-bit integer valued control. Minimum, maximum and step size
	cannot be queried using ``VIDIOC_QUERYCTRL``. Only
	``VIDIOC_QUERY_EXT_CTRL`` can retrieve the 64-bit min/max/step
	values, they should be interpreted as n/a when using
	``VIDIOC_QUERYCTRL``.
    * - ``V4L2_CTRL_TYPE_STRING``
      - ≥ 0
      - ≥ 1
      - ≥ 0
      - The minimum and maximum string lengths. The step size means that
	the string must be (minimum + N * step) characters long for N ≥ 0.
	These lengths do not include the terminating zero, so in order to
	pass a string of length 8 to
	:ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` you need to
	set the ``size`` field of struct
	:c:type:`v4l2_ext_control` to 9. For
	:ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` you can set
	the ``size`` field to ``maximum`` + 1. Which character encoding is
	used will depend on the string control itself and should be part
	of the control documentation.
    * - ``V4L2_CTRL_TYPE_CTRL_CLASS``
      - n/a
      - n/a
      - n/a
      - This is not a control. When ``VIDIOC_QUERYCTRL`` is called with a
	control ID equal to a control class code (see :ref:`ctrl-class`)
	+ 1, the ioctl returns the name of the control class and this
	control type. Older drivers which do not support this feature
	return an ``EINVAL`` error code.
    * - ``V4L2_CTRL_TYPE_U8``
      - any
      - any
      - any
      - An unsigned 8-bit valued control ranging from minimum to maximum
	inclusive. The step value indicates the increment between values.
    * - ``V4L2_CTRL_TYPE_U16``
      - any
      - any
      - any
      - An unsigned 16-bit valued control ranging from minimum to maximum
	inclusive. The step value indicates the increment between values.
    * - ``V4L2_CTRL_TYPE_U32``
      - any
      - any
      - any
      - An unsigned 32-bit valued control ranging from minimum to maximum
	inclusive. The step value indicates the increment between values.
    * - ``V4L2_CTRL_TYPE_MPEG2_QUANTISATION``
      - n/a
      - n/a
      - n/a
      - A struct :c:type:`v4l2_ctrl_mpeg2_quantisation`, containing MPEG-2
	quantisation matrices for stateless video decoders.
    * - ``V4L2_CTRL_TYPE_MPEG2_SEQUENCE``
      - n/a
      - n/a
      - n/a
      - A struct :c:type:`v4l2_ctrl_mpeg2_sequence`, containing MPEG-2
	sequence parameters for stateless video decoders.
    * - ``V4L2_CTRL_TYPE_MPEG2_PICTURE``
      - n/a
      - n/a
      - n/a
      - A struct :c:type:`v4l2_ctrl_mpeg2_picture`, containing MPEG-2
	picture parameters for stateless video decoders.
    * - ``V4L2_CTRL_TYPE_AREA``
      - n/a
      - n/a
      - n/a
      - A struct :c:type:`v4l2_area`, containing the width and the height
        of a rectangular area. Units depend on the use case.
    * - ``V4L2_CTRL_TYPE_H264_SPS``
      - n/a
      - n/a
      - n/a
      - A struct :c:type:`v4l2_ctrl_h264_sps`, containing H264
	sequence parameters for stateless video decoders.
    * - ``V4L2_CTRL_TYPE_H264_PPS``
      - n/a
      - n/a
      - n/a
      - A struct :c:type:`v4l2_ctrl_h264_pps`, containing H264
	picture parameters for stateless video decoders.
    * - ``V4L2_CTRL_TYPE_H264_SCALING_MATRIX``
      - n/a
      - n/a
      - n/a
      - A struct :c:type:`v4l2_ctrl_h264_scaling_matrix`, containing H264
	scaling matrices for stateless video decoders.
    * - ``V4L2_CTRL_TYPE_H264_SLICE_PARAMS``
      - n/a
      - n/a
      - n/a
      - A struct :c:type:`v4l2_ctrl_h264_slice_params`, containing H264
	slice parameters for stateless video decoders.
    * - ``V4L2_CTRL_TYPE_H264_DECODE_PARAMS``
      - n/a
      - n/a
      - n/a
      - A struct :c:type:`v4l2_ctrl_h264_decode_params`, containing H264
	decode parameters for stateless video decoders.
    * - ``V4L2_CTRL_TYPE_FWHT_PARAMS``
      - n/a
      - n/a
      - n/a
      - A struct :c:type:`v4l2_ctrl_fwht_params`, containing FWHT
	parameters for stateless video decoders.
    * - ``V4L2_CTRL_TYPE_HEVC_SPS``
      - n/a
      - n/a
      - n/a
      - A struct :c:type:`v4l2_ctrl_hevc_sps`, containing HEVC Sequence
	Parameter Set for stateless video decoders.
    * - ``V4L2_CTRL_TYPE_HEVC_PPS``
      - n/a
      - n/a
      - n/a
      - A struct :c:type:`v4l2_ctrl_hevc_pps`, containing HEVC Picture
	Parameter Set for stateless video decoders.
    * - ``V4L2_CTRL_TYPE_HEVC_SLICE_PARAMS``
      - n/a
      - n/a
      - n/a
      - A struct :c:type:`v4l2_ctrl_hevc_slice_params`, containing HEVC
	slice parameters for stateless video decoders.
    * - ``V4L2_CTRL_TYPE_HEVC_SCALING_MATRIX``
      - n/a
      - n/a
      - n/a
      - A struct :c:type:`v4l2_ctrl_hevc_scaling_matrix`, containing HEVC
	scaling matrix for stateless video decoders.
    * - ``V4L2_CTRL_TYPE_VP8_FRAME``
      - n/a
      - n/a
      - n/a
      - A struct :c:type:`v4l2_ctrl_vp8_frame`, containing VP8
	frame parameters for stateless video decoders.
    * - ``V4L2_CTRL_TYPE_HEVC_DECODE_PARAMS``
      - n/a
      - n/a
      - n/a
      - A struct :c:type:`v4l2_ctrl_hevc_decode_params`, containing HEVC
	decoding parameters for stateless video decoders.
    * - ``V4L2_CTRL_TYPE_VP9_COMPRESSED_HDR``
      - n/a
      - n/a
      - n/a
      - A struct :c:type:`v4l2_ctrl_vp9_compressed_hdr`, containing VP9
	probabilities updates for stateless video decoders.
    * - ``V4L2_CTRL_TYPE_VP9_FRAME``
      - n/a
      - n/a
      - n/a
      - A struct :c:type:`v4l2_ctrl_vp9_frame`, containing VP9
	frame decode parameters for stateless video decoders.

.. raw:: latex

   \normalsize

.. tabularcolumns:: |p{7.3cm}|p{1.8cm}|p{8.2cm}|

.. cssclass:: longtable

.. _control-flags:

.. flat-table:: Control Flags
    :header-rows:  0
    :stub-columns: 0
    :widths:       3 1 4

    * - ``V4L2_CTRL_FLAG_DISABLED``
      - 0x0001
      - This control is permanently disabled and should be ignored by the
	application. Any attempt to change the control will result in an
	``EINVAL`` error code.
    * - ``V4L2_CTRL_FLAG_GRABBED``
      - 0x0002
      - This control is temporarily unchangeable, for example because
	another application took over control of the respective resource.
	Such controls may be displayed specially in a user interface.
	Attempts to change the control may result in an ``EBUSY`` error code.
    * - ``V4L2_CTRL_FLAG_READ_ONLY``
      - 0x0004
      - This control is permanently readable only. Any attempt to change
	the control will result in an ``EINVAL`` error code.
    * - ``V4L2_CTRL_FLAG_UPDATE``
      - 0x0008
      - A hint that changing this control may affect the value of other
	controls within the same control class. Applications should update
	their user interface accordingly.
    * - ``V4L2_CTRL_FLAG_INACTIVE``
      - 0x0010
      - This control is not applicable to the current configuration and
	should be displayed accordingly in a user interface. For example
	the flag may be set on a MPEG audio level 2 bitrate control when
	MPEG audio encoding level 1 was selected with another control.
    * - ``V4L2_CTRL_FLAG_SLIDER``
      - 0x0020
      - A hint that this control is best represented as a slider-like
	element in a user interface.
    * - ``V4L2_CTRL_FLAG_WRITE_ONLY``
      - 0x0040
      - This control is permanently writable only. Any attempt to read the
	control will result in an ``EACCES`` error code error code. This flag
	is typically present for relative controls or action controls
	where writing a value will cause the device to carry out a given
	action (e. g. motor control) but no meaningful value can be
	returned.
    * - ``V4L2_CTRL_FLAG_VOLATILE``
      - 0x0080
      - This control is volatile, which means that the value of the
	control changes continuously. A typical example would be the
	current gain value if the device is in auto-gain mode. In such a
	case the hardware calculates the gain value based on the lighting
	conditions which can change over time.

	.. note::

	   Setting a new value for a volatile control will be ignored
	   unless
	   :ref:`V4L2_CTRL_FLAG_EXECUTE_ON_WRITE <FLAG_EXECUTE_ON_WRITE>`
	   is also set.
	   Setting a new value for a volatile control will *never* trigger a
	   :ref:`V4L2_EVENT_CTRL_CH_VALUE <ctrl-changes-flags>` event.
    * - ``V4L2_CTRL_FLAG_HAS_PAYLOAD``
      - 0x0100
      - This control has a pointer type, so its value has to be accessed
	using one of the pointer fields of struct
	:c:type:`v4l2_ext_control`. This flag is set
	for controls that are an array, string, or have a compound type.
	In all cases you have to set a pointer to memory containing the
	payload of the control.
    * .. _FLAG_EXECUTE_ON_WRITE:

      - ``V4L2_CTRL_FLAG_EXECUTE_ON_WRITE``
      - 0x0200
      - The value provided to the control will be propagated to the driver
	even if it remains constant. This is required when the control
	represents an action on the hardware. For example: clearing an
	error flag or triggering the flash. All the controls of the type
	``V4L2_CTRL_TYPE_BUTTON`` have this flag set.
    * .. _FLAG_MODIFY_LAYOUT:

      - ``V4L2_CTRL_FLAG_MODIFY_LAYOUT``
      - 0x0400
      - Changing this control value may modify the layout of the
        buffer (for video devices) or the media bus format (for sub-devices).

	A typical example would be the ``V4L2_CID_ROTATE`` control.

	Note that typically controls with this flag will also set the
	``V4L2_CTRL_FLAG_GRABBED`` flag when buffers are allocated or
	streaming is in progress since most drivers do not support changing
	the format in that case.
    * - ``V4L2_CTRL_FLAG_DYNAMIC_ARRAY``
      - 0x0800
      - This control is a dynamically sized 1-dimensional array. It
        behaves the same as a regular array, except that the number
	of elements as reported by the ``elems`` field is between 1 and
	``dims[0]``. So setting the control with a differently sized
	array will change the ``elems`` field when the control is
	queried afterwards.

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 struct :ref:`v4l2_queryctrl <v4l2-queryctrl>` ``id`` is
    invalid. The struct :ref:`v4l2_querymenu <v4l2-querymenu>` ``id``
    is invalid or ``index`` is out of range (less than ``minimum`` or
    greater than ``maximum``) or this particular menu item is not
    supported by the driver.

EACCES
    An attempt was made to read a write-only control.

.. [#f1]
   ``V4L2_CTRL_FLAG_DISABLED`` was intended for two purposes: Drivers
   can skip predefined controls not supported by the hardware (although
   returning ``EINVAL`` would do as well), or disable predefined and private
   controls after hardware detection without the trouble of reordering
   control arrays and indices (``EINVAL`` cannot be used to skip private
   controls because it would prematurely end the enumeration).


code:
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
.. c:namespace:: V4L

.. _VIDIOC_QUERYSTD:

*********************************************
ioctl VIDIOC_QUERYSTD, VIDIOC_SUBDEV_QUERYSTD
*********************************************

Name
====

VIDIOC_QUERYSTD - VIDIOC_SUBDEV_QUERYSTD - Sense the video standard received by the current input

Synopsis
========

.. c:macro:: VIDIOC_QUERYSTD

``int ioctl(int fd, VIDIOC_QUERYSTD, v4l2_std_id *argp)``

.. c:macro:: VIDIOC_SUBDEV_QUERYSTD

``int ioctl(int fd, VIDIOC_SUBDEV_QUERYSTD, v4l2_std_id *argp)``

Arguments
=========

``fd``
    File descriptor returned by :c:func:`open()`.

``argp``
    Pointer to :c:type:`v4l2_std_id`.

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

The hardware may be able to detect the current video standard
automatically. To do so, applications call :ref:`VIDIOC_QUERYSTD` with a
pointer to a :ref:`v4l2_std_id <v4l2-std-id>` type. The driver
stores here a set of candidates, this can be a single flag or a set of
supported standards if for example the hardware can only distinguish
between 50 and 60 Hz systems. If no signal was detected, then the driver
will return V4L2_STD_UNKNOWN. When detection is not possible or fails,
the set must contain all standards supported by the current video input
or output.

.. note::

   Drivers shall *not* switch the video standard
   automatically if a new video standard is detected. Instead, drivers
   should send the ``V4L2_EVENT_SOURCE_CHANGE`` event (if they support
   this) and expect that userspace will take action by calling
   :ref:`VIDIOC_QUERYSTD`. The reason is that a new video standard can mean
   different buffer sizes as well, and you cannot change buffer sizes on
   the fly. In general, applications that receive the Source Change event
   will have to call :ref:`VIDIOC_QUERYSTD`, and if the detected video
   standard is valid they will have to stop streaming, set the new
   standard, allocate new buffers and start streaming again.

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.

ENODATA
    Standard video timings are not supported for this input or output.


code:
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
.. c:namespace:: V4L

.. _VIDIOC_REQBUFS:

********************
ioctl VIDIOC_REQBUFS
********************

Name
====

VIDIOC_REQBUFS - Initiate Memory Mapping, User Pointer I/O or DMA buffer I/O

Synopsis
========

.. c:macro:: VIDIOC_REQBUFS

``int ioctl(int fd, VIDIOC_REQBUFS, struct v4l2_requestbuffers *argp)``

Arguments
=========

``fd``
    File descriptor returned by :c:func:`open()`.

``argp``
    Pointer to struct :c:type:`v4l2_requestbuffers`.

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

This ioctl is used to initiate :ref:`memory mapped <mmap>`,
:ref:`user pointer <userp>` or :ref:`DMABUF <dmabuf>` based I/O.
Memory mapped buffers are located in device memory and must be allocated
with this ioctl before they can be mapped into the application's address
space. User buffers are allocated by applications themselves, and this
ioctl is merely used to switch the driver into user pointer I/O mode and
to setup some internal structures. Similarly, DMABUF buffers are
allocated by applications through a device driver, and this ioctl only
configures the driver into DMABUF I/O mode without performing any direct
allocation.

To allocate device buffers applications initialize all fields of the
struct :c:type:`v4l2_requestbuffers` structure. They set the ``type``
field to the respective stream or buffer type, the ``count`` field to
the desired number of buffers, ``memory`` must be set to the requested
I/O method and the ``reserved`` array must be zeroed. When the ioctl is
called with a pointer to this structure the driver will attempt to
allocate the requested number of buffers and it stores the actual number
allocated in the ``count`` field. It can be smaller than the number
requested, even zero, when the driver runs out of free memory. A larger
number is also possible when the driver requires more buffers to
function correctly. For example video output requires at least two
buffers, one displayed and one filled by the application.

When the I/O method is not supported the ioctl returns an ``EINVAL`` error
code.

Applications can call :ref:`VIDIOC_REQBUFS` again to change the number of
buffers. Note that if any buffers are still mapped or exported via DMABUF,
then :ref:`VIDIOC_REQBUFS` can only succeed if the
``V4L2_BUF_CAP_SUPPORTS_ORPHANED_BUFS`` capability is set. Otherwise
:ref:`VIDIOC_REQBUFS` will return the ``EBUSY`` error code.
If ``V4L2_BUF_CAP_SUPPORTS_ORPHANED_BUFS`` is set, then these buffers are
orphaned and will be freed when they are unmapped or when the exported DMABUF
fds are closed. A ``count`` value of zero frees or orphans all buffers, after
aborting or finishing any DMA in progress, an implicit
:ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>`.

.. c:type:: v4l2_requestbuffers

.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}|

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

    * - __u32
      - ``count``
      - The number of buffers requested or granted.
    * - __u32
      - ``type``
      - Type of the stream or buffers, this is the same as the struct
	:c:type:`v4l2_format` ``type`` field. See
	:c:type:`v4l2_buf_type` for valid values.
    * - __u32
      - ``memory``
      - Applications set this field to ``V4L2_MEMORY_MMAP``,
	``V4L2_MEMORY_DMABUF`` or ``V4L2_MEMORY_USERPTR``. See
	:c:type:`v4l2_memory`.
    * - __u32
      - ``capabilities``
      - Set by the driver. If 0, then the driver doesn't support
        capabilities. In that case all you know is that the driver is
	guaranteed to support ``V4L2_MEMORY_MMAP`` and *might* support
	other :c:type:`v4l2_memory` types. It will not support any other
	capabilities.

	If you want to query the capabilities with a minimum of side-effects,
	then this can be called with ``count`` set to 0, ``memory`` set to
	``V4L2_MEMORY_MMAP`` and ``type`` set to the buffer type. This will
	free any previously allocated buffers, so this is typically something
	that will be done at the start of the application.
    * - __u8
      - ``flags``
      - Specifies additional buffer management attributes.
	See :ref:`memory-flags`.
    * - __u8
      - ``reserved``\ [3]
      - Reserved for future extensions.

.. _v4l2-buf-capabilities:
.. _V4L2-BUF-CAP-SUPPORTS-MMAP:
.. _V4L2-BUF-CAP-SUPPORTS-USERPTR:
.. _V4L2-BUF-CAP-SUPPORTS-DMABUF:
.. _V4L2-BUF-CAP-SUPPORTS-REQUESTS:
.. _V4L2-BUF-CAP-SUPPORTS-ORPHANED-BUFS:
.. _V4L2-BUF-CAP-SUPPORTS-M2M-HOLD-CAPTURE-BUF:
.. _V4L2-BUF-CAP-SUPPORTS-MMAP-CACHE-HINTS:

.. raw:: latex

   \footnotesize

.. tabularcolumns:: |p{8.1cm}|p{2.2cm}|p{7.0cm}|

.. cssclass:: longtable

.. flat-table:: V4L2 Buffer Capabilities Flags
    :header-rows:  0
    :stub-columns: 0
    :widths:       3 1 4

    * - ``V4L2_BUF_CAP_SUPPORTS_MMAP``
      - 0x00000001
      - This buffer type supports the ``V4L2_MEMORY_MMAP`` streaming mode.
    * - ``V4L2_BUF_CAP_SUPPORTS_USERPTR``
      - 0x00000002
      - This buffer type supports the ``V4L2_MEMORY_USERPTR`` streaming mode.
    * - ``V4L2_BUF_CAP_SUPPORTS_DMABUF``
      - 0x00000004
      - This buffer type supports the ``V4L2_MEMORY_DMABUF`` streaming mode.
    * - ``V4L2_BUF_CAP_SUPPORTS_REQUESTS``
      - 0x00000008
      - This buffer type supports :ref:`requests <media-request-api>`.
    * - ``V4L2_BUF_CAP_SUPPORTS_ORPHANED_BUFS``
      - 0x00000010
      - The kernel allows calling :ref:`VIDIOC_REQBUFS` while buffers are still
        mapped or exported via DMABUF. These orphaned buffers will be freed
        when they are unmapped or when the exported DMABUF fds are closed.
    * - ``V4L2_BUF_CAP_SUPPORTS_M2M_HOLD_CAPTURE_BUF``
      - 0x00000020
      - Only valid for stateless decoders. If set, then userspace can set the
        ``V4L2_BUF_FLAG_M2M_HOLD_CAPTURE_BUF`` flag to hold off on returning the
	capture buffer until the OUTPUT timestamp changes.
    * - ``V4L2_BUF_CAP_SUPPORTS_MMAP_CACHE_HINTS``
      - 0x00000040
      - This capability is set by the driver to indicate that the queue supports
        cache and memory management hints. However, it's only valid when the
        queue is used for :ref:`memory mapping <mmap>` streaming I/O. See
        :ref:`V4L2_BUF_FLAG_NO_CACHE_INVALIDATE <V4L2-BUF-FLAG-NO-CACHE-INVALIDATE>`,
        :ref:`V4L2_BUF_FLAG_NO_CACHE_CLEAN <V4L2-BUF-FLAG-NO-CACHE-CLEAN>` and
        :ref:`V4L2_MEMORY_FLAG_NON_COHERENT <V4L2-MEMORY-FLAG-NON-COHERENT>`.

.. raw:: latex

   \normalsize

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 buffer type (``type`` field) or the requested I/O method
    (``memory``) is not supported.


code:
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
.. c:namespace:: V4L

.. _VIDIOC_S_HW_FREQ_SEEK:

***************************
ioctl VIDIOC_S_HW_FREQ_SEEK
***************************

Name
====

VIDIOC_S_HW_FREQ_SEEK - Perform a hardware frequency seek

Synopsis
========

.. c:macro:: VIDIOC_S_HW_FREQ_SEEK

``int ioctl(int fd, VIDIOC_S_HW_FREQ_SEEK, struct v4l2_hw_freq_seek *argp)``

Arguments
=========

``fd``
    File descriptor returned by :c:func:`open()`.

``argp``
    Pointer to struct :c:type:`v4l2_hw_freq_seek`.

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

Start a hardware frequency seek from the current frequency. To do this
applications initialize the ``tuner``, ``type``, ``seek_upward``,
``wrap_around``, ``spacing``, ``rangelow`` and ``rangehigh`` fields, and
zero out the ``reserved`` array of a struct
:c:type:`v4l2_hw_freq_seek` and call the
``VIDIOC_S_HW_FREQ_SEEK`` ioctl with a pointer to this structure.

The ``rangelow`` and ``rangehigh`` fields can be set to a non-zero value
to tell the driver to search a specific band. If the struct
:c:type:`v4l2_tuner` ``capability`` field has the
``V4L2_TUNER_CAP_HWSEEK_PROG_LIM`` flag set, these values must fall
within one of the bands returned by
:ref:`VIDIOC_ENUM_FREQ_BANDS`. If the
``V4L2_TUNER_CAP_HWSEEK_PROG_LIM`` flag is not set, then these values
must exactly match those of one of the bands returned by
:ref:`VIDIOC_ENUM_FREQ_BANDS`. If the
current frequency of the tuner does not fall within the selected band it
will be clamped to fit in the band before the seek is started.

If an error is returned, then the original frequency will be restored.

This ioctl is supported if the ``V4L2_CAP_HW_FREQ_SEEK`` capability is
set.

If this ioctl is called from a non-blocking filehandle, then ``EAGAIN``
error code is returned and no seek takes place.

.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}|

.. c:type:: v4l2_hw_freq_seek

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

    * - __u32
      - ``tuner``
      - The tuner index number. This is the same value as in the struct
	:c:type:`v4l2_input` ``tuner`` field and the struct
	:c:type:`v4l2_tuner` ``index`` field.
    * - __u32
      - ``type``
      - The tuner type. This is the same value as in the struct
	:c:type:`v4l2_tuner` ``type`` field. See
	:c:type:`v4l2_tuner_type`
    * - __u32
      - ``seek_upward``
      - If non-zero, seek upward from the current frequency, else seek
	downward.
    * - __u32
      - ``wrap_around``
      - If non-zero, wrap around when at the end of the frequency range,
	else stop seeking. The struct :c:type:`v4l2_tuner`
	``capability`` field will tell you what the hardware supports.
    * - __u32
      - ``spacing``
      - If non-zero, defines the hardware seek resolution in Hz. The
	driver selects the nearest value that is supported by the device.
	If spacing is zero a reasonable default value is used.
    * - __u32
      - ``rangelow``
      - If non-zero, the lowest tunable frequency of the band to search in
	units of 62.5 kHz, or if the struct
	:c:type:`v4l2_tuner` ``capability`` field has the
	``V4L2_TUNER_CAP_LOW`` flag set, in units of 62.5 Hz or if the
	struct :c:type:`v4l2_tuner` ``capability`` field has
	the ``V4L2_TUNER_CAP_1HZ`` flag set, in units of 1 Hz. If
	``rangelow`` is zero a reasonable default value is used.
    * - __u32
      - ``rangehigh``
      - If non-zero, the highest tunable frequency of the band to search
	in units of 62.5 kHz, or if the struct
	:c:type:`v4l2_tuner` ``capability`` field has the
	``V4L2_TUNER_CAP_LOW`` flag set, in units of 62.5 Hz or if the
	struct :c:type:`v4l2_tuner` ``capability`` field has
	the ``V4L2_TUNER_CAP_1HZ`` flag set, in units of 1 Hz. If
	``rangehigh`` is zero a reasonable default value is used.
    * - __u32
      - ``reserved``\ [5]
      - Reserved for future extensions. 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, the ``wrap_around`` value is
    not supported or one of the values in the ``type``, ``rangelow`` or
    ``rangehigh`` fields is wrong.

EAGAIN
    Attempted to call ``VIDIOC_S_HW_FREQ_SEEK`` with the filehandle in
    non-blocking mode.

ENODATA
    The hardware seek found no channels.

EBUSY
    Another hardware seek is already in progress.


code:
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
.. c:namespace:: V4L

.. _VIDIOC_STREAMON:

***************************************
ioctl VIDIOC_STREAMON, VIDIOC_STREAMOFF
***************************************

Name
====

VIDIOC_STREAMON - VIDIOC_STREAMOFF - Start or stop streaming I/O

Synopsis
========

.. c:macro:: VIDIOC_STREAMON

``int ioctl(int fd, VIDIOC_STREAMON, const int *argp)``

.. c:macro:: VIDIOC_STREAMOFF

``int ioctl(int fd, VIDIOC_STREAMOFF, const int *argp)``

Arguments
=========

``fd``
    File descriptor returned by :c:func:`open()`.

``argp``
    Pointer to an integer.

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

The ``VIDIOC_STREAMON`` and ``VIDIOC_STREAMOFF`` ioctl start and stop
the capture or output process during streaming
(:ref:`memory mapping <mmap>`, :ref:`user pointer <userp>` or
:ref:`DMABUF <dmabuf>`) I/O.

Capture hardware is disabled and no input buffers are filled (if there
are any empty buffers in the incoming queue) until ``VIDIOC_STREAMON``
has been called. Output hardware is disabled and no video signal is
produced until ``VIDIOC_STREAMON`` has been called.

Memory-to-memory devices will not start until ``VIDIOC_STREAMON`` has
been called for both the capture and output stream types.

If ``VIDIOC_STREAMON`` fails then any already queued buffers will remain
queued.

The ``VIDIOC_STREAMOFF`` ioctl, apart of aborting or finishing any DMA
in progress, unlocks any user pointer buffers locked in physical memory,
and it removes all buffers from the incoming and outgoing queues. That
means all images captured but not dequeued yet will be lost, likewise
all images enqueued for output but not transmitted yet. I/O returns to
the same state as after calling
:ref:`VIDIOC_REQBUFS` and can be restarted
accordingly.

If buffers have been queued with :ref:`VIDIOC_QBUF` and
``VIDIOC_STREAMOFF`` is called without ever having called
``VIDIOC_STREAMON``, then those queued buffers will also be removed from
the incoming queue and all are returned to the same state as after
calling :ref:`VIDIOC_REQBUFS` and can be restarted
accordingly.

Both ioctls take a pointer to an integer, the desired buffer or stream
type. This is the same as struct
:c:type:`v4l2_requestbuffers` ``type``.

If ``VIDIOC_STREAMON`` is called when streaming is already in progress,
or if ``VIDIOC_STREAMOFF`` is called when streaming is already stopped,
then 0 is returned. Nothing happens in the case of ``VIDIOC_STREAMON``,
but ``VIDIOC_STREAMOFF`` will return queued buffers to their starting
state as mentioned above.

.. note::

   Applications can be preempted for unknown periods right before
   or after the ``VIDIOC_STREAMON`` or ``VIDIOC_STREAMOFF`` calls, there is
   no notion of starting or stopping "now". Buffer timestamps can be used
   to synchronize with other events.

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 buffer ``type`` is not supported, or no buffers have been
    allocated (memory mapping) or enqueued (output) yet.

EPIPE
    The driver implements
    :ref:`pad-level format configuration <pad-level-formats>` and the
    pipeline configuration is invalid.

ENOLINK
    The driver implements Media Controller interface and the pipeline
    link configuration is invalid.


code:
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
.. c:namespace:: V4L

.. _VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL:

***************************************
ioctl VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL
***************************************

Name
====

VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL - Enumerate frame intervals

Synopsis
========

.. c:macro:: VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL

``int ioctl(int fd, VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL, struct v4l2_subdev_frame_interval_enum * argp)``

Arguments
=========

``fd``
    File descriptor returned by :c:func:`open()`.

``argp``
    Pointer to struct :c:type:`v4l2_subdev_frame_interval_enum`.

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

This ioctl lets applications enumerate available frame intervals on a
given sub-device pad. Frame intervals only makes sense for sub-devices
that can control the frame period on their own. This includes, for
instance, image sensors and TV tuners.

For the common use case of image sensors, the frame intervals available
on the sub-device output pad depend on the frame format and size on the
same pad. Applications must thus specify the desired format and size
when enumerating frame intervals.

To enumerate frame intervals applications initialize the ``index``,
``pad``, ``which``, ``code``, ``width`` and ``height`` fields of struct
:c:type:`v4l2_subdev_frame_interval_enum`
and call the :ref:`VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL` ioctl with a pointer
to this structure. Drivers fill the rest of the structure or return an
EINVAL error code if one of the input fields is invalid. All frame
intervals are enumerable by beginning at index zero and incrementing by
one until ``EINVAL`` is returned.

Available frame intervals may depend on the current 'try' formats at
other pads of the sub-device, as well as on the current active links.
See :ref:`VIDIOC_SUBDEV_G_FMT` for more
information about the try formats.

Sub-devices that support the frame interval enumeration ioctl should
implemented it on a single pad only. Its behaviour when supported on
multiple pads of the same sub-device is not defined.

.. c:type:: v4l2_subdev_frame_interval_enum

.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}|

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

    * - __u32
      - ``index``
      - Number of the format in the enumeration, set by the application.
    * - __u32
      - ``pad``
      - Pad number as reported by the media controller API.
    * - __u32
      - ``code``
      - The media bus format code, as defined in
	:ref:`v4l2-mbus-format`.
    * - __u32
      - ``width``
      - Frame width, in pixels.
    * - __u32
      - ``height``
      - Frame height, in pixels.
    * - struct :c:type:`v4l2_fract`
      - ``interval``
      - Period, in seconds, between consecutive video frames.
    * - __u32
      - ``which``
      - Frame intervals to be enumerated, from enum
	:ref:`v4l2_subdev_format_whence <v4l2-subdev-format-whence>`.
    * - __u32
      - ``reserved``\ [8]
      - Reserved for future extensions. Applications and drivers 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 struct
    :c:type:`v4l2_subdev_frame_interval_enum`
    ``pad`` references a non-existing pad, one of the ``code``,
    ``width`` or ``height`` fields are invalid for the given pad or the
    ``index`` field is out of bounds.


code:
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
.. c:namespace:: V4L

.. _VIDIOC_SUBDEV_ENUM_FRAME_SIZE:

***********************************
ioctl VIDIOC_SUBDEV_ENUM_FRAME_SIZE
***********************************

Name
====

VIDIOC_SUBDEV_ENUM_FRAME_SIZE - Enumerate media bus frame sizes

Synopsis
========

.. c:macro:: VIDIOC_SUBDEV_ENUM_FRAME_SIZE

``int ioctl(int fd, VIDIOC_SUBDEV_ENUM_FRAME_SIZE, struct v4l2_subdev_frame_size_enum * argp)``

Arguments
=========

``fd``
    File descriptor returned by :c:func:`open()`.

``argp``
    Pointer to struct :c:type:`v4l2_subdev_frame_size_enum`.

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

This ioctl allows applications to enumerate all frame sizes supported by
a sub-device on the given pad for the given media bus format. Supported
formats can be retrieved with the
:ref:`VIDIOC_SUBDEV_ENUM_MBUS_CODE`
ioctl.

To enumerate frame sizes applications initialize the ``pad``, ``which``
, ``code`` and ``index`` fields of the struct
:c:type:`v4l2_subdev_mbus_code_enum` and
call the :ref:`VIDIOC_SUBDEV_ENUM_FRAME_SIZE` ioctl with a pointer to the
structure. Drivers fill the minimum and maximum frame sizes or return an
EINVAL error code if one of the input parameters is invalid.

Sub-devices that only support discrete frame sizes (such as most
sensors) will return one or more frame sizes with identical minimum and
maximum values.

Not all possible sizes in given [minimum, maximum] ranges need to be
supported. For instance, a scaler that uses a fixed-point scaling ratio
might not be able to produce every frame size between the minimum and
maximum values. Applications must use the
:ref:`VIDIOC_SUBDEV_S_FMT <VIDIOC_SUBDEV_G_FMT>` ioctl to try the
sub-device for an exact supported frame size.

Available frame sizes may depend on the current 'try' formats at other
pads of the sub-device, as well as on the current active links and the
current values of V4L2 controls. See
:ref:`VIDIOC_SUBDEV_G_FMT` for more
information about try formats.

.. c:type:: v4l2_subdev_frame_size_enum

.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}|

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

    * - __u32
      - ``index``
      - Number of the format in the enumeration, set by the application.
    * - __u32
      - ``pad``
      - Pad number as reported by the media controller API.
    * - __u32
      - ``code``
      - The media bus format code, as defined in
	:ref:`v4l2-mbus-format`.
    * - __u32
      - ``min_width``
      - Minimum frame width, in pixels.
    * - __u32
      - ``max_width``
      - Maximum frame width, in pixels.
    * - __u32
      - ``min_height``
      - Minimum frame height, in pixels.
    * - __u32
      - ``max_height``
      - Maximum frame height, in pixels.
    * - __u32
      - ``which``
      - Frame sizes to be enumerated, from enum
	:ref:`v4l2_subdev_format_whence <v4l2-subdev-format-whence>`.
    * - __u32
      - ``reserved``\ [8]
      - Reserved for future extensions. Applications and drivers 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 struct
    :c:type:`v4l2_subdev_frame_size_enum`
    ``pad`` references a non-existing pad, the ``code`` is invalid for
    the given pad or the ``index`` field is out of bounds.