About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

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




Custom Search

Based on kernel version 3.15.4. Page generated on 2014-07-07 09:02 EST.

1	<refentry id="func-poll">
2	  <refmeta>
3	    <refentrytitle>V4L2 poll()</refentrytitle>
4	    &manvol;
5	  </refmeta>
6	
7	  <refnamediv>
8	    <refname>v4l2-poll</refname>
9	    <refpurpose>Wait for some event on a file descriptor</refpurpose>
10	  </refnamediv>
11	
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>
23	
24	  <refsect1>
25	    <title>Description</title>
26	
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>
30	
31	    <para>When streaming I/O has been negotiated this function waits
32	until a buffer has been filled or displayed and can be dequeued with
33	the &VIDIOC-DQBUF; ioctl. When buffers are already in the outgoing
34	queue of the driver the function returns immediately.</para>
35	
36	    <para>On success <function>poll()</function> returns the number of
37	file descriptors that have been selected (that is, file descriptors
38	for which the <structfield>revents</structfield> field of the
39	respective <structname>pollfd</structname> structure is non-zero).
40	Capture devices set the <constant>POLLIN</constant> and
41	<constant>POLLRDNORM</constant> flags in the
42	<structfield>revents</structfield> field, output devices the
43	<constant>POLLOUT</constant> and <constant>POLLWRNORM</constant>
44	flags. When the function timed out it returns a value of zero, on
45	failure it returns <returnvalue>-1</returnvalue> and the
46	<varname>errno</varname> variable is set appropriately. When the
47	application did not call &VIDIOC-QBUF; or &VIDIOC-STREAMON; yet the
48	<function>poll()</function> function succeeds, but sets the
49	<constant>POLLERR</constant> flag in the
50	<structfield>revents</structfield> field.</para>
51	
52	    <para>When use of the <function>read()</function> function has
53	been negotiated and the driver does not capture yet, the
54	<function>poll</function> function starts capturing. When that fails
55	it returns a <constant>POLLERR</constant> as above. Otherwise it waits
56	until data has been captured and can be read. When the driver captures
57	continuously (as opposed to, for example, still images) the function
58	may return immediately.</para>
59	
60	    <para>When use of the <function>write()</function> function has
61	been negotiated the <function>poll</function> function just waits
62	until the driver is ready for a non-blocking
63	<function>write()</function> call.</para>
64	
65	    <para>All drivers implementing the <function>read()</function> or
66	<function>write()</function> function or streaming I/O must also
67	support the <function>poll()</function> function.</para>
68	
69	    <para>For more details see the
70	<function>poll()</function> manual page.</para>
71	  </refsect1>
72	
73	  <refsect1>
74	    <title>Return Value</title>
75	
76	    <para>On success, <function>poll()</function> returns the number
77	structures which have non-zero <structfield>revents</structfield>
78	fields, or zero if the call timed out. On error
79	<returnvalue>-1</returnvalue> is returned, and the
80	<varname>errno</varname> variable is set appropriately:</para>
81	
82	    <variablelist>
83	      <varlistentry>
84		<term><errorcode>EBADF</errorcode></term>
85		<listitem>
86		  <para>One or more of the <parameter>ufds</parameter> members
87	specify an invalid file descriptor.</para>
88		</listitem>
89	      </varlistentry>
90	      <varlistentry>
91		<term><errorcode>EBUSY</errorcode></term>
92		<listitem>
93		  <para>The driver does not support multiple read or write
94	streams and the device is already in use.</para>
95		</listitem>
96	      </varlistentry>
97	      <varlistentry>
98		<term><errorcode>EFAULT</errorcode></term>
99		<listitem>
100		  <para><parameter>ufds</parameter> references an inaccessible
101	memory area.</para>
102		</listitem>
103	      </varlistentry>
104	      <varlistentry>
105		<term><errorcode>EINTR</errorcode></term>
106		<listitem>
107		  <para>The call was interrupted by a signal.</para>
108		</listitem>
109	      </varlistentry>
110	      <varlistentry>
111		<term><errorcode>EINVAL</errorcode></term>
112		<listitem>
113		  <para>The <parameter>nfds</parameter> argument is greater
114	than <constant>OPEN_MAX</constant>.</para>
115		</listitem>
116	      </varlistentry>
117	    </variablelist>
118	  </refsect1>
119	</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.