About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / DocBook / media / v4l / func-select.xml


Based on kernel version 4.7.2. Page generated on 2016-08-22 22:45 EST.

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>
Hide Line Numbers


About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog