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 28can suspend execution until the driver has captured data or is ready 29to accept data for output.</para> 30 31 <para>When streaming I/O has been negotiated this function waits 32until a buffer has been filled or displayed and can be dequeued with 33the &VIDIOC-DQBUF; ioctl. When buffers are already in the outgoing 34queue of the driver the function returns immediately.</para> 35 36 <para>On success <function>poll()</function> returns the number of 37file descriptors that have been selected (that is, file descriptors 38for which the <structfield>revents</structfield> field of the 39respective <structname>pollfd</structname> structure is non-zero). 40Capture 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> 44flags. When the function timed out it returns a value of zero, on 45failure it returns <returnvalue>-1</returnvalue> and the 46<varname>errno</varname> variable is set appropriately. When the 47application 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 53been negotiated and the driver does not capture yet, the 54<function>poll</function> function starts capturing. When that fails 55it returns a <constant>POLLERR</constant> as above. Otherwise it waits 56until data has been captured and can be read. When the driver captures 57continuously (as opposed to, for example, still images) the function 58may return immediately.</para> 59 60 <para>When use of the <function>write()</function> function has 61been negotiated the <function>poll</function> function just waits 62until 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 67support 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 77structures which have non-zero <structfield>revents</structfield> 78fields, 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 87specify 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 94streams 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 101memory 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 114than <constant>OPEN_MAX</constant>.</para> 115 </listitem> 116 </varlistentry> 117 </variablelist> 118 </refsect1> 119</refentry> 120 121<!-- 122Local Variables: 123mode: sgml 124sgml-parent-document: "v4l2.sgml" 125indent-tabs-mode: nil 126End: 127--> 128