1<refentry id="vidioc-streamon">
2  <refmeta>
3    <refentrytitle>ioctl VIDIOC_STREAMON, VIDIOC_STREAMOFF</refentrytitle>
4    &manvol;
5  </refmeta>
6
7  <refnamediv>
8    <refname>VIDIOC_STREAMON</refname>
9    <refname>VIDIOC_STREAMOFF</refname>
10    <refpurpose>Start or stop streaming I/O</refpurpose>
11  </refnamediv>
12
13  <refsynopsisdiv>
14    <funcsynopsis>
15      <funcprototype>
16	<funcdef>int <function>ioctl</function></funcdef>
17	<paramdef>int <parameter>fd</parameter></paramdef>
18	<paramdef>int <parameter>request</parameter></paramdef>
19	<paramdef>const int *<parameter>argp</parameter></paramdef>
20      </funcprototype>
21    </funcsynopsis>
22  </refsynopsisdiv>
23
24  <refsect1>
25    <title>Arguments</title>
26
27    <variablelist>
28      <varlistentry>
29	<term><parameter>fd</parameter></term>
30	<listitem>
31	  <para>&fd;</para>
32	</listitem>
33      </varlistentry>
34      <varlistentry>
35	<term><parameter>request</parameter></term>
36	<listitem>
37	  <para>VIDIOC_STREAMON, VIDIOC_STREAMOFF</para>
38	</listitem>
39      </varlistentry>
40      <varlistentry>
41	<term><parameter>argp</parameter></term>
42	<listitem>
43	  <para></para>
44	</listitem>
45      </varlistentry>
46    </variablelist>
47  </refsect1>
48
49  <refsect1>
50    <title>Description</title>
51
52    <para>The <constant>VIDIOC_STREAMON</constant> and
53<constant>VIDIOC_STREAMOFF</constant> ioctl start and stop the capture
54or output process during streaming (<link linkend="mmap">memory
55mapping</link> or <link linkend="userp">user pointer</link>) I/O.</para>
56
57    <para>Specifically the capture hardware is disabled and no input
58buffers are filled (if there are any empty buffers in the incoming
59queue) until <constant>VIDIOC_STREAMON</constant> has been called.
60Accordingly the output hardware is disabled, no video signal is
61produced until <constant>VIDIOC_STREAMON</constant> has been called.
62The ioctl will succeed only when at least one output buffer is in the
63incoming queue.</para>
64
65    <para>The <constant>VIDIOC_STREAMOFF</constant> ioctl, apart of
66aborting or finishing any DMA in progress, unlocks any user pointer
67buffers locked in physical memory, and it removes all buffers from the
68incoming and outgoing queues. That means all images captured but not
69dequeued yet will be lost, likewise all images enqueued for output but
70not transmitted yet. I/O returns to the same state as after calling
71&VIDIOC-REQBUFS; and can be restarted accordingly.</para>
72
73    <para>Both ioctls take a pointer to an integer, the desired buffer or
74stream type. This is the same as &v4l2-requestbuffers;
75<structfield>type</structfield>.</para>
76
77    <para>Note applications can be preempted for unknown periods right
78before or after the <constant>VIDIOC_STREAMON</constant> or
79<constant>VIDIOC_STREAMOFF</constant> calls, there is no notion of
80starting or stopping "now". Buffer timestamps can be used to
81synchronize with other events.</para>
82  </refsect1>
83
84  <refsect1>
85    &return-value;
86
87    <variablelist>
88      <varlistentry>
89	<term><errorcode>EINVAL</errorcode></term>
90	<listitem>
91	  <para>The buffer<structfield>type</structfield> is not supported,
92	  or no buffers have been allocated (memory mapping) or enqueued
93	  (output) yet.</para>
94	</listitem>
95      </varlistentry>
96      <varlistentry>
97	<term><errorcode>EPIPE</errorcode></term>
98	<listitem>
99	  <para>The driver implements <link
100	  linkend="pad-level-formats">pad-level format configuration</link> and
101	  the pipeline configuration is invalid.
102	  </para>
103	</listitem>
104      </varlistentry>
105    </variablelist>
106  </refsect1>
107</refentry>
108