About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

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




Custom Search

Based on kernel version 3.15.4. Page generated on 2014-07-07 09:02 EST.

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>
Hide Line Numbers
About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.