ALSA project - the C library reference

Typedefs | Enumerations | Functions
Output Interface

## Typedefs
typedef struct _snd_output | snd_output_t
| Internal structure for an output object. More...

## Enumerations
enum | snd_output_type_t { SND_OUTPUT_STDIO , SND_OUTPUT_BUFFER }

## Functions
int | snd_output_stdio_open (snd_output_t **outputp, const char *file, const char *mode)
| Creates a new output object writing to a file. More...
int | snd_output_stdio_attach (snd_output_t **outputp, FILE *fp, int _close)
| Creates a new output object using an existing stdio `FILE` pointer. More...
int | snd_output_buffer_open (snd_output_t **outputp)
| Creates a new output object with an auto-extending memory buffer. More...
size_t | snd_output_buffer_string (snd_output_t *output, char **buf)
| Returns the address of the buffer of a SND_OUTPUT_BUFFER output handle. More...
size_t | snd_output_buffer_steal (snd_output_t *output, char **buf)
| Returns the address of the buffer of a SND_OUTPUT_BUFFER output handle. More...
int | snd_output_close (snd_output_t *output)
| Closes an output handle. More...
int | snd_output_printf (snd_output_t *output, const char *format,...)
| Writes formatted output (like `fprintf(3)`) to an output handle. More...
int | snd_output_vprintf (snd_output_t *output, const char *format, va_list args)
| Writes formatted output (like `fprintf(3)`) to an output handle. More...
int | snd_output_puts (snd_output_t *output, const char *str)
| Writes a string to an output handle (like `fputs(3)`). More...
int | snd_output_putc (snd_output_t *output, int c)
| Writes a character to an output handle (like `putc(3)`). More...
int | snd_output_flush (snd_output_t *output)
| Flushes an output handle (like fflush(3)). More...

## Detailed Description

The output functions present an interface similar to the stdio functions on top of different underlying output destinations.

Many PCM debugging functions (`snd_pcm_xxx_dump_xxx`) use such an output handle to be able to write not only to the screen but also to other destinations, e.g. to files or to memory buffers.

## Typedef Documentation

## ◆ snd_output_t

typedef struct _snd_output snd_output_t

Internal structure for an output object.

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

## Enumeration Type Documentation

## ◆ snd_output_type_t

enum snd_output_type_t

Output type.

Enumerator
SND_OUTPUT_STDIO | Output to a stdio stream.
SND_OUTPUT_BUFFER | Output to a memory buffer.

## Function Documentation

## ◆ snd_output_buffer_open()

int snd_output_buffer_open | ( | snd_output_t ** | outputp | ) |

Creates a new output object with an auto-extending memory buffer.

Parameters

  outputp | The function puts the pointer to the new output object at the address specified by `outputp`.

Returns
  Zero if successful, otherwise a negative error code.

## ◆ snd_output_buffer_steal()

size_t snd_output_buffer_steal | ( | snd_output_t * | output,
|  | char ** | buf
| ) |  |

Returns the address of the buffer of a SND_OUTPUT_BUFFER output handle.

Parameters

  output | The output handle.
  buf | The functions puts the current address of the buffer at the address specified by `buf`.

Returns
  The current size of valid data in the buffer.

The internal buffer is empty after this call. The caller has the responsibility to clean the buffer using the free() call.

## ◆ snd_output_buffer_string()

size_t snd_output_buffer_string | ( | snd_output_t * | output,
|  | char ** | buf
| ) |  |

Returns the address of the buffer of a SND_OUTPUT_BUFFER output handle.

Parameters

  output | The output handle.
  buf | The functions puts the current address of the buffer at the address specified by `buf`.

Returns
  The current size of valid data in the buffer.

The address of the buffer may become invalid when output functions or snd_output_close are called.

## ◆ snd_output_close()

int snd_output_close | ( | snd_output_t * | output | ) |

Closes an output handle.

Parameters

  output | The output handle to be closed.

Returns
  Zero if successful, otherwise a negative error code.

## ◆ snd_output_flush()

int snd_output_flush | ( | snd_output_t * | output | ) |

Flushes an output handle (like fflush(3)).

Parameters

  output | The output handle.

Returns
  Zero if successful, otherwise `EOF`.

If the underlying destination is a stdio stream, this function calls `fflush`. If the underlying destination is a memory buffer, the write position is reset to the beginning of the buffer. `=`:-o

## ◆ snd_output_printf()

int snd_output_printf | ( | snd_output_t * | output,
|  | const char * | format,
|  |  | ...
| ) |  |

Writes formatted output (like `fprintf(3)`) to an output handle.

Parameters

  output | The output handle.
  format | Format string in `fprintf` format.
  ... | Other `fprintf` arguments.

Returns
  The number of characters written, or a negative error code.

## ◆ snd_output_putc()

int snd_output_putc | ( | snd_output_t * | output,
|  | int | c
| ) |  |

Writes a character to an output handle (like `putc(3)`).

Parameters

  output | The output handle.
  c | The character.

Returns
  Zero if successful, otherwise a negative error code or `EOF`.

## ◆ snd_output_puts()

int snd_output_puts | ( | snd_output_t * | output,
|  | const char * | str
| ) |  |

Writes a string to an output handle (like `fputs(3)`).

Parameters

  output | The output handle.
  str | Pointer to the string.

Returns
  Zero if successful, otherwise a negative error code or `EOF`.

## ◆ snd_output_stdio_attach()

int snd_output_stdio_attach | ( | snd_output_t ** | outputp,
|  | FILE * | fp,
|  | int | _close
| ) |  |

Creates a new output object using an existing stdio `FILE` pointer.

Parameters

  outputp | The function puts the pointer to the new output object at the address specified by `outputp`.
  fp | The `FILE` pointer to write to. Characters are written to the file starting at the current file position.
  _close | Close flag. Set this to 1 if snd_output_close should close `fp` by calling `fclose`.

Returns
  Zero if successful, otherwise a negative error code.

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

## ◆ snd_output_stdio_open()

int snd_output_stdio_open | ( | snd_output_t ** | outputp,
|  | const char * | file,
|  | const char * | mode
| ) |  |

Creates a new output object writing to a file.

Parameters

  outputp | The function puts the pointer to the new output object at the address specified by `outputp`.
  file | The name of the file to open.
  mode | The open mode, like `fopen(3)`.

Returns
  Zero if successful, otherwise a negative error code.

## ◆ snd_output_vprintf()

int snd_output_vprintf | ( | snd_output_t * | output,
|  | const char * | format,
|  | va_list | args
| ) |  |

Writes formatted output (like `fprintf(3)`) to an output handle.

Parameters

  output | The output handle.
  format | Format string in `fprintf` format.
  args | Other `fprintf` arguments.

Returns
  The number of characters written, or a negative error code.