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

   1 .. Permission is granted to copy, distribute and/or modify this
   2 .. document under the terms of the GNU Free Documentation License,
   3 .. Version 1.1 or any later version published by the Free Software
   4 .. Foundation, with no Invariant Sections, no Front-Cover Texts
   5 .. and no Back-Cover Texts. A copy of the license is included at
   6 .. Documentation/media/uapi/fdl-appendix.rst.
   7 ..
   8 .. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
   9
  10 .. _VIDIOC_G_CTRL:
  11
  12 **********************************
  13 ioctl VIDIOC_G_CTRL, VIDIOC_S_CTRL
  14 **********************************
  15
  16 Name
  17 ====
  18
  19 VIDIOC_G_CTRL - VIDIOC_S_CTRL - Get or set the value of a control
  20
  21
  22 Synopsis
  23 ========
  24
  25 .. c:function:: int ioctl( int fd, VIDIOC_G_CTRL, struct v4l2_control *argp )
  26     :name: VIDIOC_G_CTRL
  27
  28 .. c:function:: int ioctl( int fd, VIDIOC_S_CTRL, struct v4l2_control *argp )
  29     :name: VIDIOC_S_CTRL
  30
  31
  32 Arguments
  33 =========
  34
  35 ``fd``
  36     File descriptor returned by :ref:`open() <func-open>`.
  37
  38 ``argp``
  39     Pointer to struct :c:type:`v4l2_control`.
  40
  41
  42 Description
  43 ===========
  44
  45 To get the current value of a control applications initialize the ``id``
  46 field of a struct :c:type:`v4l2_control` and call the
  47 :ref:`VIDIOC_G_CTRL <VIDIOC_G_CTRL>` ioctl with a pointer to this structure. To change the
  48 value of a control applications initialize the ``id`` and ``value``
  49 fields of a struct :c:type:`v4l2_control` and call the
  50 :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` ioctl.
  51
  52 When the ``id`` is invalid drivers return an ``EINVAL`` error code. When the
  53 ``value`` is out of bounds drivers can choose to take the closest valid
  54 value or return an ``ERANGE`` error code, whatever seems more appropriate.
  55 However, :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` is a write-only ioctl, it does not return the
  56 actual new value. If the ``value`` is inappropriate for the control
  57 (e.g. if it refers to an unsupported menu index of a menu control), then
  58 EINVAL error code is returned as well.
  59
  60 These ioctls work only with user controls. For other control classes the
  61 :ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>`,
  62 :ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` or
  63 :ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` must be used.
  64
  65
  66 .. c:type:: v4l2_control
  67
  68 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
  69
  70 .. flat-table:: struct v4l2_control
  71     :header-rows:  0
  72     :stub-columns: 0
  73     :widths:       1 1 2
  74
  75     * - __u32
  76       - ``id``
  77       - Identifies the control, set by the application.
  78     * - __s32
  79       - ``value``
  80       - New value or current value.
  81
  82
  83 Return Value
  84 ============
  85
  86 On success 0 is returned, on error -1 and the ``errno`` variable is set
  87 appropriately. The generic error codes are described at the
  88 :ref:`Generic Error Codes <gen-errors>` chapter.
  89
  90 EINVAL
  91     The struct :c:type:`v4l2_control` ``id`` is invalid
  92     or the ``value`` is inappropriate for the given control (i.e. if a
  93     menu item is selected that is not supported by the driver according
  94     to :ref:`VIDIOC_QUERYMENU <VIDIOC_QUERYCTRL>`).
  95
  96 ERANGE
  97     The struct :c:type:`v4l2_control` ``value`` is out of
  98     bounds.
  99
 100 EBUSY
 101     The control is temporarily not changeable, possibly because another
 102     applications took over control of the device function this control
 103     belongs to.
 104
 105 EACCES
 106     Attempt to set a read-only control or to get a write-only control.