ALSA project - the C library reference

Loading...
Searching...
No Matches
Macros | Typedefs | Functions | Variables
Error handling

## Macros
#define | SND_ERROR_BEGIN 500000
#define | SND_ERROR_INCOMPATIBLE_VERSION (SND_ERROR_BEGIN+0)
#define | SND_LOG_ERROR 1
#define | SND_LOG_WARN 2
#define | SND_LOG_INFO 3
#define | SND_LOG_DEBUG 4
#define | SND_LOG_TRACE 5
#define | SND_LOG_LAST SND_LOG_TRACE
#define | SND_ILOG_CORE 1
#define | SND_ILOG_CONFIG 2
#define | SND_ILOG_CONTROL 3
#define | SND_ILOG_HWDEP 4
#define | SND_ILOG_TIMER 5
#define | SND_ILOG_RAWMIDI 6
#define | SND_ILOG_PCM 7
#define | SND_ILOG_MIXER 8
#define | SND_ILOG_SEQUENCER 9
#define | SND_ILOG_UCM 10
#define | SND_ILOG_TOPOLOGY 11
#define | SND_ILOG_ASERVER 12
#define | SND_ILOG_LAST SND_ILOG_ASERVER
#define | snd_error(interface, args...)
#define | snd_errornum(interface, args...)
#define | snd_warn(interface, args...)
#define | snd_info(interface, args...)
#define | snd_debug(interface, args...)
#define | snd_trace(interface, args...)
#define | snd_check(interface, args...)
#define | snd_checknum(interface, args...)
#define | SNDERR(args...)
#define | SYSERR(args...)

## Typedefs
typedef void(* | snd_lib_log_handler_t) (int prio, int interface, const char *file, int line, const char *function, int errcode, const char *fmt, va_list arg)
| Log handler callback.
typedef void(* | snd_lib_error_handler_t) (const char *file, int line, const char *function, int errcode, const char *fmt,...)
| Error handler callback.
typedef void(* | snd_local_error_handler_t) (const char *file, int line, const char *func, int errcode, const char *fmt, va_list arg)

## Functions
const char * | snd_strerror (int errnum)
| Returns the message for an error code.
int | snd_lib_log_filter (int prio, int interface, const char *configstr)
| Check if a log message should be shown based on LIBASOUND_DEBUG.
void | snd_lib_log (int prio, int interface, const char *file, int line, const char *function, int errcode, const char *fmt,...)
| Root log handler function.
void | snd_lib_check (int interface, const char *file, int line, const char *function, int errcode, const char *fmt,...)
| The check point function.
snd_lib_log_handler_t | snd_lib_log_set_handler (snd_lib_log_handler_t handler)
| Sets the log handler.
snd_lib_log_handler_t | snd_lib_log_set_local (snd_lib_log_handler_t handler)
| Install local log handler.
const char * | snd_lib_log_priority (int prio)
| Function to convert log priority level to text.
const char * | snd_lib_log_interface (int interface)
| Function to convert interface code to text.
int | snd_lib_error_set_handler (snd_lib_error_handler_t handler)
| Sets the error handler.
snd_local_error_handler_t | snd_lib_error_set_local (snd_local_error_handler_t func)
| Install local error handler.

## Variables
snd_lib_log_handler_t | snd_lib_vlog
snd_lib_error_handler_t | snd_lib_error
snd_lib_log_handler_t | snd_lib_vlog = snd_lib_vlog_default
snd_lib_error_handler_t | snd_lib_error = snd_lib_error_default

## Detailed Description

Error handling macros and functions.

## Macro Definition Documentation

## ◆ snd_check

#define snd_check | ( |  | interface,
|  |  | args... )

Value:
snd_lib_check(SND_ILOG_##interface, __FILE__, __LINE__, __func__, 0, ##args)
snd_lib_check
void snd_lib_check(int interface, const char *file, int line, const char *function, int errcode, const char *fmt,...)
The check point function.
Definition error.c:379

Shows an check log message.

## ◆ snd_checknum

#define snd_checknum | ( |  | interface,
|  |  | args... )

Value:
snd_lib_check(SND_ILOG_##interface, __FILE__, __LINE__, __func__, errno, ##args)

Shows an check log message (related to `errno`).

## ◆ snd_debug

#define snd_debug | ( |  | interface,
|  |  | args... )

Value:
snd_lib_log(SND_LOG_DEBUG, SND_ILOG_##interface, __FILE__, __LINE__, __func__, 0, ##args)
SND_LOG_DEBUG
#define SND_LOG_DEBUG
Definition error.h:55
snd_lib_log
void snd_lib_log(int prio, int interface, const char *file, int line, const char *function, int errcode, const char *fmt,...)
Root log handler function.
Definition error.c:359

Shows an error log message.

## ◆ snd_error

#define snd_error | ( |  | interface,
|  |  | args... )

Value:
snd_lib_log(SND_LOG_ERROR, SND_ILOG_##interface, __FILE__, __LINE__, __func__, 0, ##args)
SND_LOG_ERROR
#define SND_LOG_ERROR
Definition error.h:52

Shows an error log message.

## ◆ SND_ERROR_BEGIN

#define SND_ERROR_BEGIN 500000

Lower boundary of sound error codes.

## ◆ SND_ERROR_INCOMPATIBLE_VERSION

#define SND_ERROR_INCOMPATIBLE_VERSION (SND_ERROR_BEGIN+0)

Kernel/library protocols are not compatible.

## ◆ snd_errornum

#define snd_errornum | ( |  | interface,
|  |  | args... )

Value:
snd_lib_log(SND_LOG_ERROR, SND_ILOG_##interface, __FILE__, __LINE__, __func__, errno, ##args)

Shows a system error log message (related to `errno`).

## ◆ SND_ILOG_ASERVER

#define SND_ILOG_ASERVER 12

aserver

## ◆ SND_ILOG_CONFIG

#define SND_ILOG_CONFIG 2

configuration parsing and operations

## ◆ SND_ILOG_CONTROL

#define SND_ILOG_CONTROL 3

control API

## ◆ SND_ILOG_CORE

#define SND_ILOG_CORE 1

core library code

## ◆ SND_ILOG_HWDEP

#define SND_ILOG_HWDEP 4

hwdep API

## ◆ SND_ILOG_LAST

#define SND_ILOG_LAST SND_ILOG_ASERVER

last known value for interface

## ◆ SND_ILOG_MIXER

#define SND_ILOG_MIXER 8

mixer API

## ◆ SND_ILOG_PCM

#define SND_ILOG_PCM 7

PCM API

## ◆ SND_ILOG_RAWMIDI

#define SND_ILOG_RAWMIDI 6

RawMidi API

## ◆ SND_ILOG_SEQUENCER

#define SND_ILOG_SEQUENCER 9

sequencer API

## ◆ SND_ILOG_TIMER

#define SND_ILOG_TIMER 5

timer API

## ◆ SND_ILOG_TOPOLOGY

#define SND_ILOG_TOPOLOGY 11

topology API

## ◆ SND_ILOG_UCM

#define SND_ILOG_UCM 10

UCM API

## ◆ snd_info

#define snd_info | ( |  | interface,
|  |  | args... )

Value:
snd_lib_log(SND_LOG_INFO, SND_ILOG_##interface, __FILE__, __LINE__, __func__, 0, ##args)
SND_LOG_INFO
#define SND_LOG_INFO
Definition error.h:54

Shows an error log message.

## ◆ SND_LOG_DEBUG

#define SND_LOG_DEBUG 4

debug priority level

## ◆ SND_LOG_ERROR

#define SND_LOG_ERROR 1

error priority level

## ◆ SND_LOG_INFO

#define SND_LOG_INFO 3

info priority level

## ◆ SND_LOG_LAST

#define SND_LOG_LAST SND_LOG_TRACE

last known value for priority level

## ◆ SND_LOG_TRACE

#define SND_LOG_TRACE 5

trace priority level

## ◆ SND_LOG_WARN

#define SND_LOG_WARN 2

warning priority level

## ◆ snd_trace

#define snd_trace | ( |  | interface,
|  |  | args... )

Value:
snd_lib_log(SND_LOG_TRACE, SND_ILOG_##interface, __FILE__, __LINE__, __func__, 0, ##args)
SND_LOG_TRACE
#define SND_LOG_TRACE
Definition error.h:56

Shows an trace log message.

## ◆ snd_warn

#define snd_warn | ( |  | interface,
|  |  | args... )

Value:
snd_lib_log(SND_LOG_WARN, SND_ILOG_##interface, __FILE__, __LINE__, __func__, 0, ##args)
SND_LOG_WARN
#define SND_LOG_WARN
Definition error.h:53

Shows an error log message.

## ◆ SNDERR

#define SNDERR | ( |  | args... | ) |

Value:
snd_lib_log(SND_LOG_ERROR, 0, __FILE__, __LINE__, __func__, 0, ##args)

Shows a sound error message.

## ◆ SYSERR

#define SYSERR | ( |  | args... | ) |

Value:
snd_lib_log(SND_LOG_ERROR, 0, __FILE__, __LINE__, __func__, errno, ##args)

Shows a system error message (related to `errno`).

## Typedef Documentation

## ◆ snd_lib_error_handler_t

typedef void(* snd_lib_error_handler_t) (const char *file, int line, const char *function, int errcode, const char *fmt,...)

Error handler callback.

Parameters

  file | Source file name.
  line | Line number.
  function | Function name.
  errcode | Value of `errno`, or 0 if not relevant.
  fmt | `printf(3)` format.
  ... | `printf(3)` arguments.

Deprecated
  Since 1.2.15

A function of this type is called by the ALSA library when an error occurs. This function usually shows the message on the screen, and/or logs it.

## ◆ snd_lib_log_handler_t

typedef void(* snd_lib_log_handler_t) (int prio, int interface, const char *file, int line, const char *function, int errcode, const char *fmt, va_list arg)

Log handler callback.

Parameters

  prio | Priority (SND_LOG_* defines).
  interface | Interface (SND_ILOG_* defines).
  file | Source file name.
  line | Line number.
  function | Function name.
  errcode | Value of `errno`, or 0 if not relevant.
  fmt | `printf(3)` format.
  ... | `printf(3)` arguments.

A function of this type is called by the ALSA library when an error occurs. This function usually shows the message on the screen, and/or logs it.

## ◆ snd_local_error_handler_t

typedef void(* snd_local_error_handler_t) (const char *file, int line, const char *func, int errcode, const char *fmt, va_list arg)

Local error handler function type

## Function Documentation

## ◆ snd_lib_check()

void snd_lib_check | ( | int | interface,
|  | const char * | file,
|  | int | line,
|  | const char * | function,
|  | int | errcode,
|  | const char * | fmt,
|  |  | ... )

The check point function.

Parameters

  interface | Interface (SND_ILOG_*).
  file | The filename where the error was hit.
  line | The line number.
  function | The function name.
  errcode | The error code.
  fmt | The message (including the format characters).
  ... | Optional arguments.

The error message is passed with error priority level to snd_lib_vlog handler.

## ◆ snd_lib_error_set_handler()

int snd_lib_error_set_handler | ( | snd_lib_error_handler_t | handler | ) |

Sets the error handler.

Parameters

  handler | The pointer to the new error handler function.

Deprecated
  Since 1.2.15

This function sets a new error handler, or (if `handler` is `NULL`) the default one which prints the error messages to `stderr`.

## ◆ snd_lib_error_set_local()

snd_local_error_handler_t snd_lib_error_set_local | ( | snd_local_error_handler_t | func | ) |

Install local error handler.

Parameters

  func | The local error handler function

Return values

  Previous | local error handler function

Deprecated
  Since 1.2.15

## ◆ snd_lib_log()

void snd_lib_log | ( | int | prio,
|  | int | interface,
|  | const char * | file,
|  | int | line,
|  | const char * | function,
|  | int | errcode,
|  | const char * | fmt,
|  |  | ... )

Root log handler function.

Parameters

  prio | Priority value (SND_LOG_*).
  interface | Interface (SND_ILOG_*).
  file | The filename where the error was hit.
  line | The line number.
  function | The function name.
  errcode | The error code.
  fmt | The message (including the format characters).
  ... | Optional arguments.

## ◆ snd_lib_log_filter()

int snd_lib_log_filter | ( | int | prio,
|  | int | interface,
|  | const char * | configstr )

Check if a log message should be shown based on LIBASOUND_DEBUG.

Parameters

  prio | Priority value (SND_LOG_*).
  interface | Interface (SND_ILOG_*).
  configstr | Configuration string (usually LIBASOUND_DEBUG environment variable)

Returns
  1 if the message should be shown, 0 otherwise.

## ◆ snd_lib_log_interface()

const char * snd_lib_log_interface | ( | int | interface | ) |

Function to convert interface code to text.

Parameters

  interface | Interface (SND_ILOG_*).

Returns
  The textual representation of the interface code, or NULL if invalid.

## ◆ snd_lib_log_priority()

const char * snd_lib_log_priority | ( | int | prio | ) |

Function to convert log priority level to text.

Parameters

  prio | Priority value (SND_LOG_*).

Returns
  The textual representation of the priority level, or NULL if invalid.

## ◆ snd_lib_log_set_handler()

snd_lib_log_handler_t snd_lib_log_set_handler | ( | snd_lib_log_handler_t | handler | ) |

Sets the log handler.

Parameters

  handler | The pointer to the new log handler function.

Return values

  Previous | log handler function

This function sets a new log handler, or (if `handler` is `NULL`) the default one which prints the error messages to `stderr`.

## ◆ snd_lib_log_set_local()

snd_lib_log_handler_t snd_lib_log_set_local | ( | snd_lib_log_handler_t | func | ) |

Install local log handler.

Parameters

  func | The local log handler function

Return values

  Previous | local log handler function

## ◆ snd_strerror()

const char * snd_strerror | ( | int | errnum | ) |

Returns the message for an error code.

Parameters

  errnum | The error code number, which must be a system error code or an ALSA error code.

Returns
  The ASCII description of the given numeric error code.

Examples
  /test/latency.c, /test/pcm.c, /test/pcm_min.c, /test/rawmidi.c, and /test/timer.c.

## Variable Documentation

## ◆ snd_lib_error [1/2]

snd_lib_error_handler_t snd_lib_error
| extern

Deprecated
  Since 1.2.15 Pointer to the error handler function. For internal use only.

## ◆ snd_lib_error [2/2]

snd_lib_error_handler_t snd_lib_error = snd_lib_error_default

Deprecated
  Since 1.2.15 Pointer to the error handler function. For internal use only.

## ◆ snd_lib_vlog [1/2]

snd_lib_log_handler_t snd_lib_vlog
| extern

Pointer to the error handler function. For internal use only.

## ◆ snd_lib_vlog [2/2]

snd_lib_log_handler_t snd_lib_vlog = snd_lib_vlog_default

Pointer to the error handler function. For internal use only.