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