media/v4l/func-read.rst

1 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
4 .. _func-read:
7 V4L2 read()
13 v4l2-read - Read from a V4L2 device
18 .. code-block:: c
22 .. c:function:: ssize_t read( int fd, void *buf, size_t count )
31    Buffer to be filled
34   Max number of bytes to read
39 :c:func:`read()` attempts to read up to ``count`` bytes from file
42 section, see ##. If ``count`` is zero, :c:func:`read()` returns zero
45 :c:func:`read()` call will provide at most one frame (two fields)
48 By default :c:func:`read()` blocks until data becomes available. When
49 the ``O_NONBLOCK`` flag was given to the :c:func:`open()`
52 :c:func:`poll()` functions can always be used to suspend
54 :c:func:`read()` function must also support :c:func:`select()` and
57 Drivers can implement read functionality in different ways, using a
61 :c:func:`read()` never returns a "snapshot" of a buffer being filled.
63 application starts reading the buffer until the read is finished. Thus
68 The behavior of :c:func:`read()` when called during the active picture
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.
76 :c:func:`read()` call. The frame being received at :c:func:`read()`
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()`
84 buffers, automatically advancing to the next free buffer. This allows
98 On success, the number of bytes read is returned. It is not an error if
101 :c:func:`read()` was interrupted by a signal. On error, -1 is
103 the next read will start at the beginning of a new frame. Possible error
107     Non-blocking I/O has been selected using O_NONBLOCK and no data was
115     The driver does not support multiple read streams and the device is
122     The call was interrupted by a signal before any data was read.
125     I/O error. This indicates some hardware problem or a failure to
129     The :c:func:`read()` function is not supported by this driver, not