]>
Commit | Line | Data |
---|---|---|
5377d91f MH |
1 | .. -*- coding: utf-8; mode: rst -*- |
2 | ||
3 | .. _func-read: | |
4 | ||
5 | *********** | |
6 | V4L2 read() | |
7 | *********** | |
8 | ||
9 | *man v4l2-read(2)* | |
10 | ||
11 | Read from a V4L2 device | |
12 | ||
13 | ||
14 | Synopsis | |
15 | ======== | |
16 | ||
17 | .. code-block:: c | |
18 | ||
19 | #include <unistd.h> | |
20 | ||
21 | ||
22 | .. c:function:: ssize_t read( int fd, void *buf, size_t count ) | |
23 | ||
24 | Arguments | |
25 | ========= | |
26 | ||
27 | ``fd`` | |
28 | File descriptor returned by :ref:`open() <func-open>`. | |
29 | ||
30 | ``buf`` | |
31 | ``count`` | |
32 | ||
33 | ||
34 | Description | |
35 | =========== | |
36 | ||
37 | :c:func:`read()` attempts to read up to ``count`` bytes from file | |
38 | descriptor ``fd`` into the buffer starting at ``buf``. The layout of the | |
39 | data in the buffer is discussed in the respective device interface | |
40 | section, see ##. If ``count`` is zero, :c:func:`read()` returns zero | |
41 | and has no other results. If ``count`` is greater than ``SSIZE_MAX``, | |
42 | the result is unspecified. Regardless of the ``count`` value each | |
43 | :c:func:`read()` call will provide at most one frame (two fields) | |
44 | worth of data. | |
45 | ||
46 | By default :c:func:`read()` blocks until data becomes available. When | |
47 | the ``O_NONBLOCK`` flag was given to the :ref:`open() <func-open>` | |
48 | function it returns immediately with an EAGAIN error code when no data | |
49 | is available. The :ref:`select() <func-select>` or | |
50 | :ref:`poll() <func-poll>` functions can always be used to suspend | |
51 | execution until data becomes available. All drivers supporting the | |
52 | :c:func:`read()` function must also support :c:func:`select()` and | |
53 | :c:func:`poll()`. | |
54 | ||
55 | Drivers can implement read functionality in different ways, using a | |
56 | single or multiple buffers and discarding the oldest or newest frames | |
57 | once the internal buffers are filled. | |
58 | ||
59 | :c:func:`read()` never returns a "snapshot" of a buffer being filled. | |
60 | Using a single buffer the driver will stop capturing when the | |
61 | application starts reading the buffer until the read is finished. Thus | |
62 | only the period of the vertical blanking interval is available for | |
63 | reading, or the capture rate must fall below the nominal frame rate of | |
64 | the video standard. | |
65 | ||
66 | The behavior of :c:func:`read()` when called during the active picture | |
67 | period or the vertical blanking separating the top and bottom field | |
68 | depends on the discarding policy. A driver discarding the oldest frames | |
69 | keeps capturing into an internal buffer, continuously overwriting the | |
70 | previously, not read frame, and returns the frame being received at the | |
71 | time of the :c:func:`read()` call as soon as it is complete. | |
72 | ||
73 | A driver discarding the newest frames stops capturing until the next | |
74 | :c:func:`read()` call. The frame being received at :c:func:`read()` | |
75 | time is discarded, returning the following frame instead. Again this | |
76 | implies a reduction of the capture rate to one half or less of the | |
77 | nominal frame rate. An example of this model is the video read mode of | |
78 | the bttv driver, initiating a DMA to user memory when :c:func:`read()` | |
79 | is called and returning when the DMA finished. | |
80 | ||
81 | In the multiple buffer model drivers maintain a ring of internal | |
82 | buffers, automatically advancing to the next free buffer. This allows | |
83 | continuous capturing when the application can empty the buffers fast | |
84 | enough. Again, the behavior when the driver runs out of free buffers | |
85 | depends on the discarding policy. | |
86 | ||
87 | Applications can get and set the number of buffers used internally by | |
af4a4d0d MCC |
88 | the driver with the :ref:`VIDIOC_G_PARM <VIDIOC_G_PARM>` and |
89 | :ref:`VIDIOC_S_PARM <VIDIOC_G_PARM>` ioctls. They are optional, | |
5377d91f MH |
90 | however. The discarding policy is not reported and cannot be changed. |
91 | For minimum requirements see :ref:`devices`. | |
92 | ||
93 | ||
94 | Return Value | |
95 | ============ | |
96 | ||
97 | On success, the number of bytes read is returned. It is not an error if | |
98 | this number is smaller than the number of bytes requested, or the amount | |
99 | of data required for one frame. This may happen for example because | |
100 | :c:func:`read()` was interrupted by a signal. On error, -1 is | |
101 | returned, and the ``errno`` variable is set appropriately. In this case | |
102 | the next read will start at the beginning of a new frame. Possible error | |
103 | codes are: | |
104 | ||
105 | EAGAIN | |
106 | Non-blocking I/O has been selected using O_NONBLOCK and no data was | |
107 | immediately available for reading. | |
108 | ||
109 | EBADF | |
110 | ``fd`` is not a valid file descriptor or is not open for reading, or | |
111 | the process already has the maximum number of files open. | |
112 | ||
113 | EBUSY | |
114 | The driver does not support multiple read streams and the device is | |
115 | already in use. | |
116 | ||
117 | EFAULT | |
118 | ``buf`` references an inaccessible memory area. | |
119 | ||
120 | EINTR | |
121 | The call was interrupted by a signal before any data was read. | |
122 | ||
123 | EIO | |
124 | I/O error. This indicates some hardware problem or a failure to | |
125 | communicate with a remote device (USB camera etc.). | |
126 | ||
127 | EINVAL | |
128 | The :c:func:`read()` function is not supported by this driver, not | |
129 | on this device, or generally not on this type of device. | |
130 | ||
131 | ||
132 | .. ------------------------------------------------------------------------------ | |
133 | .. This file was automatically converted from DocBook-XML with the dbxml | |
134 | .. library (https://github.com/return42/sphkerneldoc). The origin XML comes | |
135 | .. from the linux kernel, refer to: | |
136 | .. | |
137 | .. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook | |
138 | .. ------------------------------------------------------------------------------ |