1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
2.. c:namespace:: V4L
3
4.. _VIDIOC_STREAMON:
5
6***************************************
7ioctl VIDIOC_STREAMON, VIDIOC_STREAMOFF
8***************************************
9
10Name
11====
12
13VIDIOC_STREAMON - VIDIOC_STREAMOFF - Start or stop streaming I/O
14
15Synopsis
16========
17
18.. c:macro:: VIDIOC_STREAMON
19
20``int ioctl(int fd, VIDIOC_STREAMON, const int *argp)``
21
22.. c:macro:: VIDIOC_STREAMOFF
23
24``int ioctl(int fd, VIDIOC_STREAMOFF, const int *argp)``
25
26Arguments
27=========
28
29``fd``
30    File descriptor returned by :c:func:`open()`.
31
32``argp``
33    Pointer to an integer.
34
35Description
36===========
37
38The ``VIDIOC_STREAMON`` and ``VIDIOC_STREAMOFF`` ioctl start and stop
39the capture or output process during streaming
40(:ref:`memory mapping <mmap>`, :ref:`user pointer <userp>` or
41:ref:`DMABUF <dmabuf>`) I/O.
42
43Capture hardware is disabled and no input buffers are filled (if there
44are any empty buffers in the incoming queue) until ``VIDIOC_STREAMON``
45has been called. Output hardware is disabled and no video signal is
46produced until ``VIDIOC_STREAMON`` has been called. The ioctl will
47succeed when at least one output buffer is in the incoming queue.
48
49Memory-to-memory devices will not start until ``VIDIOC_STREAMON`` has
50been called for both the capture and output stream types.
51
52If ``VIDIOC_STREAMON`` fails then any already queued buffers will remain
53queued.
54
55The ``VIDIOC_STREAMOFF`` ioctl, apart of aborting or finishing any DMA
56in progress, unlocks any user pointer buffers locked in physical memory,
57and it removes all buffers from the incoming and outgoing queues. That
58means all images captured but not dequeued yet will be lost, likewise
59all images enqueued for output but not transmitted yet. I/O returns to
60the same state as after calling
61:ref:`VIDIOC_REQBUFS` and can be restarted
62accordingly.
63
64If buffers have been queued with :ref:`VIDIOC_QBUF` and
65``VIDIOC_STREAMOFF`` is called without ever having called
66``VIDIOC_STREAMON``, then those queued buffers will also be removed from
67the incoming queue and all are returned to the same state as after
68calling :ref:`VIDIOC_REQBUFS` and can be restarted
69accordingly.
70
71Both ioctls take a pointer to an integer, the desired buffer or stream
72type. This is the same as struct
73:c:type:`v4l2_requestbuffers` ``type``.
74
75If ``VIDIOC_STREAMON`` is called when streaming is already in progress,
76or if ``VIDIOC_STREAMOFF`` is called when streaming is already stopped,
77then 0 is returned. Nothing happens in the case of ``VIDIOC_STREAMON``,
78but ``VIDIOC_STREAMOFF`` will return queued buffers to their starting
79state as mentioned above.
80
81.. note::
82
83   Applications can be preempted for unknown periods right before
84   or after the ``VIDIOC_STREAMON`` or ``VIDIOC_STREAMOFF`` calls, there is
85   no notion of starting or stopping "now". Buffer timestamps can be used
86   to synchronize with other events.
87
88Return Value
89============
90
91On success 0 is returned, on error -1 and the ``errno`` variable is set
92appropriately. The generic error codes are described at the
93:ref:`Generic Error Codes <gen-errors>` chapter.
94
95EINVAL
96    The buffer ``type`` is not supported, or no buffers have been
97    allocated (memory mapping) or enqueued (output) yet.
98
99EPIPE
100    The driver implements
101    :ref:`pad-level format configuration <pad-level-formats>` and the
102    pipeline configuration is invalid.
103
104ENOLINK
105    The driver implements Media Controller interface and the pipeline
106    link configuration is invalid.
107