Based on kernel version 3.0.4. Page generated on 2011-10-03 22:07 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 <sys/poll.h></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> 120 121 <!-- 122 Local Variables: 123 mode: sgml 124 sgml-parent-document: "v4l2.sgml" 125 indent-tabs-mode: nil 126 End: 127 -->
