snd_pcm_plugin_write()

Transfer PCM data to playback channel (plugin-aware)

Synopsis:

#include <sys/asoundlib.h>

ssize_t snd_pcm_plugin_write( snd_pcm_t *handle, 
                              const void *buffer,
                              size_t size );

Arguments:

handle

The handle for the PCM device, which you must have opened by calling snd_pcm_open() or snd_pcm_open_preferred().

buffer

A pointer to a buffer that contains the data to be written.

size

The size of the data, in bytes.

Library:

libasound.so

Description:

The snd_pcm_plugin_write() function writes samples that are in the proper format specified by snd_pcm_plugin_params() to the device specified by handle.

---

The handle and the buffer must be valid.

---

If you're using SND_SRC_MODE_ACTUAL or SND_SRC_MODE_ASYNC mode (see snd_pcm_plugin_set_src_mode()), you need to call snd_pcm_plugin_update_src() after each call to snd_pcm_plugin_write().

Returns:

A positive value that represents the number of bytes that were successfully written to the device if the playback was successful. A value less than the write request size is an indication of an error; for more information, check the errno value and call snd_pcm_plugin_status().

Errors:

EAGAIN

Try again later. The subchannel is opened nonblock.

EINVAL

Partial block buffering is disabled, but the size isn't the full block size.

EIO

One of:

• The channel isn't in the prepared or running state.

  ---

  If you're writing less than a fragment-sized block, you won't get this error until enough write operations have been completed to write the fragment size. The sub-buffering plugin buffers all operations until there's a fragment's worth of data, at which point the message to io-audio occurs (you can't get an error until the request goes to io-audio).

  ---

• In SND_PCM_MODE_BLOCK mode, the size isn't an even multiple of the frag_size member of the snd_pcm_channel_setup_t structure and PCM subbuffering has been disabled with snd_pcm_plugin_set_disable().

EWOULDBLOCK

The write would have blocked (nonblocking write).

Examples:

See the wave.c example in the appendix.

Classification:

QNX Neutrino

Caveats:

This function is the plugin-aware version of snd_pcm_write(). It functions exactly the same way, with one caveat (see below). However, make sure that you don't mix and match plugin- and nonplugin-aware functions in your application, or you may get undefined behavior and misleading results.

The plugin-aware versions of the PCM read and write calls don't require that you work with multiples of fragment-size blocks (the nonplugin-aware versions do). This is because one of the plugins in the lib sub-buffers the data for you. You can disable this plugin by setting the PLUGIN_DISABLE_BUFFER_PARTIAL_BLOCKS bit with snd_pcm_plugin_set_disable(), in which case, the plugin-aware versions also fail on reads and writes that aren't multiples of the fragment size.

Either way, interleaved stereo data has to be aligned by the sample size times the number of channels (i.e. each write must have the same number of samples for the left and right channels).

See also:

snd_pcm_plugin_read(), snd_pcm_plugin_set_disable(), snd_pcm_plugin_set_src_mode(), snd_pcm_plugin_update_src(), snd_pcm_write()