aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation/DocBook/v4l/func-select.xml
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/DocBook/v4l/func-select.xml')
-rw-r--r--Documentation/DocBook/v4l/func-select.xml138
1 files changed, 138 insertions, 0 deletions
diff --git a/Documentation/DocBook/v4l/func-select.xml b/Documentation/DocBook/v4l/func-select.xml
new file mode 100644
index 000000000000..b6713623181f
--- /dev/null
+++ b/Documentation/DocBook/v4l/func-select.xml
@@ -0,0 +1,138 @@
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
33can suspend execution until the driver has captured data or is ready
34to accept data for output.</para>
35
36 <para>When streaming I/O has been negotiated this function waits
37until a buffer has been filled or displayed and can be dequeued with
38the &VIDIOC-DQBUF; ioctl. When buffers are already in the outgoing
39queue of the driver the function returns immediately.</para>
40
41 <para>On success <function>select()</function> returns the total
42number of bits set in the <structname>fd_set</structname>s. When the
43function timed out it returns a value of zero. On failure it returns
44<returnvalue>-1</returnvalue> and the <varname>errno</varname>
45variable 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
48the file descriptor in <parameter>readfds</parameter> or
49<parameter>writefds</parameter>, but subsequent &VIDIOC-DQBUF; calls
50will 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
57been negotiated and the driver does not capture yet, the
58<function>select()</function> function starts capturing. When that
59fails, <function>select()</function> returns successful and a
60subsequent <function>read()</function> call, which also attempts to
61start capturing, will return an appropriate error code. When the
62driver captures continuously (as opposed to, for example, still
63images) 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
67been negotiated the <function>select()</function> function just waits
68until 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
73support the <function>select()</function> function.</para>
74
75 <para>For more details see the <function>select()</function>
76manual page.</para>
77
78 </refsect1>
79
80 <refsect1>
81 <title>Return Value</title>
82
83 <para>On success, <function>select()</function> returns the number
84of descriptors contained in the three returned descriptor sets, which
85will 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
89are:</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
96file 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
103streams 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
112area.</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
125zero or greater than <constant>FD_SETSIZE</constant>.</para>
126 </listitem>
127 </varlistentry>
128 </variablelist>
129 </refsect1>
130</refentry>
131
132<!--
133Local Variables:
134mode: sgml
135sgml-parent-document: "v4l2.sgml"
136indent-tabs-mode: nil
137End:
138-->
generated by cgit v1.2.2 (git 2.25.0) at 2025-02-04 06:38:05 -0500