ALSA project - the C library reference: Input 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
Input Interface

## Typedefs
typedef struct _snd_input | snd_input_t
| Internal structure for an input object. More...

## Enumerations
enum | snd_input_type_t { SND_INPUT_STDIO, SND_INPUT_BUFFER }

## Functions
int | snd_input_stdio_open (snd_input_t **inputp, const char *file, const char *mode)
| Creates a new input object reading from a file. More...
int | snd_input_stdio_attach (snd_input_t **inputp, FILE *fp, int _close)
| Creates a new input object using an existing stdio `FILE` pointer. More...
int | snd_input_buffer_open (snd_input_t **inputp, const char *buffer, ssize_t size)
| Creates a new input object from a memory buffer. More...
int | snd_input_close (snd_input_t *input)
| Closes an input handle. More...
int | snd_input_scanf (snd_input_t *input, const char *format,...)
| Reads formatted input (like `fscanf(3)`) from an input handle. More...
char * | snd_input_gets (snd_input_t *input, char *str, size_t size)
| Reads a line from an input handle (like `fgets(3)`). More...
int | snd_input_getc (snd_input_t *input)
| Reads a character from an input handle (like `fgetc(3)`). More...
int | snd_input_ungetc (snd_input_t *input, int c)
| Puts the last character read back to an input handle (like `ungetc(3)`). More...

## Detailed Description

The input functions present an interface similar to the stdio functions on top of different underlying input sources.

The snd_config_load function uses such an input handle to be able to load configurations not only from standard files but also from other sources, e.g. from memory buffers.

## Typedef Documentation

typedef struct _snd_input snd_input_t

Internal structure for an input object.

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

## Enumeration Type Documentation

enum snd_input_type_t

Input type.

Enumerator
SND_INPUT_STDIO | Input from a stdio stream.
SND_INPUT_BUFFER | Input from a memory buffer.

## Function Documentation

int snd_input_buffer_open | ( | snd_input_t ** | inputp,
|  | const char * | buf,
|  | ssize_t | size
| ) |  |

Creates a new input object from a memory buffer.

Parameters

  inputp | The function puts the pointer to the new input object at the address specified by `inputp`.
  buf | Address of the input buffer.
  size | Size of the input buffer.

Returns
  Zero if successful, otherwise a negative error code.

This functions creates a copy of the input buffer, so the application is not required to preserve the buffer after this function has been called.

int snd_input_close | ( | snd_input_t * | input | ) |

Closes an input handle.

Parameters

  input | The input handle to be closed.

Returns
  Zero if successful, otherwise a negative error code.

int snd_input_getc | ( | snd_input_t * | input | ) |

Reads a character from an input handle (like `fgetc(3)`).

Parameters

  input | The input handle.

Returns
  The character read, or `EOF` on end of file or error.

char* snd_input_gets | ( | snd_input_t * | input,
|  | char * | str,
|  | size_t | size
| ) |  |

Reads a line from an input handle (like `fgets(3)`).

Parameters

  input | The input handle.
  str | Address of the destination buffer.
  size | The size of the destination buffer.

Returns
  Pointer to the buffer if successful, otherwise `NULL`.

Like `fgets`, the returned string is zero-terminated, and contains the new-line character `'\n'` if the line fits into the buffer.

int snd_input_scanf | ( | snd_input_t * | input,
|  | const char * | format,
|  |  | ...
| ) |  |

Reads formatted input (like `fscanf(3)`) from an input handle.

Parameters

  input | The input handle.
  format | Format string in `fscanf` format.
  ... | Other `fscanf` arguments.

Returns
  The number of input items assigned, or `EOF`.

Bug:
  Reading from a memory buffer doesn't work.

int snd_input_stdio_attach | ( | snd_input_t ** | inputp,
|  | FILE * | fp,
|  | int | _close
| ) |  |

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

Parameters

  inputp | The function puts the pointer to the new input object at the address specified by `inputp`.
  fp | The `FILE` pointer to read from. Reading begins at the current file position.
  _close | Close flag. Set this to 1 if snd_input_close should close `fp` by calling `fclose`.

Returns
  Zero if successful, otherwise a negative error code.

int snd_input_stdio_open | ( | snd_input_t ** | inputp,
|  | const char * | file,
|  | const char * | mode
| ) |  |

Creates a new input object reading from a file.

Parameters

  inputp | The functions puts the pointer to the new input object at the address specified by `inputp`.
  file | The name of the file to read from.
  mode | The open mode, like `fopen(3)`.

Returns
  Zero if successful, otherwise a negative error code.

int snd_input_ungetc | ( | snd_input_t * | input,
|  | int | c
| ) |  |

Puts the last character read back to an input handle (like `ungetc(3)`).

Parameters

  input | The input handle.
  c | The character to push back.

Returns
  The character pushed back, or `EOF` on error.