Audio Library

Audio function summary

This chapter includes the following:

A listing of the library functions arranged into categories
A section describing the elements you'll find in a function description

QNX is committed to supporting the entire ALSA API; however, at this time we recommend using the following API subset for the creation of complex applications such as the mixer, DVD player, and RealPlayer.

Summary of function categories

We've organized these functions into the following categories:

Driver control functions
Playback functions
Volume and balance control functions

Driver control functions

These functions work with the drivers.

snd_ctl_close(): Close a control handle
snd_ctl_file_descriptor(): Get control file descriptor
snd_ctl_hw_info(): Get information about a soundcard
snd_ctl_open(): Open a control device
snd_ctl_read(): Read pending control events

Playback functions

These functions perform playback operations.

snd_pcm_build_linear_format(): Build a linear format
snd_pcm_channel_flush(): Flush buffers
snd_pcm_channel_info(): Get information about the PCM direction
snd_pcm_channel_params(): Set PCM communication parameters
snd_pcm_channel_prepare(): Prepare the selected direction
snd_pcm_channel_setup(): Get the current PCM setup
snd_pcm_channel_status(): Get current PCM runtime status
snd_pcm_close(): Free resources allocated with audio handle
snd_pcm_file_descriptor(): Return the file descriptor of the connection to the audio interface
snd_pcm_find(): Find all PCM devices in the system
snd_pcm_format_big_endian(): Check for big-endian format
snd_pcm_format_linear(): Check for linear format
snd_pcm_format_little_endian(): Check for little-endian format
snd_pcm_format_signed(): Check for signed format
snd_pcm_format_size(): Convert size in samples to bytes
snd_pcm_format_unsigned(): Check for unsigned format
snd_pcm_format_width(): Get sample width in bits
snd_pcm_get_format_name(): Convert a format member
snd_pcm_info(): Get general information about the PCM device
snd_pcm_nonblock_mode(): Set or reset the block behavior
snd_pcm_open(): Create a new handle and open a connection to the audio interface
snd_pcm_open_preferred(): Create a new handle and open a connection to the audio interface
snd_pcm_playback_drain(): Drain the playback queue
snd_pcm_plugin_flush(): Flush all unprocessed data in the driver queue
snd_pcm_plugin_info(): Get information about the PCM direction
snd_pcm_plugin_params(): Set PCM communication parameters
snd_pcm_plugin_playback_drain(): Drain playback queue
snd_pcm_plugin_prepare(): Prepare the selected direction
snd_pcm_plugin_read(): Transfer PCM stream from capture subdevice
snd_pcm_plugin_set_disable(): Disable plugins
snd_pcm_plugin_setup(): Get current PCM setup
snd_pcm_plugin_status(): Get current PCM runtime status
snd_pcm_plugin_write(): Transfer PCM stream to playback subdevice
snd_pcm_read(): Transfer PCM stream from capture subdevice
snd_pcm_write(): Transfer PCM stream to playback subdevice
snd_strerror(): Convert an error code to a string

Volume and balance control functions

These functions manipulate volume and balance.

snd_mixer_close(): Close a control handle
snd_mixer_group_read(): Read the snd_mixer_group_t structure
snd_mixer_group_write(): Write the snd_mixer_group_t structure
snd_mixer_groups(): Fill a structure with the number of groups in the mixer
snd_mixer_info(): Fill info with mixer device information
snd_mixer_open(): Create a new connection and handle to the mixer device
snd_mixer_read(): Read pending mixer events
snd_mixer_sort_gid_table(): Sort a list of group ID structures

What's in a function description?

Each description contains the following subsections:

Synopsis:

This subsection gives the header files that should be included within a source file that references the function or macro. It also shows an appropriate declaration for the function or for a function that could be substituted for a macro. This declaration isn't included in your program; only the header file(s) should be included.

When a pointer argument is passed to a function that doesn't modify the item indicated by that pointer, the argument is shown with const before the argument. For example, the following indicates that the array pointed at by string isn't changed:

const char *string

Description:

This subsection describes the function or macro.

Returns:

This subsection gives the return value (if any) for the function or macro.

Errors:

This subsection shows the possible values that the function might assign to the global variable errno.

Examples:

This optional subsection gives one or more examples of the use of the function. The examples are often just code snippets, not complete programs.

Classification:

This subsection tells where the function or macro is commonly found, which may be helpful when porting code from one environment to another. Here are the classes:

ALSA
Neutrino

ALSA: These functions or macros are part of ALSA v0.50.
Neutrino: These functions or macros perform a function related to Neutrino. They may be found in other implementations of C for personal computers with Neutrino. Use these functions with caution if portability is a consideration.

Function safety:

This subsection summarizes whether or not it's safe to use the C library functions in certain situations:

Cancellation point

Indicates whether calling a function may or may not cause the thread to be terminated if a cancellation is pending.

Interrupt handler

An interrupt-safe function behaves as documented even if used in an interrupt handler. Functions flagged as interrupt-unsafe shouldn't be used in interrupt handlers.

Signal handler

A signal-safe function behaves as documented even if called from a signal handler even if the signal interrupts a signal-unsafe function.

Some of the signal-safe functions modify errno on failure. If you use any of these in a signal handler, asynchronous signals may have the side effect of modifying errno in an unpredictable way. If any of the code that can be interrupted checks the value of errno (this also applies to library calls, so you should assume that most library calls may internally check errno), make sure that your signal handler saves errno on entry and restores it on exit.

All of the above also applies to signal-unsafe functions, with one exception: if a signal handler calls a signal-unsafe function, make sure that signal doesn't interrupt a signal-unsafe function.

Thread

A thread-safe function behaves as documented even if called in a multi-threaded environment.

Most functions in the Neutrino libraries are thread-safe. Even for those that aren't, there are still ways to call them safely in a multi-threaded program (e.g. by protecting the calls with a mutex). Such cases are explained in each function's description.