1059b1c5bSMauro Carvalho Chehab.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later 2407e84cdSMauro Carvalho Chehab.. c:namespace:: V4L 354f38fcaSMauro Carvalho Chehab 454f38fcaSMauro Carvalho Chehab.. _VIDIOC_G_CTRL: 554f38fcaSMauro Carvalho Chehab 654f38fcaSMauro Carvalho Chehab********************************** 754f38fcaSMauro Carvalho Chehabioctl VIDIOC_G_CTRL, VIDIOC_S_CTRL 854f38fcaSMauro Carvalho Chehab********************************** 954f38fcaSMauro Carvalho Chehab 1054f38fcaSMauro Carvalho ChehabName 1154f38fcaSMauro Carvalho Chehab==== 1254f38fcaSMauro Carvalho Chehab 1354f38fcaSMauro Carvalho ChehabVIDIOC_G_CTRL - VIDIOC_S_CTRL - Get or set the value of a control 1454f38fcaSMauro Carvalho Chehab 1554f38fcaSMauro Carvalho ChehabSynopsis 1654f38fcaSMauro Carvalho Chehab======== 1754f38fcaSMauro Carvalho Chehab 18407e84cdSMauro Carvalho Chehab.. c:macro:: VIDIOC_G_CTRL 1954f38fcaSMauro Carvalho Chehab 20407e84cdSMauro Carvalho Chehab``int ioctl(int fd, VIDIOC_G_CTRL, struct v4l2_control *argp)`` 2154f38fcaSMauro Carvalho Chehab 22407e84cdSMauro Carvalho Chehab.. c:macro:: VIDIOC_S_CTRL 23407e84cdSMauro Carvalho Chehab 24407e84cdSMauro Carvalho Chehab``int ioctl(int fd, VIDIOC_S_CTRL, struct v4l2_control *argp)`` 2554f38fcaSMauro Carvalho Chehab 2654f38fcaSMauro Carvalho ChehabArguments 2754f38fcaSMauro Carvalho Chehab========= 2854f38fcaSMauro Carvalho Chehab 2954f38fcaSMauro Carvalho Chehab``fd`` 30407e84cdSMauro Carvalho Chehab File descriptor returned by :c:func:`open()`. 3154f38fcaSMauro Carvalho Chehab 3254f38fcaSMauro Carvalho Chehab``argp`` 3354f38fcaSMauro Carvalho Chehab Pointer to struct :c:type:`v4l2_control`. 3454f38fcaSMauro Carvalho Chehab 3554f38fcaSMauro Carvalho ChehabDescription 3654f38fcaSMauro Carvalho Chehab=========== 3754f38fcaSMauro Carvalho Chehab 3854f38fcaSMauro Carvalho ChehabTo get the current value of a control applications initialize the ``id`` 3954f38fcaSMauro Carvalho Chehabfield of a struct :c:type:`v4l2_control` and call the 4054f38fcaSMauro Carvalho Chehab:ref:`VIDIOC_G_CTRL <VIDIOC_G_CTRL>` ioctl with a pointer to this structure. To change the 4154f38fcaSMauro Carvalho Chehabvalue of a control applications initialize the ``id`` and ``value`` 4254f38fcaSMauro Carvalho Chehabfields of a struct :c:type:`v4l2_control` and call the 4354f38fcaSMauro Carvalho Chehab:ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` ioctl. 4454f38fcaSMauro Carvalho Chehab 4554f38fcaSMauro Carvalho ChehabWhen the ``id`` is invalid drivers return an ``EINVAL`` error code. When the 4654f38fcaSMauro Carvalho Chehab``value`` is out of bounds drivers can choose to take the closest valid 4754f38fcaSMauro Carvalho Chehabvalue or return an ``ERANGE`` error code, whatever seems more appropriate. 4854f38fcaSMauro Carvalho ChehabHowever, :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` is a write-only ioctl, it does not return the 4954f38fcaSMauro Carvalho Chehabactual new value. If the ``value`` is inappropriate for the control 5054f38fcaSMauro Carvalho Chehab(e.g. if it refers to an unsupported menu index of a menu control), then 5154f38fcaSMauro Carvalho ChehabEINVAL error code is returned as well. 5254f38fcaSMauro Carvalho Chehab 5354f38fcaSMauro Carvalho ChehabThese ioctls work only with user controls. For other control classes the 5454f38fcaSMauro Carvalho Chehab:ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>`, 5554f38fcaSMauro Carvalho Chehab:ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` or 5654f38fcaSMauro Carvalho Chehab:ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` must be used. 5754f38fcaSMauro Carvalho Chehab 5854f38fcaSMauro Carvalho Chehab.. c:type:: v4l2_control 5954f38fcaSMauro Carvalho Chehab 60fea13a69SMauro Carvalho Chehab.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| 6154f38fcaSMauro Carvalho Chehab 6254f38fcaSMauro Carvalho Chehab.. flat-table:: struct v4l2_control 6354f38fcaSMauro Carvalho Chehab :header-rows: 0 6454f38fcaSMauro Carvalho Chehab :stub-columns: 0 6554f38fcaSMauro Carvalho Chehab :widths: 1 1 2 6654f38fcaSMauro Carvalho Chehab 6754f38fcaSMauro Carvalho Chehab * - __u32 6854f38fcaSMauro Carvalho Chehab - ``id`` 6954f38fcaSMauro Carvalho Chehab - Identifies the control, set by the application. 7054f38fcaSMauro Carvalho Chehab * - __s32 7154f38fcaSMauro Carvalho Chehab - ``value`` 7254f38fcaSMauro Carvalho Chehab - New value or current value. 7354f38fcaSMauro Carvalho Chehab 7454f38fcaSMauro Carvalho ChehabReturn Value 7554f38fcaSMauro Carvalho Chehab============ 7654f38fcaSMauro Carvalho Chehab 7754f38fcaSMauro Carvalho ChehabOn success 0 is returned, on error -1 and the ``errno`` variable is set 7854f38fcaSMauro Carvalho Chehabappropriately. The generic error codes are described at the 7954f38fcaSMauro Carvalho Chehab:ref:`Generic Error Codes <gen-errors>` chapter. 8054f38fcaSMauro Carvalho Chehab 8154f38fcaSMauro Carvalho ChehabEINVAL 8254f38fcaSMauro Carvalho Chehab The struct :c:type:`v4l2_control` ``id`` is invalid 8354f38fcaSMauro Carvalho Chehab or the ``value`` is inappropriate for the given control (i.e. if a 8454f38fcaSMauro Carvalho Chehab menu item is selected that is not supported by the driver according 8554f38fcaSMauro Carvalho Chehab to :ref:`VIDIOC_QUERYMENU <VIDIOC_QUERYCTRL>`). 8654f38fcaSMauro Carvalho Chehab 8754f38fcaSMauro Carvalho ChehabERANGE 8854f38fcaSMauro Carvalho Chehab The struct :c:type:`v4l2_control` ``value`` is out of 8954f38fcaSMauro Carvalho Chehab bounds. 9054f38fcaSMauro Carvalho Chehab 9154f38fcaSMauro Carvalho ChehabEBUSY 9254f38fcaSMauro Carvalho Chehab The control is temporarily not changeable, possibly because another 9354f38fcaSMauro Carvalho Chehab applications took over control of the device function this control 9454f38fcaSMauro Carvalho Chehab belongs to. 9554f38fcaSMauro Carvalho Chehab 9654f38fcaSMauro Carvalho ChehabEACCES 9754f38fcaSMauro Carvalho Chehab Attempt to set a read-only control or to get a write-only control. 98*8c426941SRicardo Ribalda 99*8c426941SRicardo Ribalda Or if there is an attempt to set an inactive control and the driver is 100*8c426941SRicardo Ribalda not capable of caching the new value until the control is active again. 101