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

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

.. _VIDIOC_G_CTRL:

**********************************
ioctl VIDIOC_G_CTRL, VIDIOC_S_CTRL
**********************************

*man VIDIOC_G_CTRL(2)*

VIDIOC_S_CTRL
Get or set the value of a control


Synopsis
========

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

Arguments
=========

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

``request``
    VIDIOC_G_CTRL, VIDIOC_S_CTRL

``argp``


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

To get the current value of a control applications initialize the ``id``
field of a struct :c:type:`struct v4l2_control` and call the
:ref:`VIDIOC_G_CTRL <VIDIOC_G_CTRL>` ioctl with a pointer to this structure. To change the
value of a control applications initialize the ``id`` and ``value``
fields of a struct :c:type:`struct v4l2_control` and call the
:ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` ioctl.

When the ``id`` is invalid drivers return an EINVAL error code. When the
``value`` is out of bounds drivers can choose to take the closest valid
value or return an ERANGE error code, whatever seems more appropriate.
However, :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` is a write-only ioctl, it does not return the
actual new value. If the ``value`` is inappropriate for the control
(e.g. if it refers to an unsupported menu index of a menu control), then
EINVAL error code is returned as well.

These ioctls work only with user controls. For other control classes the
:ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>`,
:ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` or
:ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` must be used.


.. _v4l2-control:

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


    -  .. row 1

       -  __u32

       -  ``id``

       -  Identifies the control, set by the application.

    -  .. row 2

       -  __s32

       -  ``value``

       -  New value or current value.


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_control <v4l2-control>` ``id`` is invalid
    or the ``value`` is inappropriate for the given control (i.e. if a
    menu item is selected that is not supported by the driver according
    to :ref:`VIDIOC_QUERYMENU <VIDIOC_QUERYCTRL>`).

ERANGE
    The struct :ref:`v4l2_control <v4l2-control>` ``value`` is out of
    bounds.

EBUSY
    The control is temporarily not changeable, possibly because another
    applications took over control of the device function this control
    belongs to.

EACCES
    Attempt to set a read-only control or to get a write-only control.


.. ------------------------------------------------------------------------------
.. This file was automatically converted from DocBook-XML with the dbxml
.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
.. from the linux kernel, refer to:
..
.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
.. ------------------------------------------------------------------------------
Commit	Line	Data
5377d91f MH	1	.. -- coding: utf-8; mode: rst --
5377d91f MH	2
af4a4d0d	3	.. _VIDIOC_G_CTRL:
5377d91f MH	4
	5	**********************************
	6	ioctl VIDIOC_G_CTRL, VIDIOC_S_CTRL
	7	**********************************
	8
	9	man VIDIOC_G_CTRL(2)
	10
	11	VIDIOC_S_CTRL
	12	Get or set the value of a control
	13
	14
	15	Synopsis
	16	========
	17
	18	.. c:function:: int ioctl( int fd, int request, struct v4l2_control *argp )
	19
	20	Arguments
	21	=========
	22
	23	``fd``
	24	File descriptor returned by :ref:`open() <func-open>`.
	25
	26	``request``
	27	VIDIOC_G_CTRL, VIDIOC_S_CTRL
	28
	29	``argp``
	30
	31
	32	Description
	33	===========
	34
	35	To get the current value of a control applications initialize the ``id``
	36	field of a struct :c:type:`struct v4l2_control` and call the
4e03cb76	37	:ref:`VIDIOC_G_CTRL <VIDIOC_G_CTRL>` ioctl with a pointer to this structure. To change the
5377d91f MH	38	value of a control applications initialize the ``id`` and ``value``
5377d91f MH	39	fields of a struct :c:type:`struct v4l2_control` and call the
2212ff25	40	:ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` ioctl.
5377d91f MH	41
	42	When the ``id`` is invalid drivers return an EINVAL error code. When the
	43	``value`` is out of bounds drivers can choose to take the closest valid
	44	value or return an ERANGE error code, whatever seems more appropriate.
2212ff25	45	However, :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` is a write-only ioctl, it does not return the
5377d91f MH	46	actual new value. If the ``value`` is inappropriate for the control
	47	(e.g. if it refers to an unsupported menu index of a menu control), then
	48	EINVAL error code is returned as well.
	49
	50	These ioctls work only with user controls. For other control classes the
4e03cb76	51	:ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>`,
af4a4d0d MCC	52	:ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` or
af4a4d0d MCC	53	:ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` must be used.
5377d91f MH	54
	55
	56	.. _v4l2-control:
	57
	58	.. flat-table:: struct v4l2_control
	59	:header-rows: 0
	60	:stub-columns: 0
	61	:widths: 1 1 2
	62
	63
	64	- .. row 1
	65
	66	- __u32
	67
	68	- ``id``
	69
	70	- Identifies the control, set by the application.
	71
	72	- .. row 2
	73
	74	- __s32
	75
	76	- ``value``
	77
	78	- New value or current value.
	79
	80
	81
	82	Return Value
	83	============
	84
	85	On success 0 is returned, on error -1 and the ``errno`` variable is set
	86	appropriately. The generic error codes are described at the
	87	:ref:`Generic Error Codes <gen-errors>` chapter.
	88
	89	EINVAL
	90	The struct :ref:`v4l2_control <v4l2-control>` ``id`` is invalid
	91	or the ``value`` is inappropriate for the given control (i.e. if a
	92	menu item is selected that is not supported by the driver according
af4a4d0d	93	to :ref:`VIDIOC_QUERYMENU <VIDIOC_QUERYCTRL>`).
5377d91f MH	94
	95	ERANGE
	96	The struct :ref:`v4l2_control <v4l2-control>` ``value`` is out of
	97	bounds.
	98
	99	EBUSY
	100	The control is temporarily not changeable, possibly because another
	101	applications took over control of the device function this control
	102	belongs to.
	103
	104	EACCES
	105	Attempt to set a read-only control or to get a write-only control.
	106
	107
	108	.. ------------------------------------------------------------------------------
	109	.. This file was automatically converted from DocBook-XML with the dbxml
	110	.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
	111	.. from the linux kernel, refer to:
	112	..
	113	.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
	114	.. ------------------------------------------------------------------------------