snd_pcm_read()

Updated: April 19, 2023

Transfer PCM data from the capture channel

Synopsis:

#include <sys/asoundlib.h>

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

Arguments:

handle
The handle for the PCM device, which you must have opened by calling snd_pcm_open_name(), snd_pcm_open(), or snd_pcm_open_preferred().
buffer
A pointer to a buffer in which snd_pcm_read() can store the data that it reads.
size
The size of the buffer, in bytes.

Library:

libasound.so

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

Description:

The snd_pcm_read() function reads samples from the device, which must be in the proper format specified by snd_pcm_channel_prepare() or snd_pcm_capture_prepare().

This function may suspend the client application if the blocking behavior is active (see snd_pcm_nonblock_mode()) and no data is available to be read.

When the subdevice is in block mode (SND_PCM_MODE_BLOCK), then the number of read bytes must fulfill the N × fragment-size expression, where N > 0.

If the stream format is noninterleaved (i.e., the interleave member of the snd_pcm_format_t structure isn't set), then the driver returns data that's separated to single voice blocks encapsulated to fragments. For example, imagine you have two voices, and the fragment size is 512 bytes. The number of bytes per one voice is 256. The driver returns the first 256 bytes that contain samples for the first voice, and the second 256 bytes from the fragment size that contains samples for the second voice.

Returns:

A positive value that represents the number of bytes that were successfully read from the device if the capture was successful, or a negative value if an error occurred.

Errors:

-EAGAIN
The subdevice has no data available.
-EFAULT
Failed to copy data.
-EINVAL
The state of handle is invalid or an invalid state change occurred. You can call snd_pcm_channel_status() to check if the state change was invalid.
-EIO
The channel isn't in the prepared or running state.

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 handle (snd_pcm_t) is used across multiple threads.