1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
2.. c:namespace:: V4L
3
4.. _io:
5
6############
7Input/Output
8############
9The V4L2 API defines several different methods to read from or write to
10a device. All drivers exchanging data with applications must support at
11least one of them.
12
13The classic I/O method using the :c:func:`read()` and
14:c:func:`write()` function is automatically selected after opening a
15V4L2 device. When the driver does not support this method attempts to
16read or write will fail at any time.
17
18Other methods must be negotiated. To select the streaming I/O method
19with memory mapped or user buffers applications call the
20:ref:`VIDIOC_REQBUFS` ioctl. The asynchronous I/O
21method is not defined yet.
22
23Video overlay can be considered another I/O method, although the
24application does not directly receive the image data. It is selected by
25initiating video overlay with the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`
26ioctl. For more information see :ref:`overlay`.
27
28Generally exactly one I/O method, including overlay, is associated with
29each file descriptor. The only exceptions are applications not
30exchanging data with a driver ("panel applications", see :ref:`open`)
31and drivers permitting simultaneous video capturing and overlay using
32the same file descriptor, for compatibility with V4L and earlier
33versions of V4L2.
34
35:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` and :ref:`VIDIOC_REQBUFS` would permit this to some
36degree, but for simplicity drivers need not support switching the I/O
37method (after first switching away from read/write) other than by
38closing and reopening the device.
39
40The following sections describe the various I/O methods in more detail.
41
42.. toctree::
43    :maxdepth: 1
44
45    rw
46    mmap
47    userp
48    dmabuf
49    async
50    buffer
51    field-order
52