Documentation/media/uapi/v4l/func-read.rst

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