Output Interface

Overview

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

// typedefs

typedef struct _snd_output snd_output_t;

// enums

enum snd_output_type_t;

// global functions

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

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

int
snd_output_buffer_open(snd_output_t** outputp);

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

int
snd_output_close(snd_output_t* output);

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

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

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

int
snd_output_putc(
    snd_output_t* output,
    int c
);

int
snd_output_flush(snd_output_t* output);

Detailed Documentation

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.

Typedefs

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.

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

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

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.

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

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.

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

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_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_flush(snd_output_t* output)

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

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

Parameters:

output

The output handle.

Returns:

Zero if successful, otherwise EOF.