Documentation/DocBook/v4l/func-select.xml

   1 <refentry id="func-select">
   2   <refmeta>
   3     <refentrytitle>V4L2 select()</refentrytitle>
   4     &manvol;
   5   </refmeta>
   6
   7   <refnamediv>
   8     <refname>v4l2-select</refname>
   9     <refpurpose>Synchronous I/O multiplexing</refpurpose>
  10   </refnamediv>
  11
  12   <refsynopsisdiv>
  13     <funcsynopsis>
  14       <funcsynopsisinfo>
  15 #include &lt;sys/time.h&gt;
  16 #include &lt;sys/types.h&gt;
  17 #include &lt;unistd.h&gt;</funcsynopsisinfo>
  18       <funcprototype>
  19         <funcdef>int <function>select</function></funcdef>
  20         <paramdef>int <parameter>nfds</parameter></paramdef>
  21         <paramdef>fd_set *<parameter>readfds</parameter></paramdef>
  22         <paramdef>fd_set *<parameter>writefds</parameter></paramdef>
  23         <paramdef>fd_set *<parameter>exceptfds</parameter></paramdef>
  24         <paramdef>struct timeval *<parameter>timeout</parameter></paramdef>
  25       </funcprototype>
  26     </funcsynopsis>
  27   </refsynopsisdiv>
  28
  29   <refsect1>
  30     <title>Description</title>
  31
  32     <para>With the <function>select()</function> function applications
  33 can suspend execution until the driver has captured data or is ready
  34 to accept data for output.</para>
  35
  36     <para>When streaming I/O has been negotiated this function waits
  37 until a buffer has been filled or displayed and can be dequeued with
  38 the &VIDIOC-DQBUF; ioctl. When buffers are already in the outgoing
  39 queue of the driver the function returns immediately.</para>
  40
  41     <para>On success <function>select()</function> returns the total
  42 number of bits set in the <structname>fd_set</structname>s. When the
  43 function timed out it returns a value of zero. On failure it returns
  44 <returnvalue>-1</returnvalue> and the <varname>errno</varname>
  45 variable is set appropriately. When the application did not call
  46 &VIDIOC-QBUF; or &VIDIOC-STREAMON; yet the
  47 <function>select()</function> function succeeds, setting the bit of
  48 the file descriptor in <parameter>readfds</parameter> or
  49 <parameter>writefds</parameter>, but subsequent &VIDIOC-DQBUF; calls
  50 will fail.<footnote><para>The Linux kernel implements
  51 <function>select()</function> like the &func-poll; function, but
  52 <function>select()</function> cannot return a
  53 <constant>POLLERR</constant>.</para>
  54       </footnote></para>
  55
  56     <para>When use of the <function>read()</function> function has
  57 been negotiated and the driver does not capture yet, the
  58 <function>select()</function> function starts capturing. When that
  59 fails, <function>select()</function> returns successful and a
  60 subsequent <function>read()</function> call, which also attempts to
  61 start capturing, will return an appropriate error code. When the
  62 driver captures continuously (as opposed to, for example, still
  63 images) and data is already available the
  64 <function>select()</function> function returns immediately.</para>
  65
  66     <para>When use of the <function>write()</function> function has
  67 been negotiated the <function>select()</function> function just waits
  68 until the driver is ready for a non-blocking
  69 <function>write()</function> call.</para>
  70
  71     <para>All drivers implementing the <function>read()</function> or
  72 <function>write()</function> function or streaming I/O must also
  73 support the <function>select()</function> function.</para>
  74
  75     <para>For more details see the <function>select()</function>
  76 manual page.</para>
  77
  78   </refsect1>
  79
  80   <refsect1>
  81     <title>Return Value</title>
  82
  83     <para>On success, <function>select()</function> returns the number
  84 of descriptors contained in the three returned descriptor sets, which
  85 will be zero if the timeout expired. On error
  86 <returnvalue>-1</returnvalue> is returned, and the
  87 <varname>errno</varname> variable is set appropriately; the sets and
  88 <parameter>timeout</parameter> are undefined. Possible error codes
  89 are:</para>
  90
  91     <variablelist>
  92       <varlistentry>
  93         <term><errorcode>EBADF</errorcode></term>
  94         <listitem>
  95           <para>One or more of the file descriptor sets specified a
  96 file descriptor that is not open.</para>
  97         </listitem>
  98       </varlistentry>
  99       <varlistentry>
 100         <term><errorcode>EBUSY</errorcode></term>
 101         <listitem>
 102           <para>The driver does not support multiple read or write
 103 streams and the device is already in use.</para>
 104         </listitem>
 105       </varlistentry>
 106       <varlistentry>
 107         <term><errorcode>EFAULT</errorcode></term>
 108         <listitem>
 109           <para>The <parameter>readfds</parameter>,
 110 <parameter>writefds</parameter>, <parameter>exceptfds</parameter> or
 111 <parameter>timeout</parameter> pointer references an inaccessible memory
 112 area.</para>
 113         </listitem>
 114       </varlistentry>
 115       <varlistentry>
 116         <term><errorcode>EINTR</errorcode></term>
 117         <listitem>
 118           <para>The call was interrupted by a signal.</para>
 119         </listitem>
 120       </varlistentry>
 121       <varlistentry>
 122         <term><errorcode>EINVAL</errorcode></term>
 123         <listitem>
 124           <para>The <parameter>nfds</parameter> argument is less than
 125 zero or greater than <constant>FD_SETSIZE</constant>.</para>
 126         </listitem>
 127       </varlistentry>
 128     </variablelist>
 129   </refsect1>
 130 </refentry>
 131
 132 <!--
 133 Local Variables:
 134 mode: sgml
 135 sgml-parent-document: "v4l2.sgml"
 136 indent-tabs-mode: nil
 137 End:
 138 -->