2020-08-26 09:03:09 +02:00
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
2020-09-24 14:04:26 +02:00
.. c:namespace :: V4L
2018-08-30 10:15:26 -04:00
2016-07-01 13:42:29 -03:00
.. _VIDIOC_G_CTRL:
2016-06-30 15:18:56 +02:00
***** ***** ***** ***** ***** ***** *** *
ioctl VIDIOC_G_CTRL, VIDIOC_S_CTRL
***** ***** ***** ***** ***** ***** *** *
2016-07-05 15:14:35 -03:00
Name
2016-07-05 07:58:48 -03:00
====
2016-06-30 15:18:56 +02:00
2016-07-05 07:58:48 -03:00
VIDIOC_G_CTRL - VIDIOC_S_CTRL - Get or set the value of a control
2016-06-30 15:18:56 +02:00
2016-07-05 15:14:35 -03:00
Synopsis
2016-06-30 15:18:56 +02:00
========
2020-09-24 14:04:26 +02:00
.. c:macro :: VIDIOC_G_CTRL
`` int ioctl(int fd, VIDIOC_G_CTRL, struct v4l2_control *argp) ``
2016-08-19 16:53:38 -03:00
2020-09-24 14:04:26 +02:00
.. c:macro :: VIDIOC_S_CTRL
2016-06-30 15:18:56 +02:00
2020-09-24 14:04:26 +02:00
`` int ioctl(int fd, VIDIOC_S_CTRL, struct v4l2_control *argp) ``
2016-07-05 07:58:48 -03:00
2016-07-05 15:14:35 -03:00
Arguments
2016-06-30 15:18:56 +02:00
=========
`` fd ``
2020-09-24 14:04:26 +02:00
File descriptor returned by :c:func: `open()` .
2016-06-30 15:18:56 +02:00
`` argp ``
2017-09-02 09:54:48 -04:00
Pointer to struct :c:type: `v4l2_control` .
2016-06-30 15:18:56 +02:00
2016-07-05 15:14:35 -03:00
Description
2016-06-30 15:18:56 +02:00
===========
To get the current value of a control applications initialize the `` id ``
2016-09-08 05:43:01 -03:00
field of a struct :c:type: `v4l2_control` and call the
2016-07-03 10:02:29 -03:00
:ref: `VIDIOC_G_CTRL <VIDIOC_G_CTRL>` ioctl with a pointer to this structure. To change the
2016-06-30 15:18:56 +02:00
value of a control applications initialize the `` id `` and `` value ``
2016-09-08 05:43:01 -03:00
fields of a struct :c:type: `v4l2_control` and call the
2016-07-01 14:33:56 -03:00
:ref: `VIDIOC_S_CTRL <VIDIOC_G_CTRL>` ioctl.
2016-06-30 15:18:56 +02:00
2016-07-03 11:53:09 -03:00
When the `` id `` is invalid drivers return an `` EINVAL `` error code. When the
2016-06-30 15:18:56 +02:00
`` value `` is out of bounds drivers can choose to take the closest valid
2016-07-03 11:53:09 -03:00
value or return an `` ERANGE `` error code, whatever seems more appropriate.
2016-07-01 14:33:56 -03:00
However, :ref: `VIDIOC_S_CTRL <VIDIOC_G_CTRL>` is a write-only ioctl, it does not return the
2016-06-30 15:18:56 +02:00
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
2016-07-03 10:02:29 -03:00
:ref: `VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` ,
2016-07-01 13:42:29 -03:00
:ref: `VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` or
:ref: `VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` must be used.
2016-06-30 15:18:56 +02:00
2016-08-29 17:37:59 -03:00
.. c:type :: v4l2_control
2016-06-30 15:18:56 +02:00
2020-12-10 11:39:46 +01:00
.. tabularcolumns :: |p{4.4cm}|p{4.4cm}|p{8.5cm}|
[media] docs-rst: add tabularcolumns to all tables
LaTeX doesn't handle too well auto-width on tables, and ReST
markup requires an special tag to give it the needed hints.
As we're using A4 paper, we have 17cm of useful spaces. As
most media tables have widths, let's use it to generate the
needed via the following perl script:
my ($line_size, $table_header, $has_cols) = (17.5, 0, 0);
my $out;
my $header = "";
my @widths = ();
sub round { $_[0] > 0 ? int($_[0] + .5) : -int(-$_[0] + .5) }
while (<>) {
if (!$table_header) {
$has_cols = 1 if (m/..\s+tabularcolumns::/);
if (m/..\s+flat-table::/) {
$table_header = 1;
$header = $_;
next;
}
$out .= $_;
next;
}
$header .= $_;
@widths = split(/ /, $1) if (m/:widths:\s+(.*)/);
if (m/^\n$/) {
if (!$has_cols && @widths) {
my ($tot, $t, $i) = (0, 0, 0);
foreach my $v(@widths) { $tot += $v; };
$out .= ".. tabularcolumns:: |";
for ($i = 0; $i < scalar @widths - 1; $i++) {
my $v = $widths[$i];
my $w = round(10 * ($v * $line_size) / $tot) / 10;
$out .= sprintf "p{%.1fcm}|", $w;
$t += $w;
}
my $w = $line_size - $t;
$out .= sprintf "p{%.1fcm}|\n\n", $w;
}
$out .= $header;
$table_header = 0;
$has_cols = 0;
$header = "";
@widths = ();
}
}
print $out;
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
2016-08-17 08:14:19 -03:00
2016-06-30 15:18:56 +02:00
.. flat-table :: struct v4l2_control
:header-rows: 0
:stub-columns: 0
:widths: 1 1 2
[media] v4l: doc: Remove row numbers from tables
Shorten the tables by removing row numbers in comments, allowing for
later insertion of rows with minimal diffs.
All changes have been generated by the following script.
import io
import re
import sys
def process_table(fname, data):
if fname.endswith('hist-v4l2.rst'):
data = re.sub(u'\n{1,2}\t( ?) -( ?) ?', u'\n\t\\1 -\\2', data, flags = re.MULTILINE)
data = re.sub(u'\n(\t| )- \.\. row [0-9]+\n\t ?-( ?) ?', u'\\1* -\\2', data, flags = re.MULTILINE)
else:
data = re.sub(u'\n{1,2} -( ?) ?', u'\n -\\1', data, flags = re.MULTILINE)
data = re.sub(u'(\n?)(\n\n - \.\. row 1\n)', u'\n\\2', data, flags = re.MULTILINE)
data = re.sub(u'\n - \.\. row [0-9]+\n -( ?) ?', u' * -\\1', data, flags = re.MULTILINE)
data = re.sub(u'\n - \.\. row [0-9]+\n \.\. (_[A-Z0-9_`-]*:)', u'\n - .. \\1', data, flags = re.MULTILINE)
data = re.sub(u'\n - \.\. (_[A-Z0-9_`-]*:)\n -', u' * .. \\1\n\n -', data, flags = re.MULTILINE)
data = re.sub(u'^ - ', u' -', data, flags = re.MULTILINE)
data = re.sub(u'^(\t{1,2}) ', u'\\1', data, flags = re.MULTILINE)
return data
def process_file(fname, data):
buf = io.StringIO(data)
output = ''
in_table = False
table_separator = 0
for line in buf.readlines():
if line.find('.. flat-table::') != -1:
in_table = True
table = ''
elif in_table and not re.match('^[\t\n]|( )', line):
in_table = False
output += process_table(fname, table)
if in_table:
table += line
else:
output += line
if in_table:
in_table = False
output += process_table(fname, table)
return output
fname = sys.argv[1]
data = file(fname, 'rb').read().decode('utf-8')
data = process_file(fname, data)
file(fname, 'wb').write(data.encode('utf-8'))
Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
2016-09-05 08:44:34 -03:00
* - __u32
- `` id ``
- Identifies the control, set by the application.
* - __s32
- `` value ``
- New value or current value.
2016-06-30 15:18:56 +02:00
2016-07-05 15:14:35 -03:00
Return Value
2016-06-30 15:18:56 +02:00
============
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
2016-08-29 17:37:59 -03:00
The struct :c:type: `v4l2_control` `` id `` is invalid
2016-06-30 15:18:56 +02:00
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
2016-07-01 13:42:29 -03:00
to :ref: `VIDIOC_QUERYMENU <VIDIOC_QUERYCTRL>` ).
2016-06-30 15:18:56 +02:00
ERANGE
2016-08-29 17:37:59 -03:00
The struct :c:type: `v4l2_control` `` value `` is out of
2016-06-30 15:18:56 +02:00
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.
