tjh.dev
Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
fork
Configure Feed
Select the types of activity you want to include in your feed.
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
38linkend="videodev">videodev.h</link> header file, for example
39VIDIOC_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
55V4L2 devices. The argument <parameter>fd</parameter> must be an open
56file descriptor. An ioctl <parameter>request</parameter> has encoded
57in it whether the argument is an input, output or read/write
58parameter, and the size of the argument <parameter>argp</parameter> in
59bytes. Macros and defines specifying V4L2 ioctl requests are located
60in the <link linkend="videodev">videodev.h</link> header file.
61Applications should use their own copy, not include the version in the
62kernel sources on the system they compile on. All V4L2 ioctl requests,
63their 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
74output or read/write parameter it remains unmodified, and the
75<varname>errno</varname> variable is set appropriately. See below for
76possible error codes. Generic errors like <errorcode>EBADF</errorcode>
77or <errorcode>EFAULT</errorcode> are not listed in the sections
78discussing individual ioctl requests.</para>
79 <para>Note ioctls may return undefined error codes. Since errors
80may have side effects such as a driver reset applications should
81abort 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
88descriptor.</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
95this error code is returned when I/O is in progress or the driver
96supports 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
103memory 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
110character 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
117to by <parameter>argp</parameter> is not valid. This is a very common
118error 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
126complete 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<!--
141Local Variables:
142mode: sgml
143sgml-parent-document: "v4l2.sgml"
144indent-tabs-mode: nil
145End:
146-->