func-read.rst

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