ALSA project - the C library reference: Global defines and functions

ALSA project - the C library reference

Loading...
Searching...
No Matches
Files | Macros | Typedefs | Functions
Global defines and functions

## Files
file | shmarea.c
| shared memory helpers

## Macros
#define | __STRING(x) #x
| Return 'x' argument as string.
#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 | 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.
int | snd_dlpath (char *path, size_t path_len, const char *name)
| Compose the dynamic path.
void * | snd_dlopen (const char *file, int mode, char *errbuf, size_t errbuflen)
| 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

## ◆ snd_async_callback_t

typedef void(* snd_async_callback_t) (snd_async_handler_t *handler)

Async notification callback.

See the snd_async_add_handler function for details.

## ◆ snd_async_handler_t

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.

## ◆ snd_htimestamp_t

typedef struct timespec snd_htimestamp_t

Hi-res timestamp

## ◆ snd_timestamp_t

typedef struct timeval snd_timestamp_t

Timestamp

## Function Documentation

## ◆ snd_asoundlib_version()

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.

## ◆ snd_async_add_handler()

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

  handler | The function puts the pointer to the new async handler object at the address specified by `handler`.
  fd | The file descriptor to be associated with the callback.
  callback | The async callback function.
  private_data | Private 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

## ◆ snd_async_del_handler()

int snd_async_del_handler | ( | snd_async_handler_t * | handler | ) |

Deletes an async handler.

Parameters

  handler | Handle of the async handler to delete.

Returns
  Zero if successful, otherwise a negative error code.

## ◆ snd_async_handler_get_callback_private()

void * snd_async_handler_get_callback_private | ( | snd_async_handler_t * | handler | ) |

Returns the private data assigned to an async handler.

Parameters

  handler | Handle to an async handler.

Returns
  The `private_data` value registered with the async handler.

Examples
  /test/pcm.c, and /test/timer.c.

## ◆ snd_async_handler_get_fd()

int snd_async_handler_get_fd | ( | snd_async_handler_t * | handler | ) |

Returns the file descriptor assigned to an async handler.

Parameters

  handler | Handle to an async handler.

Returns
  The file descriptor if successful, otherwise a negative error code.

## ◆ snd_async_handler_get_signo()

int snd_async_handler_get_signo | ( | snd_async_handler_t * | handler | ) |

Returns the signal number assigned to an async handler.

Parameters

  handler | Handle 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.

## ◆ snd_dlclose()

int snd_dlclose | ( | void * | handle | ) |

Closes a dynamic library - ALSA wrapper for `dlclose`.

Parameters

  handle | Library 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.

## ◆ snd_dlopen()

void * snd_dlopen | ( | const char * | name,
|  | int | mode,
|  | char * | errbuf,
|  | size_t | errbuflen )

Opens a dynamic library - ALSA wrapper for `dlopen`.

Parameters

  name | name of the library, similar to `dlopen`.
  mode | mode flags, similar to `dlopen`.
  errbuf | a string buffer for the error message `dlerror`.
  errbuflen | a length of the string buffer for the error message.

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`.

## ◆ snd_dlpath()

int snd_dlpath | ( | char * | path,
|  | size_t | path_len,
|  | const char * | name )

Compose the dynamic path.

Parameters

  path | Returned path (string)
  path_len | Returned path max size (with trailing zero)
  name | Plugin name (relative)

Returns
  Zero on success, otherwise a negative error code

## ◆ snd_dlsym()

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

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

Parameters

  handle | Library handle, similar to `dlsym`.
  name | Symbol name.
  version | Version 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.

## ◆ snd_shm_area_create()

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

Create a shm area record.

Parameters

  shmid | IPC SHM ID
  ptr | the 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.

## ◆ snd_shm_area_destroy()

int snd_shm_area_destroy | ( | struct snd_shm_area * | area | ) |

Release the shared area record.

Parameters

  area | the 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.

## ◆ snd_shm_area_share()

struct snd_shm_area * snd_shm_area_share | ( | struct snd_shm_area * | area | ) |

Increase the reference counter of shm area record.

Parameters

  area | shm area record

Returns
  the shm area record (identical with the argument)

Increases the reference counter of the given shared area record.

## ◆ snd_user_file()

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

Get the full file name.

Parameters

  file | The file name string to parse
  result | The 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.