0001 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
0002 .. c:namespace:: V4L
0003
0004 .. _func-read:
0005
0006 ***********
0007 V4L2 read()
0008 ***********
0009
0010 Name
0011 ====
0012
0013 v4l2-read - Read from a V4L2 device
0014
0015 Synopsis
0016 ========
0017
0018 .. code-block:: c
0019
0020 #include <unistd.h>
0021
0022 .. c:function:: ssize_t read( int fd, void *buf, size_t count )
0023
0024 Arguments
0025 =========
0026
0027 ``fd``
0028 File descriptor returned by :c:func:`open()`.
0029
0030 ``buf``
0031 Buffer to be filled
0032
0033 ``count``
0034 Max number of bytes to read
0035
0036 Description
0037 ===========
0038
0039 :c:func:`read()` attempts to read up to ``count`` bytes from file
0040 descriptor ``fd`` into the buffer starting at ``buf``. The layout of the
0041 data in the buffer is discussed in the respective device interface
0042 section, see ##. If ``count`` is zero, :c:func:`read()` returns zero
0043 and has no other results. If ``count`` is greater than ``SSIZE_MAX``,
0044 the result is unspecified. Regardless of the ``count`` value each
0045 :c:func:`read()` call will provide at most one frame (two fields)
0046 worth of data.
0047
0048 By default :c:func:`read()` blocks until data becomes available. When
0049 the ``O_NONBLOCK`` flag was given to the :c:func:`open()`
0050 function it returns immediately with an ``EAGAIN`` error code when no data
0051 is available. The :c:func:`select()` or
0052 :c:func:`poll()` functions can always be used to suspend
0053 execution until data becomes available. All drivers supporting the
0054 :c:func:`read()` function must also support :c:func:`select()` and
0055 :c:func:`poll()`.
0056
0057 Drivers can implement read functionality in different ways, using a
0058 single or multiple buffers and discarding the oldest or newest frames
0059 once the internal buffers are filled.
0060
0061 :c:func:`read()` never returns a "snapshot" of a buffer being filled.
0062 Using a single buffer the driver will stop capturing when the
0063 application starts reading the buffer until the read is finished. Thus
0064 only the period of the vertical blanking interval is available for
0065 reading, or the capture rate must fall below the nominal frame rate of
0066 the video standard.
0067
0068 The behavior of :c:func:`read()` when called during the active picture
0069 period or the vertical blanking separating the top and bottom field
0070 depends on the discarding policy. A driver discarding the oldest frames
0071 keeps capturing into an internal buffer, continuously overwriting the
0072 previously, not read frame, and returns the frame being received at the
0073 time of the :c:func:`read()` call as soon as it is complete.
0074
0075 A driver discarding the newest frames stops capturing until the next
0076 :c:func:`read()` call. The frame being received at :c:func:`read()`
0077 time is discarded, returning the following frame instead. Again this
0078 implies a reduction of the capture rate to one half or less of the
0079 nominal frame rate. An example of this model is the video read mode of
0080 the bttv driver, initiating a DMA to user memory when :c:func:`read()`
0081 is called and returning when the DMA finished.
0082
0083 In the multiple buffer model drivers maintain a ring of internal
0084 buffers, automatically advancing to the next free buffer. This allows
0085 continuous capturing when the application can empty the buffers fast
0086 enough. Again, the behavior when the driver runs out of free buffers
0087 depends on the discarding policy.
0088
0089 Applications can get and set the number of buffers used internally by
0090 the driver with the :ref:`VIDIOC_G_PARM <VIDIOC_G_PARM>` and
0091 :ref:`VIDIOC_S_PARM <VIDIOC_G_PARM>` ioctls. They are optional,
0092 however. The discarding policy is not reported and cannot be changed.
0093 For minimum requirements see :ref:`devices`.
0094
0095 Return Value
0096 ============
0097
0098 On success, the number of bytes read is returned. It is not an error if
0099 this number is smaller than the number of bytes requested, or the amount
0100 of data required for one frame. This may happen for example because
0101 :c:func:`read()` was interrupted by a signal. On error, -1 is
0102 returned, and the ``errno`` variable is set appropriately. In this case
0103 the next read will start at the beginning of a new frame. Possible error
0104 codes are:
0105
0106 EAGAIN
0107 Non-blocking I/O has been selected using O_NONBLOCK and no data was
0108 immediately available for reading.
0109
0110 EBADF
0111 ``fd`` is not a valid file descriptor or is not open for reading, or
0112 the process already has the maximum number of files open.
0113
0114 EBUSY
0115 The driver does not support multiple read streams and the device is
0116 already in use.
0117
0118 EFAULT
0119 ``buf`` references an inaccessible memory area.
0120
0121 EINTR
0122 The call was interrupted by a signal before any data was read.
0123
0124 EIO
0125 I/O error. This indicates some hardware problem or a failure to
0126 communicate with a remote device (USB camera etc.).
0127
0128 EINVAL
0129 The :c:func:`read()` function is not supported by this driver, not
0130 on this device, or generally not on this type of device.
