Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 1 | .. -*- coding: utf-8; mode: rst -*- |
| 2 | |
| 3 | .. _vidioc-g-ctrl: |
| 4 | |
| 5 | ********************************** |
| 6 | ioctl VIDIOC_G_CTRL, VIDIOC_S_CTRL |
| 7 | ********************************** |
| 8 | |
| 9 | *man VIDIOC_G_CTRL(2)* |
| 10 | |
| 11 | VIDIOC_S_CTRL |
| 12 | Get or set the value of a control |
| 13 | |
| 14 | |
| 15 | Synopsis |
| 16 | ======== |
| 17 | |
| 18 | .. c:function:: int ioctl( int fd, int request, struct v4l2_control *argp ) |
| 19 | |
| 20 | Arguments |
| 21 | ========= |
| 22 | |
| 23 | ``fd`` |
| 24 | File descriptor returned by :ref:`open() <func-open>`. |
| 25 | |
| 26 | ``request`` |
| 27 | VIDIOC_G_CTRL, VIDIOC_S_CTRL |
| 28 | |
| 29 | ``argp`` |
| 30 | |
| 31 | |
| 32 | Description |
| 33 | =========== |
| 34 | |
| 35 | To get the current value of a control applications initialize the ``id`` |
| 36 | field of a struct :c:type:`struct v4l2_control` and call the |
| 37 | ``VIDIOC_G_CTRL`` ioctl with a pointer to this structure. To change the |
| 38 | value of a control applications initialize the ``id`` and ``value`` |
| 39 | fields of a struct :c:type:`struct v4l2_control` and call the |
| 40 | ``VIDIOC_S_CTRL`` ioctl. |
| 41 | |
| 42 | When the ``id`` is invalid drivers return an EINVAL error code. When the |
| 43 | ``value`` is out of bounds drivers can choose to take the closest valid |
| 44 | value or return an ERANGE error code, whatever seems more appropriate. |
| 45 | However, ``VIDIOC_S_CTRL`` is a write-only ioctl, it does not return the |
| 46 | actual new value. If the ``value`` is inappropriate for the control |
| 47 | (e.g. if it refers to an unsupported menu index of a menu control), then |
| 48 | EINVAL error code is returned as well. |
| 49 | |
| 50 | These ioctls work only with user controls. For other control classes the |
| 51 | :ref:`VIDIOC_G_EXT_CTRLS <vidioc-g-ext-ctrls>`, |
| 52 | :ref:`VIDIOC_S_EXT_CTRLS <vidioc-g-ext-ctrls>` or |
| 53 | :ref:`VIDIOC_TRY_EXT_CTRLS <vidioc-g-ext-ctrls>` must be used. |
| 54 | |
| 55 | |
| 56 | .. _v4l2-control: |
| 57 | |
| 58 | .. flat-table:: struct v4l2_control |
| 59 | :header-rows: 0 |
| 60 | :stub-columns: 0 |
| 61 | :widths: 1 1 2 |
| 62 | |
| 63 | |
| 64 | - .. row 1 |
| 65 | |
| 66 | - __u32 |
| 67 | |
| 68 | - ``id`` |
| 69 | |
| 70 | - Identifies the control, set by the application. |
| 71 | |
| 72 | - .. row 2 |
| 73 | |
| 74 | - __s32 |
| 75 | |
| 76 | - ``value`` |
| 77 | |
| 78 | - New value or current value. |
| 79 | |
| 80 | |
| 81 | |
| 82 | Return Value |
| 83 | ============ |
| 84 | |
| 85 | On success 0 is returned, on error -1 and the ``errno`` variable is set |
| 86 | appropriately. The generic error codes are described at the |
| 87 | :ref:`Generic Error Codes <gen-errors>` chapter. |
| 88 | |
| 89 | EINVAL |
| 90 | The struct :ref:`v4l2_control <v4l2-control>` ``id`` is invalid |
| 91 | or the ``value`` is inappropriate for the given control (i.e. if a |
| 92 | menu item is selected that is not supported by the driver according |
| 93 | to :ref:`VIDIOC_QUERYMENU <vidioc-queryctrl>`). |
| 94 | |
| 95 | ERANGE |
| 96 | The struct :ref:`v4l2_control <v4l2-control>` ``value`` is out of |
| 97 | bounds. |
| 98 | |
| 99 | EBUSY |
| 100 | The control is temporarily not changeable, possibly because another |
| 101 | applications took over control of the device function this control |
| 102 | belongs to. |
| 103 | |
| 104 | EACCES |
| 105 | Attempt to set a read-only control or to get a write-only control. |
| 106 | |
| 107 | |
| 108 | .. ------------------------------------------------------------------------------ |
| 109 | .. This file was automatically converted from DocBook-XML with the dbxml |
| 110 | .. library (https://github.com/return42/sphkerneldoc). The origin XML comes |
| 111 | .. from the linux kernel, refer to: |
| 112 | .. |
| 113 | .. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook |
| 114 | .. ------------------------------------------------------------------------------ |