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