요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
1
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
2
.. c:namespace:: V4L
4
.. _VIDIOC_G_CTRL:
6
**********************************
7
ioctl VIDIOC_G_CTRL, VIDIOC_S_CTRL
8
**********************************
10
Name
11
====
13
VIDIOC_G_CTRL - VIDIOC_S_CTRL - Get or set the value of a control
15
Synopsis
16
========
18
.. c:macro:: VIDIOC_G_CTRL
20
``int ioctl(int fd, VIDIOC_G_CTRL, struct v4l2_control *argp)``
22
.. c:macro:: VIDIOC_S_CTRL
24
``int ioctl(int fd, VIDIOC_S_CTRL, struct v4l2_control *argp)``
26
Arguments
27
=========
29
``fd``
30
File descriptor returned by :c:func:`open()`.
32
``argp``
33
Pointer to struct :c:type:`v4l2_control`.
35
Description
36
===========
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.
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.
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.
58
.. c:type:: v4l2_control
60
.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}|
62
.. flat-table:: struct v4l2_control
63
:header-rows: 0
64
:stub-columns: 0
65
:widths: 1 1 2
67
* - __u32
68
- ``id``
69
- Identifies the control, set by the application.
70
* - __s32
71
- ``value``
72
- New value or current value.
74
Return Value
75
============
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.
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>`).
87
ERANGE
88
The struct :c:type:`v4l2_control` ``value`` is out of
89
bounds.
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.
96
EACCES
97
Attempt to set a read-only control or to get a write-only control.
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.
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
목적, 호출 형식과 인자
1-34`VIDIOC_G_CTRL`은 control의 현재 값을 조회하고, `VIDIOC_S_CTRL`은 control 값을 설정하는 ioctl입니다.
두 명령 모두 `struct v4l2_control *argp`를 받습니다. 조회 형식은 `int ioctl(int fd, VIDIOC_G_CTRL, struct v4l2_control *argp)`, 설정 형식은 두 번째 인자가 `VIDIOC_S_CTRL`입니다.
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
.. c:namespace:: V4L
.. _VIDIOC_G_CTRL:
**********************************
ioctl VIDIOC_G_CTRL, VIDIOC_S_CTRL
**********************************
Name
====
VIDIOC_G_CTRL - VIDIOC_S_CTRL - Get or set the value of a control
Synopsis
========
.. c:macro:: VIDIOC_G_CTRL
``int ioctl(int fd, VIDIOC_G_CTRL, struct v4l2_control *argp)``
.. c:macro:: VIDIOC_S_CTRL
``int ioctl(int fd, VIDIOC_S_CTRL, struct v4l2_control *argp)``
Arguments
=========
``fd``
File descriptor returned by :c:func:`open()`.
``argp``
Pointer to struct :c:type:`v4l2_control`.
Control 값 조회·설정 규칙
35-57현재 값을 얻으려면 `v4l2_control.id`를 초기화해 `VIDIOC_G_CTRL`을 호출합니다. 값을 바꾸려면 `id`와 `value`를 설정해 `VIDIOC_S_CTRL`을 호출합니다.
`id`가 유효하지 않으면 `EINVAL`입니다. `value`가 범위를 벗어나면 드라이버는 상황에 따라 가장 가까운 유효값을 선택하거나 `ERANGE`를 반환할 수 있습니다.
`VIDIOC_S_CTRL`은 write-only이므로 clamp되거나 다른 값이 적용되어도 실제 새 값을 구조체에 반환하지 않습니다. 결과가 필요하면 다시 조회해야 합니다.
control에 부적절한 값, 예를 들어 menu control에서 지원하지 않는 menu index를 지정하면 `EINVAL`을 반환합니다.
이 두 ioctl은 user control에만 동작합니다. 다른 control class에는 `VIDIOC_G_EXT_CTRLS`, `VIDIOC_S_EXT_CTRLS`, `VIDIOC_TRY_EXT_CTRLS`를 사용해야 합니다.
control id 선택→G_CTRL로 현재 value 조회→새 id·value 설정→S_CTRL 호출→driver clamp 또는 오류 처리→필요하면 G_CTRL로 결과 재조회
단일 user control을 식별하고 값을 적용하는 흐름입니다.
Description
===========
To get the current value of a control applications initialize the ``id``
field of a struct :c:type:`v4l2_control` and call the
:ref:`VIDIOC_G_CTRL <VIDIOC_G_CTRL>` ioctl with a pointer to this structure. To change the
value of a control applications initialize the ``id`` and ``value``
fields of a struct :c:type:`v4l2_control` and call the
:ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` ioctl.
When the ``id`` is invalid drivers return an ``EINVAL`` error code. When the
``value`` is out of bounds drivers can choose to take the closest valid
value or return an ``ERANGE`` error code, whatever seems more appropriate.
However, :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` is a write-only ioctl, it does not return the
actual new value. If the ``value`` is inappropriate for the control
(e.g. if it refers to an unsupported menu index of a menu control), then
EINVAL error code is returned as well.
These ioctls work only with user controls. For other control classes the
:ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>`,
:ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` or
:ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` must be used.
v4l2_control 구조체
58-73형식필드의미
`__u32``id`응용 프로그램이 설정하는 control 식별자
`__s32``value`설정할 새 값 또는 조회된 현재 값
단일 user control의 식별자와 값입니다.
`id`는 항상 응용 프로그램의 입력입니다. `value`는 G_CTRL에서는 출력, S_CTRL에서는 입력이지만 S_CTRL 성공 후 실제 적용값을 뜻하지는 않습니다.
.. c:type:: v4l2_control
.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}|
.. flat-table:: struct v4l2_control
:header-rows: 0
:stub-columns: 0
:widths: 1 1 2
* - __u32
- ``id``
- Identifies the control, set by the application.
* - __s32
- ``value``
- New value or current value.
반환값과 오류 조건
74-100성공하면 0을 반환합니다. 오류가 발생하면 -1을 반환하고 `errno`를 설정하며, 공통 오류 코드는 Generic Error Codes 장을 따릅니다.
errno조건
`EINVAL``id`가 유효하지 않거나, `VIDIOC_QUERYMENU` 기준으로 driver가 지원하지 않는 menu item처럼 control에 부적절한 `value`
`ERANGE``value`가 control 범위를 벗어남
`EBUSY`다른 응용 프로그램이 관련 device function을 제어하는 등 control을 일시적으로 변경할 수 없음
`EACCES`read-only control 설정, write-only control 조회, 또는 driver가 값을 cache할 수 없는 inactive control 설정 시도
control 식별자·값·현재 상태·접근 권한에 따른 오류입니다.
inactive control 설정에서 `EACCES`가 발생하는 조건은 driver가 control이 다시 active가 될 때까지 새 값을 cache할 능력이 없는 경우입니다.
Return Value
============
On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
EINVAL
The struct :c:type:`v4l2_control` ``id`` is invalid
or the ``value`` is inappropriate for the given control (i.e. if a
menu item is selected that is not supported by the driver according
to :ref:`VIDIOC_QUERYMENU <VIDIOC_QUERYCTRL>`).
ERANGE
The struct :c:type:`v4l2_control` ``value`` is out of
bounds.
EBUSY
The control is temporarily not changeable, possibly because another
applications took over control of the device function this control
belongs to.
EACCES
Attempt to set a read-only control or to get a write-only control.
Or if there is an attempt to set an inactive control and the driver is
not capable of caching the new value until the control is active again.
요약·해설
vidioc-g-ctrl.rst:1-100단일 V4L2 user control 값을 조회·설정하고 clamp, extended controls 선택 기준과 EINVAL·ERANGE·EBUSY·EACCES 조건을 설명합니다.