Documentation/userspace-api/media/v4l/vidioc-g-ctrl.rst

   1 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
   2 .. c:namespace:: V4L
   3
   4 .. _VIDIOC_G_CTRL:
   5
   6 **********************************
   7 ioctl VIDIOC_G_CTRL, VIDIOC_S_CTRL
   8 **********************************
   9
  10 Name
  11 ====
  12
  13 VIDIOC_G_CTRL - VIDIOC_S_CTRL - Get or set the value of a control
  14
  15 Synopsis
  16 ========
  17
  18 .. c:macro:: VIDIOC_G_CTRL
  19
  20 ``int ioctl(int fd, VIDIOC_G_CTRL, struct v4l2_control *argp)``
  21
  22 .. c:macro:: VIDIOC_S_CTRL
  23
  24 ``int ioctl(int fd, VIDIOC_S_CTRL, struct v4l2_control *argp)``
  25
  26 Arguments
  27 =========
  28
  29 ``fd``
  30     File descriptor returned by :c:func:`open()`.
  31
  32 ``argp``
  33     Pointer to struct :c:type:`v4l2_control`.
  34
  35 Description
  36 ===========
  37
  38 To get the current value of a control applications initialize the ``id``
  39 field of a struct :c:type:`v4l2_control` and call the
  40 :ref:`VIDIOC_G_CTRL <VIDIOC_G_CTRL>` ioctl with a pointer to this structure. To change the
  41 value of a control applications initialize the ``id`` and ``value``
  42 fields of a struct :c:type:`v4l2_control` and call the
  43 :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` ioctl.
  44
  45 When the ``id`` is invalid drivers return an ``EINVAL`` error code. When the
  46 ``value`` is out of bounds drivers can choose to take the closest valid
  47 value or return an ``ERANGE`` error code, whatever seems more appropriate.
  48 However, :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` is a write-only ioctl, it does not return the
  49 actual new value. If the ``value`` is inappropriate for the control
  50 (e.g. if it refers to an unsupported menu index of a menu control), then
  51 EINVAL error code is returned as well.
  52
  53 These ioctls work only with user controls. For other control classes the
  54 :ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>`,
  55 :ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` or
  56 :ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` must be used.
  57
  58 .. c:type:: 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     * - __u32
  68       - ``id``
  69       - Identifies the control, set by the application.
  70     * - __s32
  71       - ``value``
  72       - New value or current value.
  73
  74 Return Value
  75 ============
  76
  77 On success 0 is returned, on error -1 and the ``errno`` variable is set
  78 appropriately. The generic error codes are described at the
  79 :ref:`Generic Error Codes <gen-errors>` chapter.
  80
  81 EINVAL
  82     The struct :c:type:`v4l2_control` ``id`` is invalid
  83     or the ``value`` is inappropriate for the given control (i.e. if a
  84     menu item is selected that is not supported by the driver according
  85     to :ref:`VIDIOC_QUERYMENU <VIDIOC_QUERYCTRL>`).
  86
  87 ERANGE
  88     The struct :c:type:`v4l2_control` ``value`` is out of
  89     bounds.
  90
  91 EBUSY
  92     The control is temporarily not changeable, possibly because another
  93     applications took over control of the device function this control
  94     belongs to.
  95
  96 EACCES
  97     Attempt to set a read-only control or to get a write-only control.