1<refentry id="vidioc-g-audioout">
2  <refmeta>
3    <refentrytitle>ioctl VIDIOC_G_AUDOUT, VIDIOC_S_AUDOUT</refentrytitle>
4    &manvol;
5  </refmeta>
6
7  <refnamediv>
8    <refname>VIDIOC_G_AUDOUT</refname>
9    <refname>VIDIOC_S_AUDOUT</refname>
10    <refpurpose>Query or select the current audio output</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>struct v4l2_audioout *<parameter>argp</parameter></paramdef>
20      </funcprototype>
21    </funcsynopsis>
22    <funcsynopsis>
23      <funcprototype>
24	<funcdef>int <function>ioctl</function></funcdef>
25	<paramdef>int <parameter>fd</parameter></paramdef>
26	<paramdef>int <parameter>request</parameter></paramdef>
27	<paramdef>const struct v4l2_audioout *<parameter>argp</parameter></paramdef>
28      </funcprototype>
29    </funcsynopsis>
30  </refsynopsisdiv>
31
32  <refsect1>
33    <title>Arguments</title>
34
35    <variablelist>
36      <varlistentry>
37	<term><parameter>fd</parameter></term>
38	<listitem>
39	  <para>&fd;</para>
40	</listitem>
41      </varlistentry>
42      <varlistentry>
43	<term><parameter>request</parameter></term>
44	<listitem>
45	  <para>VIDIOC_G_AUDOUT, VIDIOC_S_AUDOUT</para>
46	</listitem>
47      </varlistentry>
48      <varlistentry>
49	<term><parameter>argp</parameter></term>
50	<listitem>
51	  <para></para>
52	</listitem>
53      </varlistentry>
54    </variablelist>
55  </refsect1>
56
57  <refsect1>
58    <title>Description</title>
59
60    <para>To query the current audio output applications zero out the
61<structfield>reserved</structfield> array of a &v4l2-audioout; and
62call the <constant>VIDIOC_G_AUDOUT</constant> ioctl with a pointer
63to this structure. Drivers fill the rest of the structure or return an
64&EINVAL; when the device has no audio inputs, or none which combine
65with the current video output.</para>
66
67    <para>Audio outputs have no writable properties. Nevertheless, to
68select the current audio output applications can initialize the
69<structfield>index</structfield> field and
70<structfield>reserved</structfield> array (which in the future may
71contain writable properties) of a
72<structname>v4l2_audioout</structname> structure and call the
73<constant>VIDIOC_S_AUDOUT</constant> ioctl. Drivers switch to the
74requested output or return the &EINVAL; when the index is out of
75bounds. This is a write-only ioctl, it does not return the current
76audio output attributes as <constant>VIDIOC_G_AUDOUT</constant>
77does.</para>
78
79    <para>Note connectors on a TV card to loop back the received audio
80signal to a sound card are not audio outputs in this sense.</para>
81
82    <table pgwide="1" frame="none" id="v4l2-audioout">
83      <title>struct <structname>v4l2_audioout</structname></title>
84      <tgroup cols="3">
85	&cs-str;
86	<tbody valign="top">
87	  <row>
88	    <entry>__u32</entry>
89	    <entry><structfield>index</structfield></entry>
90	    <entry>Identifies the audio output, set by the
91driver or application.</entry>
92	  </row>
93	  <row>
94	    <entry>__u8</entry>
95	    <entry><structfield>name</structfield>[32]</entry>
96	    <entry>Name of the audio output, a NUL-terminated ASCII
97string, for example: "Line Out". This information is intended for the
98user, preferably the connector label on the device itself.</entry>
99	  </row>
100	  <row>
101	    <entry>__u32</entry>
102	    <entry><structfield>capability</structfield></entry>
103	    <entry>Audio capability flags, none defined yet. Drivers
104must set this field to zero.</entry>
105	  </row>
106	  <row>
107	    <entry>__u32</entry>
108	    <entry><structfield>mode</structfield></entry>
109	    <entry>Audio mode, none defined yet. Drivers and
110applications (on <constant>VIDIOC_S_AUDOUT</constant>) must set this
111field to zero.</entry>
112	  </row>
113	  <row>
114	    <entry>__u32</entry>
115	    <entry><structfield>reserved</structfield>[2]</entry>
116	    <entry>Reserved for future extensions. Drivers and
117applications must set the array to zero.</entry>
118	  </row>
119	</tbody>
120      </tgroup>
121    </table>
122  </refsect1>
123
124  <refsect1>
125    &return-value;
126
127    <variablelist>
128      <varlistentry>
129	<term><errorcode>EINVAL</errorcode></term>
130	<listitem>
131	  <para>No audio outputs combine with the current video
132output, or the number of the selected audio output is out of bounds or
133it does not combine.</para>
134	</listitem>
135      </varlistentry>
136    </variablelist>
137  </refsect1>
138</refentry>
139