← Back to branch summary

~ubuntu-branches/ubuntu/precise/linux-lowlatency/precise

« back to all changes in this revision

Viewing changes to Documentation/DocBook/media/v4l/func-read.xml

  • Committer: Package Import Robot
  • Author(s): Alessio Igor Bogani
  • Date: 2011-10-26 11:13:05 UTC
  • Revision ID: package-import@ubuntu.com-20111026111305-tz023xykf0i6eosh
Tags: upstream-3.2.0
Import upstream version 3.2.0

Show diffs side-by-side

added added

removed removed

Lines of Context:
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
-->