[media] DocBook: mention that EINVAL can be returned for invalid menu indices
authorHans Verkuil <hans.verkuil@cisco.com>
Fri, 11 Jan 2013 13:49:12 +0000 (10:49 -0300)
committerMauro Carvalho Chehab <mchehab@redhat.com>
Wed, 6 Feb 2013 10:12:57 +0000 (08:12 -0200)
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>
Documentation/DocBook/media/v4l/vidioc-g-ctrl.xml
Documentation/DocBook/media/v4l/vidioc-g-ext-ctrls.xml

index 12b1d0503e261ecabd76c370b8d6498306535ac4..ee2820d6ca66f990d408cc11d9087f9dfe1b8842 100644 (file)
@@ -64,7 +64,9 @@ 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.</para>
+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
@@ -99,7 +101,9 @@ application.</entry>
        <term><errorcode>EINVAL</errorcode></term>
        <listitem>
          <para>The &v4l2-control; <structfield>id</structfield> is
-invalid.</para>
+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>
index 42ffbff6d37ef42e985425f6435ea0ca0afda749..4e16112df99234ca1848ad58e2e37b90ddfc181b 100644 (file)
@@ -106,7 +106,9 @@ value or if an error is returned.</para>
 &EINVAL;. When the value is out of bounds drivers can choose to take
 the closest valid value or return an &ERANGE;, whatever seems more
 appropriate. In the first case the new value is set in
-&v4l2-ext-control;.</para>
+&v4l2-ext-control;. If the new control value is inappropriate (e.g. the
+given menu index is not supported by the menu control), then this will
+also result in an &EINVAL; error.</para>
 
     <para>The driver will only set/get these controls if all control
 values are correct. This prevents the situation where only some of the
@@ -331,8 +333,10 @@ These controls are described in <xref
        <term><errorcode>EINVAL</errorcode></term>
        <listitem>
          <para>The &v4l2-ext-control; <structfield>id</structfield>
-is invalid or the &v4l2-ext-controls;
-<structfield>ctrl_class</structfield> is invalid. This error code is
+is invalid, the &v4l2-ext-controls;
+<structfield>ctrl_class</structfield> is invalid, or the &v4l2-ext-control;
+<structfield>value</structfield> was inappropriate (e.g. the given menu
+index is not supported by the driver). This error code is
 also returned by the <constant>VIDIOC_S_EXT_CTRLS</constant> and
 <constant>VIDIOC_TRY_EXT_CTRLS</constant> ioctls if two or more
 control values are in conflict.</para>