About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

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

Custom Search

Based on kernel version 4.3. Page generated on 2015-11-02 12:48 EST.

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

Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.