8e080c2e6c
The V4L and DVB API's are there for a long time. however, up to now, no efforts were done to merge them to kernel DocBook. This patch adds the current versions of the specs as an unique compendium. Signed-off-by: Mauro Carvalho Chehab <mchehab@redhat.com>
146 lines
4.6 KiB
XML
146 lines
4.6 KiB
XML
<refentry id="func-ioctl">
|
|
<refmeta>
|
|
<refentrytitle>V4L2 ioctl()</refentrytitle>
|
|
&manvol;
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>v4l2-ioctl</refname>
|
|
<refpurpose>Program a V4L2 device</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcsynopsisinfo>#include <sys/ioctl.h></funcsynopsisinfo>
|
|
<funcprototype>
|
|
<funcdef>int <function>ioctl</function></funcdef>
|
|
<paramdef>int <parameter>fd</parameter></paramdef>
|
|
<paramdef>int <parameter>request</parameter></paramdef>
|
|
<paramdef>void *<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>V4L2 ioctl request code as defined in the <link
|
|
linkend="videodev">videodev.h</link> header file, for example
|
|
VIDIOC_QUERYCAP.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>argp</parameter></term>
|
|
<listitem>
|
|
<para>Pointer to a function parameter, usually a structure.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Description</title>
|
|
|
|
<para>The <function>ioctl()</function> function is used to program
|
|
V4L2 devices. The argument <parameter>fd</parameter> must be an open
|
|
file descriptor. An ioctl <parameter>request</parameter> has encoded
|
|
in it whether the argument is an input, output or read/write
|
|
parameter, and the size of the argument <parameter>argp</parameter> in
|
|
bytes. Macros and defines specifying V4L2 ioctl requests are located
|
|
in the <link linkend="videodev">videodev.h</link> header file.
|
|
Applications should use their own copy, not include the version in the
|
|
kernel sources on the system they compile on. All V4L2 ioctl requests,
|
|
their respective function and parameters are specified in <xref
|
|
linkend="user-func" />.</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Return Value</title>
|
|
|
|
<para>On success the <function>ioctl()</function> function returns
|
|
<returnvalue>0</returnvalue> and does not reset the
|
|
<varname>errno</varname> variable. On failure
|
|
<returnvalue>-1</returnvalue> is returned, when the ioctl takes an
|
|
output or read/write parameter it remains unmodified, and the
|
|
<varname>errno</varname> variable is set appropriately. See below for
|
|
possible error codes. Generic errors like <errorcode>EBADF</errorcode>
|
|
or <errorcode>EFAULT</errorcode> are not listed in the sections
|
|
discussing individual ioctl requests.</para>
|
|
<para>Note ioctls may return undefined error codes. Since errors
|
|
may have side effects such as a driver reset applications should
|
|
abort on unexpected errors.</para>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><errorcode>EBADF</errorcode></term>
|
|
<listitem>
|
|
<para><parameter>fd</parameter> is not a valid open file
|
|
descriptor.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><errorcode>EBUSY</errorcode></term>
|
|
<listitem>
|
|
<para>The property cannot be changed right now. Typically
|
|
this error code is returned when I/O is in progress or the driver
|
|
supports multiple opens and another process locked the property.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><errorcode>EFAULT</errorcode></term>
|
|
<listitem>
|
|
<para><parameter>argp</parameter> references an inaccessible
|
|
memory area.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><errorcode>ENOTTY</errorcode></term>
|
|
<listitem>
|
|
<para><parameter>fd</parameter> is not associated with a
|
|
character special device.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><errorcode>EINVAL</errorcode></term>
|
|
<listitem>
|
|
<para>The <parameter>request</parameter> or the data pointed
|
|
to by <parameter>argp</parameter> is not valid. This is a very common
|
|
error code, see the individual ioctl requests listed in <xref
|
|
linkend="user-func" /> for actual causes.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><errorcode>ENOMEM</errorcode></term>
|
|
<listitem>
|
|
<para>Not enough physical or virtual memory was available to
|
|
complete the request.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><errorcode>ERANGE</errorcode></term>
|
|
<listitem>
|
|
<para>The application attempted to set a control with the
|
|
&VIDIOC-S-CTRL; ioctl to a value which is out of bounds.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<!--
|
|
Local Variables:
|
|
mode: sgml
|
|
sgml-parent-document: "v4l2.sgml"
|
|
indent-tabs-mode: nil
|
|
End:
|
|
-->
|