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