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**********************************
  7ioctl VIDIOC_G_CTRL, VIDIOC_S_CTRL
  8**********************************
  9
 10Name
 11====
 12
 13VIDIOC_G_CTRL - VIDIOC_S_CTRL - Get or set the value of a control
 14
 15Synopsis
 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
 26Arguments
 27=========
 28
 29``fd``
 30    File descriptor returned by :c:func:`open()`.
 31
 32``argp``
 33    Pointer to struct :c:type:`v4l2_control`.
 34
 35Description
 36===========
 37
 38To get the current value of a control applications initialize the ``id``
 39field 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
 41value of a control applications initialize the ``id`` and ``value``
 42fields of a struct :c:type:`v4l2_control` and call the
 43:ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` ioctl.
 44
 45When 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
 47value or return an ``ERANGE`` error code, whatever seems more appropriate.
 48However, :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` is a write-only ioctl, it does not return the
 49actual 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
 51EINVAL error code is returned as well.
 52
 53These 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.5cm}|
 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
 74Return Value
 75============
 76
 77On success 0 is returned, on error -1 and the ``errno`` variable is set
 78appropriately. The generic error codes are described at the
 79:ref:`Generic Error Codes <gen-errors>` chapter.
 80
 81EINVAL
 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
 87ERANGE
 88    The struct :c:type:`v4l2_control` ``value`` is out of
 89    bounds.
 90
 91EBUSY
 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
 96EACCES
 97    Attempt to set a read-only control or to get a write-only control.
 98
 99    Or if there is an attempt to set an inactive control and the driver is
100    not capable of caching the new value until the control is active again.