1 .. -*- coding: utf-8; mode: rst -*-
5 ***************************************
6 ioctl VIDIOC_STREAMON, VIDIOC_STREAMOFF
7 ***************************************
12 VIDIOC_STREAMON - VIDIOC_STREAMOFF - Start or stop streaming I/O
17 .. cpp:function:: int ioctl( int fd, int request, const int *argp )
24 File descriptor returned by :ref:`open() <func-open>`.
27 VIDIOC_STREAMON, VIDIOC_STREAMOFF
35 The ``VIDIOC_STREAMON`` and ``VIDIOC_STREAMOFF`` ioctl start and stop
36 the capture or output process during streaming
37 (:ref:`memory mapping <mmap>`, :ref:`user pointer <userp>` or
38 :ref:`DMABUF <dmabuf>`) I/O.
40 Capture hardware is disabled and no input buffers are filled (if there
41 are any empty buffers in the incoming queue) until ``VIDIOC_STREAMON``
42 has been called. Output hardware is disabled and no video signal is
43 produced until ``VIDIOC_STREAMON`` has been called. The ioctl will
44 succeed when at least one output buffer is in the incoming queue.
46 Memory-to-memory devices will not start until ``VIDIOC_STREAMON`` has
47 been called for both the capture and output stream types.
49 If ``VIDIOC_STREAMON`` fails then any already queued buffers will remain
52 The ``VIDIOC_STREAMOFF`` ioctl, apart of aborting or finishing any DMA
53 in progress, unlocks any user pointer buffers locked in physical memory,
54 and it removes all buffers from the incoming and outgoing queues. That
55 means all images captured but not dequeued yet will be lost, likewise
56 all images enqueued for output but not transmitted yet. I/O returns to
57 the same state as after calling
58 :ref:`VIDIOC_REQBUFS` and can be restarted
61 If buffers have been queued with :ref:`VIDIOC_QBUF` and
62 ``VIDIOC_STREAMOFF`` is called without ever having called
63 ``VIDIOC_STREAMON``, then those queued buffers will also be removed from
64 the incoming queue and all are returned to the same state as after
65 calling :ref:`VIDIOC_REQBUFS` and can be restarted
68 Both ioctls take a pointer to an integer, the desired buffer or stream
69 type. This is the same as struct
70 :ref:`v4l2_requestbuffers <v4l2-requestbuffers>` ``type``.
72 If ``VIDIOC_STREAMON`` is called when streaming is already in progress,
73 or if ``VIDIOC_STREAMOFF`` is called when streaming is already stopped,
74 then 0 is returned. Nothing happens in the case of ``VIDIOC_STREAMON``,
75 but ``VIDIOC_STREAMOFF`` will return queued buffers to their starting
76 state as mentioned above.
78 Note that applications can be preempted for unknown periods right before
79 or after the ``VIDIOC_STREAMON`` or ``VIDIOC_STREAMOFF`` calls, there is
80 no notion of starting or stopping "now". Buffer timestamps can be used
81 to synchronize with other events.
87 On success 0 is returned, on error -1 and the ``errno`` variable is set
88 appropriately. The generic error codes are described at the
89 :ref:`Generic Error Codes <gen-errors>` chapter.
92 The buffer ``type`` is not supported, or no buffers have been
93 allocated (memory mapping) or enqueued (output) yet.
97 :ref:`pad-level format configuration <pad-level-formats>` and the
98 pipeline configuration is invalid.
101 The driver implements Media Controller interface and the pipeline
102 link configuration is invalid.