Documentation/DocBook/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 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 -->