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

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