[mirror_ubuntu-bionic-kernel.git] / Documentation / linux_tv / media / v4l / querycap.rst

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

.. _querycap:

*********************
Querying Capabilities
*********************

Because V4L2 covers a wide variety of devices not all aspects of the API
are equally applicable to all types of devices. Furthermore devices of
the same type have different capabilities and this specification permits
the omission of a few complicated and less important parts of the API.

The :ref:`VIDIOC_QUERYCAP <VIDIOC_QUERYCAP>` ioctl is available to
check if the kernel device is compatible with this specification, and to
query the :ref:`functions <devices>` and :ref:`I/O methods <io>`
supported by the device.

Starting with kernel version 3.1, :ref:`VIDIOC_QUERYCAP <VIDIOC_QUERYCAP>`
will return the V4L2 API version used by the driver, with generally
matches the Kernel version. There's no need of using
:ref:`VIDIOC_QUERYCAP <VIDIOC_QUERYCAP>` to check if a specific ioctl
is supported, the V4L2 core now returns ENOTTY if a driver doesn't
provide support for an ioctl.

Other features can be queried by calling the respective ioctl, for
example :ref:`VIDIOC_ENUMINPUT <VIDIOC_ENUMINPUT>` to learn about the
number, types and names of video connectors on the device. Although
abstraction is a major objective of this API, the
:ref:`VIDIOC_QUERYCAP <VIDIOC_QUERYCAP>` ioctl also allows driver
specific applications to reliably identify the driver.

All V4L2 drivers must support :ref:`VIDIOC_QUERYCAP <VIDIOC_QUERYCAP>`.
Applications should always call this ioctl after opening the device.


.. ------------------------------------------------------------------------------
.. This file was automatically converted from DocBook-XML with the dbxml
.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
.. from the linux kernel, refer to:
..
.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
.. ------------------------------------------------------------------------------
Commit	Line	Data
5377d91f MH	1	.. -- coding: utf-8; mode: rst --
	2
	3	.. _querycap:
	4
	5	*********************
	6	Querying Capabilities
	7	*********************
	8
	9	Because V4L2 covers a wide variety of devices not all aspects of the API
	10	are equally applicable to all types of devices. Furthermore devices of
	11	the same type have different capabilities and this specification permits
	12	the omission of a few complicated and less important parts of the API.
	13
af4a4d0d	14	The :ref:`VIDIOC_QUERYCAP <VIDIOC_QUERYCAP>` ioctl is available to
5377d91f MH	15	check if the kernel device is compatible with this specification, and to
	16	query the :ref:`functions <devices>` and :ref:`I/O methods <io>`
	17	supported by the device.
	18
af4a4d0d	19	Starting with kernel version 3.1, :ref:`VIDIOC_QUERYCAP <VIDIOC_QUERYCAP>`
9e00ffca MCC	20	will return the V4L2 API version used by the driver, with generally
9e00ffca MCC	21	matches the Kernel version. There's no need of using
af4a4d0d	22	:ref:`VIDIOC_QUERYCAP <VIDIOC_QUERYCAP>` to check if a specific ioctl
5377d91f MH	23	is supported, the V4L2 core now returns ENOTTY if a driver doesn't
	24	provide support for an ioctl.
	25
	26	Other features can be queried by calling the respective ioctl, for
af4a4d0d	27	example :ref:`VIDIOC_ENUMINPUT <VIDIOC_ENUMINPUT>` to learn about the
5377d91f MH	28	number, types and names of video connectors on the device. Although
5377d91f MH	29	abstraction is a major objective of this API, the
af4a4d0d	30	:ref:`VIDIOC_QUERYCAP <VIDIOC_QUERYCAP>` ioctl also allows driver
5377d91f MH	31	specific applications to reliably identify the driver.
5377d91f MH	32
af4a4d0d	33	All V4L2 drivers must support :ref:`VIDIOC_QUERYCAP <VIDIOC_QUERYCAP>`.
9e00ffca	34	Applications should always call this ioctl after opening the device.
5377d91f MH	35
	36
	37	.. ------------------------------------------------------------------------------
	38	.. This file was automatically converted from DocBook-XML with the dbxml
	39	.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
	40	.. from the linux kernel, refer to:
	41	..
	42	.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
	43	.. ------------------------------------------------------------------------------