Documentation/media/uapi/v4l/vidioc-g-ctrl.rst

   1 .. -*- coding: utf-8; mode: rst -*-
   2
   3 .. _VIDIOC_G_CTRL:
   4
   5 **********************************
   6 ioctl VIDIOC_G_CTRL, VIDIOC_S_CTRL
   7 **********************************
   8
   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 .. c:function:: int ioctl( int fd, int request, struct v4l2_control *argp )
  19
  20
  21 Arguments
  22 =========
  23
  24 ``fd``
  25     File descriptor returned by :ref:`open() <func-open>`.
  26
  27 ``request``
  28     VIDIOC_G_CTRL, VIDIOC_S_CTRL
  29
  30 ``argp``
  31
  32
  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 actual new value. If the ``value`` is inappropriate for the control
  48 (e.g. if it refers to an unsupported menu index of a menu control), then
  49 EINVAL error code is returned as well.
  50
  51 These ioctls work only with user controls. For other control classes the
  52 :ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>`,
  53 :ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` or
  54 :ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` must be used.
  55
  56
  57 .. _v4l2-control:
  58
  59 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
  60
  61 .. flat-table:: struct v4l2_control
  62     :header-rows:  0
  63     :stub-columns: 0
  64     :widths:       1 1 2
  65
  66
  67     -  .. row 1
  68
  69        -  __u32
  70
  71        -  ``id``
  72
  73        -  Identifies the control, set by the application.
  74
  75     -  .. row 2
  76
  77        -  __s32
  78
  79        -  ``value``
  80
  81        -  New value or current value.
  82
  83
  84 Return Value
  85 ============
  86
  87 On success 0 is returned, on error -1 and the ``errno`` variable is set
  88 appropriately. The generic error codes are described at the
  89 :ref:`Generic Error Codes <gen-errors>` chapter.
  90
  91 EINVAL
  92     The struct :ref:`v4l2_control <v4l2-control>` ``id`` is invalid
  93     or the ``value`` is inappropriate for the given control (i.e. if a
  94     menu item is selected that is not supported by the driver according
  95     to :ref:`VIDIOC_QUERYMENU <VIDIOC_QUERYCTRL>`).
  96
  97 ERANGE
  98     The struct :ref:`v4l2_control <v4l2-control>` ``value`` is out of
  99     bounds.
 100
 101 EBUSY
 102     The control is temporarily not changeable, possibly because another
 103     applications took over control of the device function this control
 104     belongs to.
 105
 106 EACCES
 107     Attempt to set a read-only control or to get a write-only control.