ALSA project - the C library reference: Output Interface

# Output Interface

## Typedefs
typedef struct _snd_output | snd_output_t
| Internal structure for an output object.
## 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.
int | snd_output_stdio_attach (snd_output_t **outputp, FILE *fp, int _close)
| Creates a new output object using an existing stdio `FILE` pointer.
int | snd_output_buffer_open (snd_output_t **outputp)
| Creates a new output object with an auto-extending memory buffer.
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.
int | snd_output_close (snd_output_t *output)
| Closes an output handle.
int | snd_output_printf (snd_output_t *output, const char *format,...)
| Writes formatted output (like `fprintf(3)`) to an output handle.
int | snd_output_vprintf (snd_output_t *output, const char *format, va_list args)
| Writes formatted output (like `fprintf(3)`) to an output handle.
int | snd_output_puts (snd_output_t *output, const char *str)
| Writes a string to an output handle (like `fputs(3)`).
int | snd_output_putc (snd_output_t *output, int c)
| Writes a character to an output handle (like `putc(3)`).
int | snd_output_flush (snd_output_t *output)
| Flushes an output handle (like fflush(3)).

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

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

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

All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines