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

   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 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>