snd_pcm_link()

Link two PCM streams together

Synopsis:

#include <sys/asoundlib.h>

int snd_pcm_link( snd_pcm_t *pcm1,
                  snd_pcm_t *pcm2 );

Arguments:

pcm1, pcm2
The handles for the PCM devices, which you must have opened by calling snd_pcm_open_name(), snd_pcm_open(), or snd_pcm_open_preferred().
Tip: If you Audio component BuildID 237—June 29, 2017 (7.0.237.S201706290957) or a later update installed, the description for the arguments is as follows:
  • pcm1—A PCM handle that may or may not belong to a group.
  • pcm2—A PCM handle that must not belong to an existing group.

Library:

libasound.so

Use the -l asound option to qcc to link against this library.

Description:

The snd_pcm_link() function links two PCM streams together such that they always play at the same time. Starting one starts the other, and stopping one stops the other. When you have audio subchannels grouped together using snd_pcm_link(), you can start the audio streams only by meeting the start mode condition.

Tip: If you have Audio component update-BuildID 237 (7.0.237.S201706290957) or a later update installed, the behavior of this function is as follows:

You can link two PCM streams (either playing or capturing) together such that they always stream at the same time. Starting one stream causes the other streams in the group to start. When audio management is applied to the PCM streams for playback, the subchannels in the PCM link group are treated as a single audio stream (or session). You can set the mode if you don't want the default synchronous behavior using snd_pcm_link_mode(). Regardless of the mode you choose, audio management policies are applied to the grouped PCM streams as single audio stream.

PCM handles for playback must have the same audio type for this function to create a new link to a group; otherwise the call fails. In addition, pcm2 mustn't already belong to a PCM link group. PCM handles for capture aren't required to be the same audio type.

Previously, when you grouped audio subchannels together using the snd_pcm_link() call, you could start the audio streams only by meeting the start mode condition. This update permits you to call snd_pcm_*_resume(), snd_pcm_*_pause(), and snd_pcm_*_prepare() on the grouped PCM handles to start the audio stream.

This default behavior is referred to as synchronized behavior and is the default PCM link mode (SND_PCM_LINK_MODE_SYNC). You can change this behavior using the snd_pcm_link_mode() and snd_pcm_transition() functions.

Returns:

EOK on success, or a positive errno value if an error occurred.

Classification:

QNX Neutrino

Safety:  
Cancellation point No
Interrupt handler No
Signal handler Yes
Thread Read the Caveats

Caveats:

This function is not thread safe if pcm1 or pcm2(snd_pcm_t) are used across multiple threads.