Merge branch 'for-3.3/drivers' of git://git.kernel.dk/linux-block
[linux-2.6.git] / Documentation / DocBook / media / v4l / func-select.xml
1 <refentry id="func-select">
2   <refmeta>
3     <refentrytitle>V4L2 select()</refentrytitle>
4     &manvol;
5   </refmeta>
6
7   <refnamediv>
8     <refname>v4l2-select</refname>
9     <refpurpose>Synchronous I/O multiplexing</refpurpose>
10   </refnamediv>
11
12   <refsynopsisdiv>
13     <funcsynopsis>
14       <funcsynopsisinfo>
15 #include &lt;sys/time.h&gt;
16 #include &lt;sys/types.h&gt;
17 #include &lt;unistd.h&gt;</funcsynopsisinfo>
18       <funcprototype>
19         <funcdef>int <function>select</function></funcdef>
20         <paramdef>int <parameter>nfds</parameter></paramdef>
21         <paramdef>fd_set *<parameter>readfds</parameter></paramdef>
22         <paramdef>fd_set *<parameter>writefds</parameter></paramdef>
23         <paramdef>fd_set *<parameter>exceptfds</parameter></paramdef>
24         <paramdef>struct timeval *<parameter>timeout</parameter></paramdef>
25       </funcprototype>
26     </funcsynopsis>
27   </refsynopsisdiv>
28
29   <refsect1>
30     <title>Description</title>
31
32     <para>With the <function>select()</function> function applications
33 can suspend execution until the driver has captured data or is ready
34 to accept data for output.</para>
35
36     <para>When streaming I/O has been negotiated this function waits
37 until a buffer has been filled or displayed and can be dequeued with
38 the &VIDIOC-DQBUF; ioctl. When buffers are already in the outgoing
39 queue of the driver the function returns immediately.</para>
40
41     <para>On success <function>select()</function> returns the total
42 number of bits set in the <structname>fd_set</structname>s. When the
43 function timed out it returns a value of zero. On failure it returns
44 <returnvalue>-1</returnvalue> and the <varname>errno</varname>
45 variable is set appropriately. When the application did not call
46 &VIDIOC-QBUF; or &VIDIOC-STREAMON; yet the
47 <function>select()</function> function succeeds, setting the bit of
48 the file descriptor in <parameter>readfds</parameter> or
49 <parameter>writefds</parameter>, but subsequent &VIDIOC-DQBUF; calls
50 will fail.<footnote><para>The Linux kernel implements
51 <function>select()</function> like the &func-poll; function, but
52 <function>select()</function> cannot return a
53 <constant>POLLERR</constant>.</para>
54       </footnote></para>
55
56     <para>When use of the <function>read()</function> function has
57 been negotiated and the driver does not capture yet, the
58 <function>select()</function> function starts capturing. When that
59 fails, <function>select()</function> returns successful and a
60 subsequent <function>read()</function> call, which also attempts to
61 start capturing, will return an appropriate error code. When the
62 driver captures continuously (as opposed to, for example, still
63 images) and data is already available the
64 <function>select()</function> function returns immediately.</para>
65
66     <para>When use of the <function>write()</function> function has
67 been negotiated the <function>select()</function> function just waits
68 until the driver is ready for a non-blocking
69 <function>write()</function> call.</para>
70
71     <para>All drivers implementing the <function>read()</function> or
72 <function>write()</function> function or streaming I/O must also
73 support the <function>select()</function> function.</para>
74
75     <para>For more details see the <function>select()</function>
76 manual page.</para>
77
78   </refsect1>
79
80   <refsect1>
81     <title>Return Value</title>
82
83     <para>On success, <function>select()</function> returns the number
84 of descriptors contained in the three returned descriptor sets, which
85 will be zero if the timeout expired. On error
86 <returnvalue>-1</returnvalue> is returned, and the
87 <varname>errno</varname> variable is set appropriately; the sets and
88 <parameter>timeout</parameter> are undefined. Possible error codes
89 are:</para>
90
91     <variablelist>
92       <varlistentry>
93         <term><errorcode>EBADF</errorcode></term>
94         <listitem>
95           <para>One or more of the file descriptor sets specified a
96 file descriptor that is not open.</para>
97         </listitem>
98       </varlistentry>
99       <varlistentry>
100         <term><errorcode>EBUSY</errorcode></term>
101         <listitem>
102           <para>The driver does not support multiple read or write
103 streams and the device is already in use.</para>
104         </listitem>
105       </varlistentry>
106       <varlistentry>
107         <term><errorcode>EFAULT</errorcode></term>
108         <listitem>
109           <para>The <parameter>readfds</parameter>,
110 <parameter>writefds</parameter>, <parameter>exceptfds</parameter> or
111 <parameter>timeout</parameter> pointer references an inaccessible memory
112 area.</para>
113         </listitem>
114       </varlistentry>
115       <varlistentry>
116         <term><errorcode>EINTR</errorcode></term>
117         <listitem>
118           <para>The call was interrupted by a signal.</para>
119         </listitem>
120       </varlistentry>
121       <varlistentry>
122         <term><errorcode>EINVAL</errorcode></term>
123         <listitem>
124           <para>The <parameter>nfds</parameter> argument is less than
125 zero or greater than <constant>FD_SETSIZE</constant>.</para>
126         </listitem>
127       </varlistentry>
128     </variablelist>
129   </refsect1>
130 </refentry>
131
132 <!--
133 Local Variables:
134 mode: sgml
135 sgml-parent-document: "v4l2.sgml"
136 indent-tabs-mode: nil
137 End:
138 -->