1 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later 2 .. c:namespace:: V4L 3 4 .. _func-read: 5 6 *********** 7 V4L2 read() 8 *********** 9 10 Name 11 ==== 12 13 v4l2-read - Read from a V4L2 device 14 15 Synopsis 16 ======== 17 18 .. code-block:: c 19 20 #include <unistd.h> 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 :c:func:`open()`. 29 30 ``buf`` 31 Buffer to be filled 32 33 ``count`` 34 Max number of bytes to read 35 36 Description 37 =========== 38 39 :c:func:`read()` attempts to read up to ``count`` bytes from file 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 42 section, see ##. If ``count`` is zero, :c:func:`read()` returns zero 43 and has no other results. If ``count`` is greater than ``SSIZE_MAX``, 44 the result is unspecified. Regardless of the ``count`` value each 45 :c:func:`read()` call will provide at most one frame (two fields) 46 worth of data. 47 48 By default :c:func:`read()` blocks until data becomes available. When 49 the ``O_NONBLOCK`` flag was given to the :c:func:`open()` 50 function it returns immediately with an ``EAGAIN`` error code when no data 51 is available. The :c:func:`select()` or 52 :c:func:`poll()` functions can always be used to suspend 53 execution until data becomes available. All drivers supporting the 54 :c:func:`read()` function must also support :c:func:`select()` and 55 :c:func:`poll()`. 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 61 :c:func:`read()` never returns a "snapshot" of a buffer being filled. 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 68 The behavior of :c:func:`read()` when called during the active picture 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 73 time of the :c:func:`read()` call as soon as it is complete. 74 75 A driver discarding the newest frames stops capturing until the next 76 :c:func:`read()` call. The frame being received at :c:func:`read()` 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 80 the bttv driver, initiating a DMA to user memory when :c:func:`read()` 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 90 the driver with the :ref:`VIDIOC_G_PARM <VIDIOC_G_PARM>` and 91 :ref:`VIDIOC_S_PARM <VIDIOC_G_PARM>` ioctls. They are optional, 92 however. The discarding policy is not reported and cannot be changed. 93 For minimum requirements see :ref:`devices`. 94 95 Return Value 96 ============ 97 98 On success, the number of bytes read is returned. It is not an error if 99 this number is smaller than the number of bytes requested, or the amount 100 of data required for one frame. This may happen for example because 101 :c:func:`read()` was interrupted by a signal. On error, -1 is 102 returned, and the ``errno`` variable is set appropriately. In this case 103 the next read will start at the beginning of a new frame. Possible error 104 codes are: 105 106 EAGAIN 107 Non-blocking I/O has been selected using O_NONBLOCK and no data was 108 immediately available for reading. 109 110 EBADF 111 ``fd`` is not a valid file descriptor or is not open for reading, or 112 the process already has the maximum number of files open. 113 114 EBUSY 115 The driver does not support multiple read streams and the device is 116 already in use. 117 118 EFAULT 119 ``buf`` references an inaccessible memory area. 120 121 EINTR 122 The call was interrupted by a signal before any data was read. 123 124 EIO 125 I/O error. This indicates some hardware problem or a failure to 126 communicate with a remote device (USB camera etc.). 127 128 EINVAL 129 The :c:func:`read()` function is not supported by this driver, not 130 on this device, or generally not on this type of device.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.