1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
2
3.. _VIDIOC_G_AUDOUT:
4
5**************************************
6ioctl VIDIOC_G_AUDOUT, VIDIOC_S_AUDOUT
7**************************************
8
9Name
10====
11
12VIDIOC_G_AUDOUT - VIDIOC_S_AUDOUT - Query or select the current audio output
13
14
15Synopsis
16========
17
18.. c:function:: int ioctl( int fd, VIDIOC_G_AUDOUT, struct v4l2_audioout *argp )
19    :name: VIDIOC_G_AUDOUT
20
21.. c:function:: int ioctl( int fd, VIDIOC_S_AUDOUT, const struct v4l2_audioout *argp )
22    :name: VIDIOC_S_AUDOUT
23
24
25Arguments
26=========
27
28``fd``
29    File descriptor returned by :ref:`open() <func-open>`.
30
31``argp``
32    Pointer to struct :c:type:`v4l2_audioout`.
33
34
35Description
36===========
37
38To query the current audio output applications zero out the ``reserved``
39array of a struct :c:type:`v4l2_audioout` and call the
40``VIDIOC_G_AUDOUT`` ioctl with a pointer to this structure. Drivers fill
41the rest of the structure or return an ``EINVAL`` error code when the device
42has no audio inputs, or none which combine with the current video
43output.
44
45Audio outputs have no writable properties. Nevertheless, to select the
46current audio output applications can initialize the ``index`` field and
47``reserved`` array (which in the future may contain writable properties)
48of a struct :c:type:`v4l2_audioout` structure and call the
49``VIDIOC_S_AUDOUT`` ioctl. Drivers switch to the requested output or
50return the ``EINVAL`` error code when the index is out of bounds. This is a
51write-only ioctl, it does not return the current audio output attributes
52as ``VIDIOC_G_AUDOUT`` does.
53
54.. note::
55
56   Connectors on a TV card to loop back the received audio signal
57   to a sound card are not audio outputs in this sense.
58
59
60.. c:type:: v4l2_audioout
61
62.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
63
64.. flat-table:: struct v4l2_audioout
65    :header-rows:  0
66    :stub-columns: 0
67    :widths:       1 1 2
68
69    * - __u32
70      - ``index``
71      - Identifies the audio output, set by the driver or application.
72    * - __u8
73      - ``name``\ [32]
74      - Name of the audio output, a NUL-terminated ASCII string, for
75	example: "Line Out". This information is intended for the user,
76	preferably the connector label on the device itself.
77    * - __u32
78      - ``capability``
79      - Audio capability flags, none defined yet. Drivers must set this
80	field to zero.
81    * - __u32
82      - ``mode``
83      - Audio mode, none defined yet. Drivers and applications (on
84	``VIDIOC_S_AUDOUT``) must set this field to zero.
85    * - __u32
86      - ``reserved``\ [2]
87      - Reserved for future extensions. Drivers and applications must set
88	the array to zero.
89
90
91Return Value
92============
93
94On success 0 is returned, on error -1 and the ``errno`` variable is set
95appropriately. The generic error codes are described at the
96:ref:`Generic Error Codes <gen-errors>` chapter.
97
98EINVAL
99    No audio outputs combine with the current video output, or the
100    number of the selected audio output is out of bounds or it does not
101    combine.
102