Mauro Carvalho Chehab | 8e080c2 | 2009-09-13 22:16:04 -0300 | [diff] [blame] | 1 | <refentry id="func-ioctl"> |
| 2 | <refmeta> |
| 3 | <refentrytitle>V4L2 ioctl()</refentrytitle> |
| 4 | &manvol; |
| 5 | </refmeta> |
| 6 | |
| 7 | <refnamediv> |
| 8 | <refname>v4l2-ioctl</refname> |
| 9 | <refpurpose>Program a V4L2 device</refpurpose> |
| 10 | </refnamediv> |
| 11 | |
| 12 | <refsynopsisdiv> |
| 13 | <funcsynopsis> |
| 14 | <funcsynopsisinfo>#include <sys/ioctl.h></funcsynopsisinfo> |
| 15 | <funcprototype> |
| 16 | <funcdef>int <function>ioctl</function></funcdef> |
| 17 | <paramdef>int <parameter>fd</parameter></paramdef> |
| 18 | <paramdef>int <parameter>request</parameter></paramdef> |
| 19 | <paramdef>void *<parameter>argp</parameter></paramdef> |
| 20 | </funcprototype> |
| 21 | </funcsynopsis> |
| 22 | </refsynopsisdiv> |
| 23 | |
| 24 | <refsect1> |
| 25 | <title>Arguments</title> |
| 26 | |
| 27 | <variablelist> |
| 28 | <varlistentry> |
| 29 | <term><parameter>fd</parameter></term> |
| 30 | <listitem> |
| 31 | <para>&fd;</para> |
| 32 | </listitem> |
| 33 | </varlistentry> |
| 34 | <varlistentry> |
| 35 | <term><parameter>request</parameter></term> |
| 36 | <listitem> |
| 37 | <para>V4L2 ioctl request code as defined in the <link |
| 38 | linkend="videodev">videodev.h</link> header file, for example |
| 39 | VIDIOC_QUERYCAP.</para> |
| 40 | </listitem> |
| 41 | </varlistentry> |
| 42 | <varlistentry> |
| 43 | <term><parameter>argp</parameter></term> |
| 44 | <listitem> |
| 45 | <para>Pointer to a function parameter, usually a structure.</para> |
| 46 | </listitem> |
| 47 | </varlistentry> |
| 48 | </variablelist> |
| 49 | </refsect1> |
| 50 | |
| 51 | <refsect1> |
| 52 | <title>Description</title> |
| 53 | |
| 54 | <para>The <function>ioctl()</function> function is used to program |
| 55 | V4L2 devices. The argument <parameter>fd</parameter> must be an open |
| 56 | file descriptor. An ioctl <parameter>request</parameter> has encoded |
| 57 | in it whether the argument is an input, output or read/write |
| 58 | parameter, and the size of the argument <parameter>argp</parameter> in |
| 59 | bytes. Macros and defines specifying V4L2 ioctl requests are located |
| 60 | in the <link linkend="videodev">videodev.h</link> header file. |
| 61 | Applications should use their own copy, not include the version in the |
| 62 | kernel sources on the system they compile on. All V4L2 ioctl requests, |
| 63 | their respective function and parameters are specified in <xref |
| 64 | linkend="user-func" />.</para> |
| 65 | </refsect1> |
| 66 | |
| 67 | <refsect1> |
| 68 | <title>Return Value</title> |
| 69 | |
| 70 | <para>On success the <function>ioctl()</function> function returns |
| 71 | <returnvalue>0</returnvalue> and does not reset the |
| 72 | <varname>errno</varname> variable. On failure |
| 73 | <returnvalue>-1</returnvalue> is returned, when the ioctl takes an |
| 74 | output or read/write parameter it remains unmodified, and the |
| 75 | <varname>errno</varname> variable is set appropriately. See below for |
| 76 | possible error codes. Generic errors like <errorcode>EBADF</errorcode> |
| 77 | or <errorcode>EFAULT</errorcode> are not listed in the sections |
| 78 | discussing individual ioctl requests.</para> |
| 79 | <para>Note ioctls may return undefined error codes. Since errors |
| 80 | may have side effects such as a driver reset applications should |
| 81 | abort on unexpected errors.</para> |
| 82 | |
| 83 | <variablelist> |
| 84 | <varlistentry> |
| 85 | <term><errorcode>EBADF</errorcode></term> |
| 86 | <listitem> |
| 87 | <para><parameter>fd</parameter> is not a valid open file |
| 88 | descriptor.</para> |
| 89 | </listitem> |
| 90 | </varlistentry> |
| 91 | <varlistentry> |
| 92 | <term><errorcode>EBUSY</errorcode></term> |
| 93 | <listitem> |
| 94 | <para>The property cannot be changed right now. Typically |
| 95 | this error code is returned when I/O is in progress or the driver |
| 96 | supports multiple opens and another process locked the property.</para> |
| 97 | </listitem> |
| 98 | </varlistentry> |
| 99 | <varlistentry> |
| 100 | <term><errorcode>EFAULT</errorcode></term> |
| 101 | <listitem> |
| 102 | <para><parameter>argp</parameter> references an inaccessible |
| 103 | memory area.</para> |
| 104 | </listitem> |
| 105 | </varlistentry> |
| 106 | <varlistentry> |
| 107 | <term><errorcode>ENOTTY</errorcode></term> |
| 108 | <listitem> |
| 109 | <para><parameter>fd</parameter> is not associated with a |
| 110 | character special device.</para> |
| 111 | </listitem> |
| 112 | </varlistentry> |
| 113 | <varlistentry> |
| 114 | <term><errorcode>EINVAL</errorcode></term> |
| 115 | <listitem> |
| 116 | <para>The <parameter>request</parameter> or the data pointed |
| 117 | to by <parameter>argp</parameter> is not valid. This is a very common |
| 118 | error code, see the individual ioctl requests listed in <xref |
| 119 | linkend="user-func" /> for actual causes.</para> |
| 120 | </listitem> |
| 121 | </varlistentry> |
| 122 | <varlistentry> |
| 123 | <term><errorcode>ENOMEM</errorcode></term> |
| 124 | <listitem> |
| 125 | <para>Not enough physical or virtual memory was available to |
| 126 | complete the request.</para> |
| 127 | </listitem> |
| 128 | </varlistentry> |
| 129 | <varlistentry> |
| 130 | <term><errorcode>ERANGE</errorcode></term> |
| 131 | <listitem> |
| 132 | <para>The application attempted to set a control with the |
| 133 | &VIDIOC-S-CTRL; ioctl to a value which is out of bounds.</para> |
| 134 | </listitem> |
| 135 | </varlistentry> |
| 136 | </variablelist> |
| 137 | </refsect1> |
| 138 | </refentry> |
| 139 | |
| 140 | <!-- |
| 141 | Local Variables: |
| 142 | mode: sgml |
| 143 | sgml-parent-document: "v4l2.sgml" |
| 144 | indent-tabs-mode: nil |
| 145 | End: |
| 146 | --> |