ALSA project - the C library reference
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Macros | Typedefs | Functions
Global defines and functions

Macros

#define __SND_DLSYM_VERSION(name, version)
 Helper macro for SND_DLSYM_BUILD_VERSION.
#define SND_DLSYM_BUILD_VERSION(name, version)
 Appends the build version to the name of a versioned dynamic symbol.
#define __STRING(x)   #x
 Return 'x' argument as string.
#define SND_DLSYM_VERSION(version)   __STRING(version)
 Returns the version of a dynamic symbol as a string.
#define __snd_alloca(ptr, type)   do { *ptr = (type##_t *) alloca(type##_sizeof()); memset(*ptr, 0, type##_sizeof()); } while (0)
 alloca helper macro.

Typedefs

typedef struct _snd_async_handler snd_async_handler_t
 Internal structure for an async notification client handler.
typedef void(* snd_async_callback_t )(snd_async_handler_t *handler)
 Async notification callback.
typedef struct timeval snd_timestamp_t
typedef struct timespec snd_htimestamp_t

Functions

const char * snd_asoundlib_version (void)
 Returns the ALSA sound library version in ASCII format.
void * snd_dlopen (const char *file, int mode)
 Opens a dynamic library - ALSA wrapper for dlopen.
void * snd_dlsym (void *handle, const char *name, const char *version)
 Resolves a symbol from a dynamic library - ALSA wrapper for dlsym.
int snd_dlclose (void *handle)
 Closes a dynamic library - ALSA wrapper for dlclose.
int snd_async_add_handler (snd_async_handler_t **handler, int fd, snd_async_callback_t callback, void *private_data)
 Registers an async handler.
int snd_async_del_handler (snd_async_handler_t *handler)
 Deletes an async handler.
int snd_async_handler_get_fd (snd_async_handler_t *handler)
 Returns the file descriptor assigned to an async handler.
int snd_async_handler_get_signo (snd_async_handler_t *handler)
 Returns the signal number assigned to an async handler.
void * snd_async_handler_get_callback_private (snd_async_handler_t *handler)
 Returns the private data assigned to an async handler.
struct snd_shm_area * snd_shm_area_create (int shmid, void *ptr)
 Create a shm area record.
struct snd_shm_area * snd_shm_area_share (struct snd_shm_area *area)
 Increase the reference counter of shm area record.
int snd_shm_area_destroy (struct snd_shm_area *area)
 Release the shared area record.
int snd_user_file (const char *file, char **result)
 Get the full file name.

Detailed Description

Global defines and functions.

The ALSA library implementation uses these macros and functions. Most applications probably do not need them.

Typedef Documentation

typedef void(* snd_async_callback_t)(snd_async_handler_t *handler)

Async notification callback.

See the snd_async_add_handler function for details.

typedef struct _snd_async_handler snd_async_handler_t

Internal structure for an async notification client handler.

The ALSA library uses a pointer to this structure as a handle to an async notification object. Applications don't access its contents directly.

typedef struct timespec snd_htimestamp_t

Hi-res timestamp

typedef struct timeval snd_timestamp_t

Timestamp


Function Documentation

const char* snd_asoundlib_version ( void  )

Returns the ALSA sound library version in ASCII format.

Returns:
The ASCII description of the used ALSA sound library.
int snd_async_add_handler ( snd_async_handler_t **  handler,
int  fd,
snd_async_callback_t  callback,
void *  private_data 
)

Registers an async handler.

Parameters:
handlerThe function puts the pointer to the new async handler object at the address specified by handler.
fdThe file descriptor to be associated with the callback.
callbackThe async callback function.
private_dataPrivate data for the async callback function.
Returns:
Zero if successful, otherwise a negative error code.

This function associates the callback function with the given file, and saves this association in a snd_async_handler_t object.

Whenever the SIGIO signal is raised for the file fd, the callback function will be called with its parameter pointing to the async handler object returned by this function.

The ALSA sigaction handler for the SIGIO signal automatically multiplexes the notifications to the registered async callbacks. However, the application is responsible for instructing the device driver to generate the SIGIO signal.

The SIGIO signal may have been replaced with another signal, see snd_async_handler_get_signo.

When the async handler isn't needed anymore, you must delete it with snd_async_del_handler.

See also:
snd_async_add_pcm_handler, snd_async_add_ctl_handler
int snd_async_del_handler ( snd_async_handler_t handler)

Deletes an async handler.

Parameters:
handlerHandle of the async handler to delete.
Returns:
Zero if successful, otherwise a negative error code.
void* snd_async_handler_get_callback_private ( snd_async_handler_t handler)

Returns the private data assigned to an async handler.

Parameters:
handlerHandle to an async handler.
Returns:
The private_data value registered with the async handler.
Examples:
/test/pcm.c, and /test/timer.c.
int snd_async_handler_get_fd ( snd_async_handler_t handler)

Returns the file descriptor assigned to an async handler.

Parameters:
handlerHandle to an async handler.
Returns:
The file descriptor if successful, otherwise a negative error code.
int snd_async_handler_get_signo ( snd_async_handler_t handler)

Returns the signal number assigned to an async handler.

Parameters:
handlerHandle to an async handler.
Returns:
The signal number if successful, otherwise a negative error code.

The signal number for async handlers usually is SIGIO, but wizards can redefine it to a realtime signal when compiling the ALSA library.

int snd_dlclose ( void *  handle)

Closes a dynamic library - ALSA wrapper for dlclose.

Parameters:
handleLibrary handle, similar to dlclose.
Returns:
Zero if successful, otherwise an error code.

This function can emulate dynamic linking for the static build of the alsa-lib library.

void* snd_dlopen ( const char *  name,
int  mode 
)

Opens a dynamic library - ALSA wrapper for dlopen.

Parameters:
namename of the library, similar to dlopen.
modemode flags, similar to dlopen.
Returns:
Library handle if successful, otherwise NULL.

This function can emulate dynamic linking for the static build of the alsa-lib library. In that case, name is set to NULL.

void* snd_dlsym ( void *  handle,
const char *  name,
const char *  version 
)

Resolves a symbol from a dynamic library - ALSA wrapper for dlsym.

Parameters:
handleLibrary handle, similar to dlsym.
nameSymbol name.
versionVersion of the symbol.

This function can emulate dynamic linking for the static build of the alsa-lib library.

This special version of the dlsym function checks also the version of the symbol. A versioned symbol should be defined using the SND_DLSYM_BUILD_VERSION macro.

struct snd_shm_area* snd_shm_area_create ( int  shmid,
void *  ptr 
)
read

Create a shm area record.

Parameters:
shmidIPC SHM ID
ptrthe shared area pointer
Returns:
The allocated shm area record, NULL if fail

Allocates a shared area record with the given SHM ID and pointer. The record has a reference counter, which is initialized to 1 by this function.

int snd_shm_area_destroy ( struct snd_shm_area *  area)

Release the shared area record.

Parameters:
areathe shared are record
Returns:
0 if successful, or a negative error code

Decreases the reference counter of the given shared area record, and releases the resources automaticall if it reaches to 0.

struct snd_shm_area* snd_shm_area_share ( struct snd_shm_area *  area)
read

Increase the reference counter of shm area record.

Parameters:
areashm area record
Returns:
the shm area record (identical with the argument)

Increases the reference counter of the given shared area record.

int snd_user_file ( const char *  file,
char **  result 
)

Get the full file name.

Parameters:
fileThe file name string to parse
resultThe pointer to store the resultant file name
Returns:
0 if successful, or a negative error code

Parses the given file name with POSIX-Shell-like expansion and stores the first matchine one. The returned string is strdup'ed.