101 lines · plain
1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later2.. c:namespace:: V4L3 4.. _VIDIOC_G_CTRL:5 6**********************************7ioctl VIDIOC_G_CTRL, VIDIOC_S_CTRL8**********************************9 10Name11====12 13VIDIOC_G_CTRL - VIDIOC_S_CTRL - Get or set the value of a control14 15Synopsis16========17 18.. c:macro:: VIDIOC_G_CTRL19 20``int ioctl(int fd, VIDIOC_G_CTRL, struct v4l2_control *argp)``21 22.. c:macro:: VIDIOC_S_CTRL23 24``int ioctl(int fd, VIDIOC_S_CTRL, struct v4l2_control *argp)``25 26Arguments27=========28 29``fd``30 File descriptor returned by :c:func:`open()`.31 32``argp``33 Pointer to struct :c:type:`v4l2_control`.34 35Description36===========37 38To get the current value of a control applications initialize the ``id``39field of a struct :c:type:`v4l2_control` and call the40:ref:`VIDIOC_G_CTRL <VIDIOC_G_CTRL>` ioctl with a pointer to this structure. To change the41value of a control applications initialize the ``id`` and ``value``42fields of a struct :c:type:`v4l2_control` and call the43:ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` ioctl.44 45When the ``id`` is invalid drivers return an ``EINVAL`` error code. When the46``value`` is out of bounds drivers can choose to take the closest valid47value 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 the49actual new value. If the ``value`` is inappropriate for the control50(e.g. if it refers to an unsupported menu index of a menu control), then51EINVAL error code is returned as well.52 53These ioctls work only with user controls. For other control classes the54:ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>`,55:ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` or56:ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` must be used.57 58.. c:type:: v4l2_control59 60.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}|61 62.. flat-table:: struct v4l2_control63 :header-rows: 064 :stub-columns: 065 :widths: 1 1 266 67 * - __u3268 - ``id``69 - Identifies the control, set by the application.70 * - __s3271 - ``value``72 - New value or current value.73 74Return Value75============76 77On success 0 is returned, on error -1 and the ``errno`` variable is set78appropriately. The generic error codes are described at the79:ref:`Generic Error Codes <gen-errors>` chapter.80 81EINVAL82 The struct :c:type:`v4l2_control` ``id`` is invalid83 or the ``value`` is inappropriate for the given control (i.e. if a84 menu item is selected that is not supported by the driver according85 to :ref:`VIDIOC_QUERYMENU <VIDIOC_QUERYCTRL>`).86 87ERANGE88 The struct :c:type:`v4l2_control` ``value`` is out of89 bounds.90 91EBUSY92 The control is temporarily not changeable, possibly because another93 applications took over control of the device function this control94 belongs to.95 96EACCES97 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 is100 not capable of caching the new value until the control is active again.101