ALSA project - the C library reference: Output Interface

ALSA project - the C library reference

- Main Page
- Related Pages
- Modules
- Data Structures
- Files
- Examples

All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
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...
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

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

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

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.

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.

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.

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

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.

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

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

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.

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.

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.