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 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-STREAMON; the
  48 <function>poll()</function> function succeeds, but sets the
  49 <constant>POLLERR</constant> flag in the
  50 <structfield>revents</structfield> field. When the
  51 application has called &VIDIOC-STREAMON; for a capture device but hasn't
  52 yet called &VIDIOC-QBUF;, the <function>poll()</function> function
  53 succeeds and sets the <constant>POLLERR</constant> flag in the
  54 <structfield>revents</structfield> field. For output devices this
  55 same situation will cause <function>poll()</function> to succeed
  56 as well, but it sets the <constant>POLLOUT</constant> and
  57 <constant>POLLWRNORM</constant> flags in the <structfield>revents</structfield>
  58 field.</para>
  59
  60     <para>When use of the <function>read()</function> function has
  61 been negotiated and the driver does not capture yet, the
  62 <function>poll</function> function starts capturing. When that fails
  63 it returns a <constant>POLLERR</constant> as above. Otherwise it waits
  64 until data has been captured and can be read. When the driver captures
  65 continuously (as opposed to, for example, still images) the function
  66 may return immediately.</para>
  67
  68     <para>When use of the <function>write()</function> function has
  69 been negotiated the <function>poll</function> function just waits
  70 until the driver is ready for a non-blocking
  71 <function>write()</function> call.</para>
  72
  73     <para>All drivers implementing the <function>read()</function> or
  74 <function>write()</function> function or streaming I/O must also
  75 support the <function>poll()</function> function.</para>
  76
  77     <para>For more details see the
  78 <function>poll()</function> manual page.</para>
  79   </refsect1>
  80
  81   <refsect1>
  82     <title>Return Value</title>
  83
  84     <para>On success, <function>poll()</function> returns the number
  85 structures which have non-zero <structfield>revents</structfield>
  86 fields, or zero if the call timed out. On error
  87 <returnvalue>-1</returnvalue> is returned, and the
  88 <varname>errno</varname> variable is set appropriately:</para>
  89
  90     <variablelist>
  91       <varlistentry>
  92         <term><errorcode>EBADF</errorcode></term>
  93         <listitem>
  94           <para>One or more of the <parameter>ufds</parameter> members
  95 specify an invalid file descriptor.</para>
  96         </listitem>
  97       </varlistentry>
  98       <varlistentry>
  99         <term><errorcode>EBUSY</errorcode></term>
 100         <listitem>
 101           <para>The driver does not support multiple read or write
 102 streams and the device is already in use.</para>
 103         </listitem>
 104       </varlistentry>
 105       <varlistentry>
 106         <term><errorcode>EFAULT</errorcode></term>
 107         <listitem>
 108           <para><parameter>ufds</parameter> references an inaccessible
 109 memory area.</para>
 110         </listitem>
 111       </varlistentry>
 112       <varlistentry>
 113         <term><errorcode>EINTR</errorcode></term>
 114         <listitem>
 115           <para>The call was interrupted by a signal.</para>
 116         </listitem>
 117       </varlistentry>
 118       <varlistentry>
 119         <term><errorcode>EINVAL</errorcode></term>
 120         <listitem>
 121           <para>The <parameter>nfds</parameter> argument is greater
 122 than <constant>OPEN_MAX</constant>.</para>
 123         </listitem>
 124       </varlistentry>
 125     </variablelist>
 126   </refsect1>
 127 </refentry>