Based on kernel version 4.7.2. Page generated on 2016-08-22 22:45 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 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> 38 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> 62 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> 66 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> 74 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> 81 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> 87 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> 91 92 <para>For more details see the 93 <function>poll()</function> manual page.</para> 94 </refsect1> 95 96 <refsect1> 97 <title>Return Value</title> 98 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> 104 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>
