Documentation/linux_tv/media/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 *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
  37 :ref:`VIDIOC_G_CTRL` ioctl with a pointer to this structure. To change the
  38 value of a control applications initialize the ``id`` and ``value``
  39 fields of a struct :c:type:`struct v4l2_control` and call the
  40 :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` ioctl.
  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.
  45 However, :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` is a write-only ioctl, it does not return the
  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
  51 :ref:`VIDIOC_G_EXT_CTRLS`,
  52 :ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` or
  53 :ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` must be used.
  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
  93     to :ref:`VIDIOC_QUERYMENU <VIDIOC_QUERYCTRL>`).
  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 .. ------------------------------------------------------------------------------