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

   1 <refentry id="func-read">
   2   <refmeta>
   3     <refentrytitle>V4L2 read()</refentrytitle>
   4     &manvol;
   5   </refmeta>
   6
   7   <refnamediv>
   8     <refname>v4l2-read</refname>
   9     <refpurpose>Read from a V4L2 device</refpurpose>
  10   </refnamediv>
  11
  12   <refsynopsisdiv>
  13     <funcsynopsis>
  14       <funcsynopsisinfo>#include &lt;unistd.h&gt;</funcsynopsisinfo>
  15       <funcprototype>
  16         <funcdef>ssize_t <function>read</function></funcdef>
  17         <paramdef>int <parameter>fd</parameter></paramdef>
  18         <paramdef>void *<parameter>buf</parameter></paramdef>
  19         <paramdef>size_t <parameter>count</parameter></paramdef>
  20       </funcprototype>
  21     </funcsynopsis>
  22   </refsynopsisdiv>
  23
  24   <refsect1>
  25     <title>Arguments</title>
  26
  27     <variablelist>
  28       <varlistentry>
  29         <term><parameter>fd</parameter></term>
  30         <listitem>
  31           <para>&fd;</para>
  32         </listitem>
  33       </varlistentry>
  34       <varlistentry>
  35         <term><parameter>buf</parameter></term>
  36         <listitem>
  37           <para></para>
  38         </listitem>
  39       </varlistentry>
  40       <varlistentry>
  41         <term><parameter>count</parameter></term>
  42         <listitem>
  43           <para></para>
  44         </listitem>
  45       </varlistentry>
  46     </variablelist>
  47   </refsect1>
  48
  49   <refsect1>
  50     <title>Description</title>
  51
  52     <para><function>read()</function> attempts to read up to
  53 <parameter>count</parameter> bytes from file descriptor
  54 <parameter>fd</parameter> into the buffer starting at
  55 <parameter>buf</parameter>. The layout of the data in the buffer is
  56 discussed in the respective device interface section, see ##. If <parameter>count</parameter> is zero,
  57 <function>read()</function> returns zero and has no other results. If
  58 <parameter>count</parameter> is greater than
  59 <constant>SSIZE_MAX</constant>, the result is unspecified. Regardless
  60 of the <parameter>count</parameter> value each
  61 <function>read()</function> call will provide at most one frame (two
  62 fields) worth of data.</para>
  63
  64     <para>By default <function>read()</function> blocks until data
  65 becomes available. When the <constant>O_NONBLOCK</constant> flag was
  66 given to the &func-open; function it
  67 returns immediately with an &EAGAIN; when no data is available. The
  68 &func-select; or &func-poll; functions
  69 can always be used to suspend execution until data becomes available. All
  70 drivers supporting the <function>read()</function> function must also
  71 support <function>select()</function> and
  72 <function>poll()</function>.</para>
  73
  74     <para>Drivers can implement read functionality in different
  75 ways, using a single or multiple buffers and discarding the oldest or
  76 newest frames once the internal buffers are filled.</para>
  77
  78     <para><function>read()</function> never returns a "snapshot" of a
  79 buffer being filled. Using a single buffer the driver will stop
  80 capturing when the application starts reading the buffer until the
  81 read is finished. Thus only the period of the vertical blanking
  82 interval is available for reading, or the capture rate must fall below
  83 the nominal frame rate of the video standard.</para>
  84
  85 <para>The behavior of
  86 <function>read()</function> when called during the active picture
  87 period or the vertical blanking separating the top and bottom field
  88 depends on the discarding policy. A driver discarding the oldest
  89 frames keeps capturing into an internal buffer, continuously
  90 overwriting the previously, not read frame, and returns the frame
  91 being received at the time of the <function>read()</function> call as
  92 soon as it is complete.</para>
  93
  94     <para>A driver discarding the newest frames stops capturing until
  95 the next <function>read()</function> call. The frame being received at
  96 <function>read()</function> time is discarded, returning the following
  97 frame instead. Again this implies a reduction of the capture rate to
  98 one half or less of the nominal frame rate. An example of this model
  99 is the video read mode of the bttv driver, initiating a DMA to user
 100 memory when <function>read()</function> is called and returning when
 101 the DMA finished.</para>
 102
 103     <para>In the multiple buffer model drivers maintain a ring of
 104 internal buffers, automatically advancing to the next free buffer.
 105 This allows continuous capturing when the application can empty the
 106 buffers fast enough. Again, the behavior when the driver runs out of
 107 free buffers depends on the discarding policy.</para>
 108
 109     <para>Applications can get and set the number of buffers used
 110 internally by the driver with the &VIDIOC-G-PARM; and &VIDIOC-S-PARM;
 111 ioctls. They are optional, however. The discarding policy is not
 112 reported and cannot be changed. For minimum requirements see <xref
 113         linkend="devices" />.</para>
 114   </refsect1>
 115
 116   <refsect1>
 117     <title>Return Value</title>
 118
 119     <para>On success, the number of bytes read is returned. It is not
 120 an error if this number is smaller than the number of bytes requested,
 121 or the amount of data required for one frame. This may happen for
 122 example because <function>read()</function> was interrupted by a
 123 signal. On error, -1 is returned, and the <varname>errno</varname>
 124 variable is set appropriately. In this case the next read will start
 125 at the beginning of a new frame. Possible error codes are:</para>
 126
 127     <variablelist>
 128       <varlistentry>
 129         <term><errorcode>EAGAIN</errorcode></term>
 130         <listitem>
 131           <para>Non-blocking I/O has been selected using
 132 O_NONBLOCK and no data was immediately available for reading.</para>
 133         </listitem>
 134       </varlistentry>
 135       <varlistentry>
 136         <term><errorcode>EBADF</errorcode></term>
 137         <listitem>
 138           <para><parameter>fd</parameter> is not a valid file
 139 descriptor or is not open for reading, or the process already has the
 140 maximum number of files open.</para>
 141         </listitem>
 142       </varlistentry>
 143       <varlistentry>
 144         <term><errorcode>EBUSY</errorcode></term>
 145         <listitem>
 146           <para>The driver does not support multiple read streams and the
 147 device is already in use.</para>
 148         </listitem>
 149       </varlistentry>
 150       <varlistentry>
 151         <term><errorcode>EFAULT</errorcode></term>
 152         <listitem>
 153           <para><parameter>buf</parameter> references an inaccessible
 154 memory area.</para>
 155         </listitem>
 156       </varlistentry>
 157       <varlistentry>
 158         <term><errorcode>EINTR</errorcode></term>
 159         <listitem>
 160           <para>The call was interrupted by a signal before any
 161 data was read.</para>
 162         </listitem>
 163       </varlistentry>
 164       <varlistentry>
 165         <term><errorcode>EIO</errorcode></term>
 166         <listitem>
 167           <para>I/O error. This indicates some hardware problem or a
 168 failure to communicate with a remote device (USB camera etc.).</para>
 169         </listitem>
 170       </varlistentry>
 171       <varlistentry>
 172         <term><errorcode>EINVAL</errorcode></term>
 173         <listitem>
 174           <para>The <function>read()</function> function is not
 175 supported by this driver, not on this device, or generally not on this
 176 type of device.</para>
 177         </listitem>
 178       </varlistentry>
 179     </variablelist>
 180   </refsect1>
 181 </refentry>
 182
 183 <!--
 184 Local Variables:
 185 mode: sgml
 186 sgml-parent-document: "v4l2.sgml"
 187 indent-tabs-mode: nil
 188 End:
 189 -->