1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
|
<refentry id="func-poll">
<refmeta>
<refentrytitle>V4L2 poll()</refentrytitle>
&manvol;
</refmeta>
<refnamediv>
<refname>v4l2-poll</refname>
<refpurpose>Wait for some event on a file descriptor</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>#include <sys/poll.h></funcsynopsisinfo>
<funcprototype>
<funcdef>int <function>poll</function></funcdef>
<paramdef>struct pollfd *<parameter>ufds</parameter></paramdef>
<paramdef>unsigned int <parameter>nfds</parameter></paramdef>
<paramdef>int <parameter>timeout</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>With the <function>poll()</function> function applications
can suspend execution until the driver has captured data or is ready
to accept data for output.</para>
<para>When streaming I/O has been negotiated this function waits
until a buffer has been filled by the capture device and can be dequeued
with the &VIDIOC-DQBUF; ioctl. For output devices this function waits
until the device is ready to accept a new buffer to be queued up with
the &VIDIOC-QBUF; ioctl for display. When buffers are already in the outgoing
queue of the driver (capture) or the incoming queue isn't full (display)
the function returns immediately.</para>
<para>On success <function>poll()</function> returns the number of
file descriptors that have been selected (that is, file descriptors
for which the <structfield>revents</structfield> field of the
respective <structname>pollfd</structname> structure is non-zero).
Capture devices set the <constant>POLLIN</constant> and
<constant>POLLRDNORM</constant> flags in the
<structfield>revents</structfield> field, output devices the
<constant>POLLOUT</constant> and <constant>POLLWRNORM</constant>
flags. When the function timed out it returns a value of zero, on
failure it returns <returnvalue>-1</returnvalue> and the
<varname>errno</varname> variable is set appropriately. When the
application did not call &VIDIOC-STREAMON; the
<function>poll()</function> function succeeds, but sets the
<constant>POLLERR</constant> flag in the
<structfield>revents</structfield> field. When the
application has called &VIDIOC-STREAMON; for a capture device but hasn't
yet called &VIDIOC-QBUF;, the <function>poll()</function> function
succeeds and sets the <constant>POLLERR</constant> flag in the
<structfield>revents</structfield> field. For output devices this
same situation will cause <function>poll()</function> to succeed
as well, but it sets the <constant>POLLOUT</constant> and
<constant>POLLWRNORM</constant> flags in the <structfield>revents</structfield>
field.</para>
<para>If an event occurred (see &VIDIOC-DQEVENT;) then
<constant>POLLPRI</constant> will be set in the <structfield>revents</structfield>
field and <function>poll()</function> will return.</para>
<para>When use of the <function>read()</function> function has
been negotiated and the driver does not capture yet, the
<function>poll</function> function starts capturing. When that fails
it returns a <constant>POLLERR</constant> as above. Otherwise it waits
until data has been captured and can be read. When the driver captures
continuously (as opposed to, for example, still images) the function
may return immediately.</para>
<para>When use of the <function>write()</function> function has
been negotiated and the driver does not stream yet, the
<function>poll</function> function starts streaming. When that fails
it returns a <constant>POLLERR</constant> as above. Otherwise it waits
until the driver is ready for a non-blocking
<function>write()</function> call.</para>
<para>If the caller is only interested in events (just
<constant>POLLPRI</constant> is set in the <structfield>events</structfield>
field), then <function>poll()</function> will <emphasis>not</emphasis>
start streaming if the driver does not stream yet. This makes it
possible to just poll for events and not for buffers.</para>
<para>All drivers implementing the <function>read()</function> or
<function>write()</function> function or streaming I/O must also
support the <function>poll()</function> function.</para>
<para>For more details see the
<function>poll()</function> manual page.</para>
</refsect1>
<refsect1>
<title>Return Value</title>
<para>On success, <function>poll()</function> returns the number
structures which have non-zero <structfield>revents</structfield>
fields, or zero if the call timed out. On error
<returnvalue>-1</returnvalue> is returned, and the
<varname>errno</varname> variable is set appropriately:</para>
<variablelist>
<varlistentry>
<term><errorcode>EBADF</errorcode></term>
<listitem>
<para>One or more of the <parameter>ufds</parameter> members
specify an invalid file descriptor.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><errorcode>EBUSY</errorcode></term>
<listitem>
<para>The driver does not support multiple read or write
streams and the device is already in use.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><errorcode>EFAULT</errorcode></term>
<listitem>
<para><parameter>ufds</parameter> references an inaccessible
memory area.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><errorcode>EINTR</errorcode></term>
<listitem>
<para>The call was interrupted by a signal.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><errorcode>EINVAL</errorcode></term>
<listitem>
<para>The <parameter>nfds</parameter> argument is greater
than <constant>OPEN_MAX</constant>.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
</refentry>
|
