Mauro Carvalho Chehab | 8e080c2 | 2009-09-13 22:16:04 -0300 | [diff] [blame] | 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 <unistd.h></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 | --> |