00b230fe23
The documentation suggested that if the control value is wrong only ERANGE can be returned. But in some cases (an invalid menu index) EINVAL can also be returned. Clarify this. Signed-off-by: Hans Verkuil <hans.verkuil@cisco.com> Signed-off-by: Mauro Carvalho Chehab <mchehab@redhat.com>
134 lines
4.0 KiB
XML
134 lines
4.0 KiB
XML
<refentry id="vidioc-g-ctrl">
|
|
<refmeta>
|
|
<refentrytitle>ioctl VIDIOC_G_CTRL, VIDIOC_S_CTRL</refentrytitle>
|
|
&manvol;
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>VIDIOC_G_CTRL</refname>
|
|
<refname>VIDIOC_S_CTRL</refname>
|
|
<refpurpose>Get or set the value of a control</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>int <function>ioctl</function></funcdef>
|
|
<paramdef>int <parameter>fd</parameter></paramdef>
|
|
<paramdef>int <parameter>request</parameter></paramdef>
|
|
<paramdef>struct v4l2_control
|
|
*<parameter>argp</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1>
|
|
<title>Arguments</title>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><parameter>fd</parameter></term>
|
|
<listitem>
|
|
<para>&fd;</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>request</parameter></term>
|
|
<listitem>
|
|
<para>VIDIOC_G_CTRL, VIDIOC_S_CTRL</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>argp</parameter></term>
|
|
<listitem>
|
|
<para></para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Description</title>
|
|
|
|
<para>To get the current value of a control applications
|
|
initialize the <structfield>id</structfield> field of a struct
|
|
<structname>v4l2_control</structname> and call the
|
|
<constant>VIDIOC_G_CTRL</constant> ioctl with a pointer to this
|
|
structure. To change the value of a control applications initialize
|
|
the <structfield>id</structfield> and <structfield>value</structfield>
|
|
fields of a struct <structname>v4l2_control</structname> and call the
|
|
<constant>VIDIOC_S_CTRL</constant> ioctl.</para>
|
|
|
|
<para>When the <structfield>id</structfield> is invalid drivers
|
|
return an &EINVAL;. When the <structfield>value</structfield> is out
|
|
of bounds drivers can choose to take the closest valid value or return
|
|
an &ERANGE;, whatever seems more appropriate. However,
|
|
<constant>VIDIOC_S_CTRL</constant> is a write-only ioctl, it does not
|
|
return the actual new value. If the <structfield>value</structfield>
|
|
is inappropriate for the control (e.g. if it refers to an unsupported
|
|
menu index of a menu control), then &EINVAL; is returned as well.</para>
|
|
|
|
<para>These ioctls work only with user controls. For other
|
|
control classes the &VIDIOC-G-EXT-CTRLS;, &VIDIOC-S-EXT-CTRLS; or
|
|
&VIDIOC-TRY-EXT-CTRLS; must be used.</para>
|
|
|
|
<table pgwide="1" frame="none" id="v4l2-control">
|
|
<title>struct <structname>v4l2_control</structname></title>
|
|
<tgroup cols="3">
|
|
&cs-str;
|
|
<tbody valign="top">
|
|
<row>
|
|
<entry>__u32</entry>
|
|
<entry><structfield>id</structfield></entry>
|
|
<entry>Identifies the control, set by the
|
|
application.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>__s32</entry>
|
|
<entry><structfield>value</structfield></entry>
|
|
<entry>New value or current value.</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
&return-value;
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><errorcode>EINVAL</errorcode></term>
|
|
<listitem>
|
|
<para>The &v4l2-control; <structfield>id</structfield> is
|
|
invalid or the <structfield>value</structfield> is inappropriate for
|
|
the given control (i.e. if a menu item is selected that is not supported
|
|
by the driver according to &VIDIOC-QUERYMENU;).</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><errorcode>ERANGE</errorcode></term>
|
|
<listitem>
|
|
<para>The &v4l2-control; <structfield>value</structfield>
|
|
is out of bounds.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><errorcode>EBUSY</errorcode></term>
|
|
<listitem>
|
|
<para>The control is temporarily not changeable, possibly
|
|
because another applications took over control of the device function
|
|
this control belongs to.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><errorcode>EACCES</errorcode></term>
|
|
<listitem>
|
|
<para>Attempt to set a read-only control or to get a
|
|
write-only control.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect1>
|
|
</refentry>
|