vidioc-g-ctrl.rst 2.7 KB
Newer Older
1 2
.. -*- coding: utf-8; mode: rst -*-

3
.. _VIDIOC_G_CTRL:
4 5 6 7 8

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

9
Name
10
====
11

12
VIDIOC_G_CTRL - VIDIOC_S_CTRL - Get or set the value of a control
13

14 15

Synopsis
16 17
========

18
.. cpp:function:: int ioctl( int fd, int request, struct v4l2_control *argp )
19

20

21
Arguments
22 23 24 25 26 27 28 29 30 31 32
=========

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

``request``
    VIDIOC_G_CTRL, VIDIOC_S_CTRL

``argp``


33
Description
34 35 36
===========

To get the current value of a control applications initialize the ``id``
37
field of a struct :ref:`struct v4l2_control <v4l2-control>` and call the
38
:ref:`VIDIOC_G_CTRL <VIDIOC_G_CTRL>` ioctl with a pointer to this structure. To change the
39
value of a control applications initialize the ``id`` and ``value``
40
fields of a struct :ref:`struct v4l2_control <v4l2-control>` and call the
41
:ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` ioctl.
42

43
When the ``id`` is invalid drivers return an ``EINVAL`` error code. When the
44
``value`` is out of bounds drivers can choose to take the closest valid
45
value or return an ``ERANGE`` error code, whatever seems more appropriate.
46
However, :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` is a write-only ioctl, it does not return the
47 48 49 50 51
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
52
:ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>`,
53 54
:ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` or
:ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` must be used.
55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81


.. _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.


82
Return Value
83 84 85 86 87 88 89 90 91 92
============

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
93
    to :ref:`VIDIOC_QUERYMENU <VIDIOC_QUERYCTRL>`).
94 95 96 97 98 99 100 101 102 103 104 105

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.