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

# Global defines and functions

## Defines
#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)
struct snd_shm_area * | snd_shm_area_share (struct snd_shm_area *area)
int | snd_shm_area_destroy (struct snd_shm_area *area)
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.

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

typedef struct timespec snd_htimestamp_t

Hi-res timestamp

typedef struct timeval snd_timestamp_t

Timestamp

Examples:
  /test/latency.c.

## 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:

  | 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

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.

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.

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.

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.

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.

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

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

Parameters:

  | name | name of the library, similar to `dlopen`.
  | mode | mode 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:

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

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.

All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines