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