[deliverable/linux.git] / Documentation / linux_tv / media / v4l / vidioc-g-audioout.rst

.. -*- coding: utf-8; mode: rst -*-

.. _VIDIOC_G_AUDIOOUT:

**************************************
ioctl VIDIOC_G_AUDOUT, VIDIOC_S_AUDOUT
**************************************

*man VIDIOC_G_AUDOUT(2)*

VIDIOC_S_AUDOUT
Query or select the current audio output


Synopsis
========

.. cpp:function:: int ioctl( int fd, int request, struct v4l2_audioout *argp )

.. cpp:function:: int ioctl( int fd, int request, const struct v4l2_audioout *argp )

Arguments
=========

``fd``
    File descriptor returned by :ref:`open() <func-open>`.

``request``
    VIDIOC_G_AUDOUT, VIDIOC_S_AUDOUT

``argp``


Description
===========

To query the current audio output applications zero out the ``reserved``
array of a struct :ref:`v4l2_audioout <v4l2-audioout>` and call the
``VIDIOC_G_AUDOUT`` ioctl with a pointer to this structure. Drivers fill
the rest of the structure or return an EINVAL error code when the device
has no audio inputs, or none which combine with the current video
output.

Audio outputs have no writable properties. Nevertheless, to select the
current audio output applications can initialize the ``index`` field and
``reserved`` array (which in the future may contain writable properties)
of a :c:type:`struct v4l2_audioout` structure and call the
``VIDIOC_S_AUDOUT`` ioctl. Drivers switch to the requested output or
return the EINVAL error code when the index is out of bounds. This is a
write-only ioctl, it does not return the current audio output attributes
as ``VIDIOC_G_AUDOUT`` does.

Note connectors on a TV card to loop back the received audio signal to a
sound card are not audio outputs in this sense.


.. _v4l2-audioout:

.. flat-table:: struct v4l2_audioout
    :header-rows:  0
    :stub-columns: 0
    :widths:       1 1 2


    -  .. row 1

       -  __u32

       -  ``index``

       -  Identifies the audio output, set by the driver or application.

    -  .. row 2

       -  __u8

       -  ``name``\ [32]

       -  Name of the audio output, a NUL-terminated ASCII string, for
          example: "Line Out". This information is intended for the user,
          preferably the connector label on the device itself.

    -  .. row 3

       -  __u32

       -  ``capability``

       -  Audio capability flags, none defined yet. Drivers must set this
          field to zero.

    -  .. row 4

       -  __u32

       -  ``mode``

       -  Audio mode, none defined yet. Drivers and applications (on
          ``VIDIOC_S_AUDOUT``) must set this field to zero.

    -  .. row 5

       -  __u32

       -  ``reserved``\ [2]

       -  Reserved for future extensions. Drivers and applications must set
          the array to zero.


Return Value
============

On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.

EINVAL
    No audio outputs combine with the current video output, or the
    number of the selected audio output is out of bounds or it does not
    combine.


.. ------------------------------------------------------------------------------
.. This file was automatically converted from DocBook-XML with the dbxml
.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
.. from the linux kernel, refer to:
..
.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
.. ------------------------------------------------------------------------------
Commit	Line	Data
5377d91f MH	1	.. -- coding: utf-8; mode: rst --
5377d91f MH	2
af4a4d0d	3	.. _VIDIOC_G_AUDIOOUT:
5377d91f MH	4
	5	**************************************
	6	ioctl VIDIOC_G_AUDOUT, VIDIOC_S_AUDOUT
	7	**************************************
	8
	9	man VIDIOC_G_AUDOUT(2)
	10
	11	VIDIOC_S_AUDOUT
	12	Query or select the current audio output
	13
	14
	15	Synopsis
	16	========
	17
b7e67f6c	18	.. cpp:function:: int ioctl( int fd, int request, struct v4l2_audioout *argp )
5377d91f	19
b7e67f6c	20	.. cpp:function:: int ioctl( int fd, int request, const struct v4l2_audioout *argp )
5377d91f MH	21
	22	Arguments
	23	=========
	24
	25	``fd``
	26	File descriptor returned by :ref:`open() <func-open>`.
	27
	28	``request``
	29	VIDIOC_G_AUDOUT, VIDIOC_S_AUDOUT
	30
	31	``argp``
	32
	33
	34	Description
	35	===========
	36
	37	To query the current audio output applications zero out the ``reserved``
	38	array of a struct :ref:`v4l2_audioout <v4l2-audioout>` and call the
	39	``VIDIOC_G_AUDOUT`` ioctl with a pointer to this structure. Drivers fill
	40	the rest of the structure or return an EINVAL error code when the device
	41	has no audio inputs, or none which combine with the current video
	42	output.
	43
	44	Audio outputs have no writable properties. Nevertheless, to select the
	45	current audio output applications can initialize the ``index`` field and
	46	``reserved`` array (which in the future may contain writable properties)
	47	of a :c:type:`struct v4l2_audioout` structure and call the
	48	``VIDIOC_S_AUDOUT`` ioctl. Drivers switch to the requested output or
	49	return the EINVAL error code when the index is out of bounds. This is a
	50	write-only ioctl, it does not return the current audio output attributes
	51	as ``VIDIOC_G_AUDOUT`` does.
	52
	53	Note connectors on a TV card to loop back the received audio signal to a
	54	sound card are not audio outputs in this sense.
	55
	56
	57	.. _v4l2-audioout:
	58
	59	.. flat-table:: struct v4l2_audioout
	60	:header-rows: 0
	61	:stub-columns: 0
	62	:widths: 1 1 2
	63
	64
	65	- .. row 1
	66
	67	- __u32
	68
	69	- ``index``
	70
	71	- Identifies the audio output, set by the driver or application.
	72
	73	- .. row 2
	74
	75	- __u8
	76
	77	- ``name``\ [32]
	78
	79	- Name of the audio output, a NUL-terminated ASCII string, for
	80	example: "Line Out". This information is intended for the user,
	81	preferably the connector label on the device itself.
	82
	83	- .. row 3
	84
85	- __u32
86
87	- ``capability``
88
89	- Audio capability flags, none defined yet. Drivers must set this
90	field to zero.
91
92	- .. row 4
93
94	- __u32
95
96	- ``mode``
97
98	- Audio mode, none defined yet. Drivers and applications (on
99	``VIDIOC_S_AUDOUT``) must set this field to zero.
100
101	- .. row 5
102
103	- __u32
104
105	- ``reserved``\ [2]
106
107	- Reserved for future extensions. Drivers and applications must set
108	the array to zero.
109
110
111
112	Return Value
113	============
114
115	On success 0 is returned, on error -1 and the ``errno`` variable is set
116	appropriately. The generic error codes are described at the
117	:ref:`Generic Error Codes <gen-errors>` chapter.
118
119	EINVAL
120	No audio outputs combine with the current video output, or the
121	number of the selected audio output is out of bounds or it does not
122	combine.
123
124
125	.. ------------------------------------------------------------------------------
126	.. This file was automatically converted from DocBook-XML with the dbxml
127	.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
128	.. from the linux kernel, refer to:
129	..
130	.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
131	.. ------------------------------------------------------------------------------