diff options
Diffstat (limited to 'Documentation/DocBook/media/v4l/func-read.xml')
| -rw-r--r-- | Documentation/DocBook/media/v4l/func-read.xml | 181 |
1 files changed, 0 insertions, 181 deletions
diff --git a/Documentation/DocBook/media/v4l/func-read.xml b/Documentation/DocBook/media/v4l/func-read.xml deleted file mode 100644 index e218bbfbd362..000000000000 --- a/Documentation/DocBook/media/v4l/func-read.xml +++ /dev/null @@ -1,181 +0,0 @@ -<refentry id="func-read"> - <refmeta> - <refentrytitle>V4L2 read()</refentrytitle> - &manvol; - </refmeta> - - <refnamediv> - <refname>v4l2-read</refname> - <refpurpose>Read from a V4L2 device</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <unistd.h></funcsynopsisinfo> - <funcprototype> - <funcdef>ssize_t <function>read</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>void *<parameter>buf</parameter></paramdef> - <paramdef>size_t <parameter>count</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Arguments</title> - - <variablelist> - <varlistentry> - <term><parameter>fd</parameter></term> - <listitem> - <para>&fd;</para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>buf</parameter></term> - <listitem> - <para></para> - </listitem> - </varlistentry> - <varlistentry> - <term><parameter>count</parameter></term> - <listitem> - <para></para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Description</title> - - <para><function>read()</function> attempts to read up to -<parameter>count</parameter> bytes from file descriptor -<parameter>fd</parameter> into the buffer starting at -<parameter>buf</parameter>. The layout of the data in the buffer is -discussed in the respective device interface section, see ##. If <parameter>count</parameter> is zero, -<function>read()</function> returns zero and has no other results. If -<parameter>count</parameter> is greater than -<constant>SSIZE_MAX</constant>, the result is unspecified. Regardless -of the <parameter>count</parameter> value each -<function>read()</function> call will provide at most one frame (two -fields) worth of data.</para> - - <para>By default <function>read()</function> blocks until data -becomes available. When the <constant>O_NONBLOCK</constant> flag was -given to the &func-open; function it -returns immediately with an &EAGAIN; when no data is available. The -&func-select; or &func-poll; functions -can always be used to suspend execution until data becomes available. All -drivers supporting the <function>read()</function> function must also -support <function>select()</function> and -<function>poll()</function>.</para> - - <para>Drivers can implement read functionality in different -ways, using a single or multiple buffers and discarding the oldest or -newest frames once the internal buffers are filled.</para> - - <para><function>read()</function> never returns a "snapshot" of a -buffer being filled. Using a single buffer the driver will stop -capturing when the application starts reading the buffer until the -read is finished. Thus only the period of the vertical blanking -interval is available for reading, or the capture rate must fall below -the nominal frame rate of the video standard.</para> - -<para>The behavior of -<function>read()</function> when called during the active picture -period or the vertical blanking separating the top and bottom field -depends on the discarding policy. A driver discarding the oldest -frames keeps capturing into an internal buffer, continuously -overwriting the previously, not read frame, and returns the frame -being received at the time of the <function>read()</function> call as -soon as it is complete.</para> - - <para>A driver discarding the newest frames stops capturing until -the next <function>read()</function> call. The frame being received at -<function>read()</function> time is discarded, returning the following -frame instead. Again this implies a reduction of the capture rate to -one half or less of the nominal frame rate. An example of this model -is the video read mode of the bttv driver, initiating a DMA to user -memory when <function>read()</function> is called and returning when -the DMA finished.</para> - - <para>In the multiple buffer model drivers maintain a ring of -internal buffers, automatically advancing to the next free buffer. -This allows continuous capturing when the application can empty the -buffers fast enough. Again, the behavior when the driver runs out of -free buffers depends on the discarding policy.</para> - - <para>Applications can get and set the number of buffers used -internally by the driver with the &VIDIOC-G-PARM; and &VIDIOC-S-PARM; -ioctls. They are optional, however. The discarding policy is not -reported and cannot be changed. For minimum requirements see <xref - linkend="devices" />.</para> - </refsect1> - - <refsect1> - <title>Return Value</title> - - <para>On success, the number of bytes read is returned. It is not -an error if this number is smaller than the number of bytes requested, -or the amount of data required for one frame. This may happen for -example because <function>read()</function> was interrupted by a -signal. On error, -1 is returned, and the <varname>errno</varname> -variable is set appropriately. In this case the next read will start -at the beginning of a new frame. Possible error codes are:</para> - - <variablelist> - <varlistentry> - <term><errorcode>EAGAIN</errorcode></term> - <listitem> - <para>Non-blocking I/O has been selected using -O_NONBLOCK and no data was immediately available for reading.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><errorcode>EBADF</errorcode></term> - <listitem> - <para><parameter>fd</parameter> is not a valid file -descriptor or is not open for reading, or the process already has the -maximum number of files open.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><errorcode>EBUSY</errorcode></term> - <listitem> - <para>The driver does not support multiple read streams and the -device is already in use.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><errorcode>EFAULT</errorcode></term> - <listitem> - <para><parameter>buf</parameter> references an inaccessible -memory area.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><errorcode>EINTR</errorcode></term> - <listitem> - <para>The call was interrupted by a signal before any -data was read.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><errorcode>EIO</errorcode></term> - <listitem> - <para>I/O error. This indicates some hardware problem or a -failure to communicate with a remote device (USB camera etc.).</para> - </listitem> - </varlistentry> - <varlistentry> - <term><errorcode>EINVAL</errorcode></term> - <listitem> - <para>The <function>read()</function> function is not -supported by this driver, not on this device, or generally not on this -type of device.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> -</refentry> |