mirrors/alsa-lib
1
0
Fork 0
mirror of https://github.com/alsa-project/alsa-lib.git synced 2025-11-02 09:01:48 -05:00
Code Issues Projects Releases Packages Wiki Activity Actions

Documentation update by Clement Ladish

Browse source
This commit is contained in:
Jaroslav Kysela 2002-07-23 19:51:16 +00:00
parent 2db6b18b39
commit 63d708a344
15 changed files with 965 additions and 714 deletions
Download patch file Download diff file Expand all files Collapse all files

64
src/async.c
View file

@ -63,17 +63,33 @@ static void snd_async_handler(int signo ATTRIBUTE_UNUSED, siginfo_t *siginfo, vo
}
/**
* \brief Add async handler
* \param handler Result - async handler
* \param fd - File descriptor
* \param callback - Async callback
* \param private_data - Private data for async callback
* \result zero if success, otherwise a negative error code
* \brief Registers an async handler.
* \param handler The function puts the pointer to the new async handler
* object at the address specified by \p handler.
* \param fd The file descriptor to be associated with the callback.
* \param callback The async callback function.
* \param private_data Private data for the async callback function.
* \result Zero if successful, otherwise a negative error code.
*
* The function create the async handler. The ALSA extension
* for the standard SIGIO signal contains the multiplexer
* for multiple asynchronous notifiers using one sigaction
* callback.
* This function associates the callback function with the given file,
* and saves this association in a \c snd_async_handler_t object.
*
* Whenever the \c SIGIO signal is raised for the file \p fd, the callback
* function will be called with its parameter pointing to the async handler
* object returned by this function.
*
* The ALSA \c sigaction handler for the \c SIGIO signal automatically
* multiplexes the notifications to the registered async callbacks.
* However, the application is responsible for instructing the device driver
* to generate the \c SIGIO signal.
*
* The \c SIGIO signal may have been replaced with another signal,
* see #snd_async_handler_get_signo.
*
* When the async handler isn't needed anymore, you must delete it with
* #snd_async_del_handler.
*
* \see snd_async_add_pcm_handler, snd_async_add_ctl_handler
*/
int snd_async_add_handler(snd_async_handler_t **handler, int fd,
snd_async_callback_t callback, void *private_data)
@ -108,9 +124,9 @@ int snd_async_add_handler(snd_async_handler_t **handler, int fd,
}
/**
* \brief Delete async handler
* \param handler Async handler to delete
* \result zero if success, otherwise a negative error code
* \brief Deletes an async handler.
* \param handler Handle of the async handler to delete.
* \result Zero if successful, otherwise a negative error code.
*/
int snd_async_del_handler(snd_async_handler_t *handler)
{
@ -150,9 +166,13 @@ int snd_async_del_handler(snd_async_handler_t *handler)
}
/**
* \brief Get signal number assigned to async handler
* \param handler Async handler
* \result signal number if success, otherwise a negative error code
* \brief Returns the signal number assigned to an async handler.
* \param handler Handle to an async handler.
* \result The signal number if successful, otherwise a negative error code.
*
* The signal number for async handlers usually is \c SIGIO,
* but wizards can redefine it to a realtime signal
* when compiling the ALSA library.
*/
int snd_async_handler_get_signo(snd_async_handler_t *handler)
{
@ -161,9 +181,9 @@ int snd_async_handler_get_signo(snd_async_handler_t *handler)
}
/**
* \brief Get file descriptor assigned to async handler
* \param handler Async handler
* \result file descriptor if success, otherwise a negative error code
* \brief Returns the file descriptor assigned to an async handler.
* \param handler Handle to an async handler.
* \result The file descriptor if successful, otherwise a negative error code.
*/
int snd_async_handler_get_fd(snd_async_handler_t *handler)
{
@ -172,9 +192,9 @@ int snd_async_handler_get_fd(snd_async_handler_t *handler)
}
/**
* \brief Get private data assigned to async handler
* \param handler Async handler
* \result private data if success, otherwise a negative error code
* \brief Returns the private data assigned to an async handler.
* \param handler Handle to an async handler.
* \result The \c private_data value registered with the async handler.
*/
void *snd_async_handler_get_callback_private(snd_async_handler_t *handler)
{

845
src/conf.c
View file

File diff suppressed because it is too large Load diff

219
src/confmisc.c
View file

@ -37,30 +37,30 @@
\section conffunc_ref Function reference
<UL>
<LI>The getenv function - snd_func_getenv() - allows to obtain
an environment value. The result is string.
<LI>The igetenv function - snd_func_igetenv() - allows to obtain
an environment value. The result is integer.
<LI>The getenv function - snd_func_getenv() - obtains
an environment value. The result is a string.
<LI>The igetenv function - snd_func_igetenv() - obtains
an environment value. The result is an integer.
<LI>The concat function - snd_func_concat() - merges all specified
strings. The result is string.
strings. The result is a string.
<LI>The datadir function - snd_func_datadir() - returns the
data directory. The result is string.
ALSA data directory. The result is a string.
<LI>The refer function - snd_func_refer() - copies the referred
configuration. The result is same as the referred node.
configuration. The result has the same type as the referred node.
<LI>The card_driver function - snd_func_card_driver() - returns
the driver identification. The result is string.
a driver identification. The result is a string.
<LI>The card_id function - snd_func_card_id() - returns
the card identification. The result is string.
a card identification. The result is a string.
<LI>The pcm_id function - snd_func_pcm_id() - returns
the pcm identification. The result is string.
<LI>The private_string - snd_func_private_string() - returns
string using private_data node.
<LI>The private_card_driver - snd_func_private_card_driver() -
returns the driver identification using private_data node.
The result is string.
<LI>The private_pcm_subdevice - snd_func_private_pcm_subdevice() -
returns the PCM subdevice number using the private_data node.
The result is string.
a pcm identification. The result is a string.
<LI>The private_string function - snd_func_private_string() - returns the
string from the private_data node.
<LI>The private_card_driver function - snd_func_private_card_driver() -
returns the driver identification from the private_data node.
The result is a string.
<LI>The private_pcm_subdevice function - snd_func_private_pcm_subdevice() -
returns the PCM subdevice number from the private_data node.
The result is a string.
</UL>
*/
@ -73,9 +73,9 @@
#include "local.h"
/**
* \brief Get the boolean value from given ASCII string
* \param ascii The ASCII string to be parsed
* \return a positive value when success otherwise a negative error number
* \brief Gets the boolean value from the given ASCII string.
* \param ascii The string to be parsed.
* \return 0 or 1 if successful, otherwise a negative error code.
*/
int snd_config_get_bool_ascii(const char *ascii)
{
@ -101,9 +101,9 @@ int snd_config_get_bool_ascii(const char *ascii)
}
/**
* \brief Get the boolean value
* \param conf The configuration node to be parsed
* \return a positive value when success otherwise a negative error number
* \brief Gets the boolean value from a configuration node.
* \param conf Handle to the configuration node to be parsed.
* \return 0 or 1 if successful, otherwise a negative error code.
*/
int snd_config_get_bool(const snd_config_t *conf)
{
@ -135,9 +135,9 @@ int snd_config_get_bool(const snd_config_t *conf)
}
/**
* \brief Get the control interface index from given ASCII string
* \param ascii The ASCII string to be parsed
* \return a positive value when success otherwise a negative error number
* \brief Gets the control interface index from the given ASCII string.
* \param ascii The string to be parsed.
* \return The control interface index if successful, otherwise a negative error code.
*/
int snd_config_get_ctl_iface_ascii(const char *ascii)
{
@ -158,9 +158,9 @@ int snd_config_get_ctl_iface_ascii(const char *ascii)
}
/**
* \brief Get the control interface index
* \param conf The configuration node to be parsed
* \return a positive value when success otherwise a negative error number
* \brief Gets the control interface index from a configuration node.
* \param conf Handle to the configuration node to be parsed.
* \return The control interface index if successful, otherwise a negative error code.
*/
int snd_config_get_ctl_iface(const snd_config_t *conf)
{
@ -196,12 +196,14 @@ int snd_config_get_ctl_iface(const snd_config_t *conf)
*/
/**
* \brief Get environment value
* \param dst The destination node (result type is string)
* \param root The root source node
* \param src The source node, with vars and default definition
* \param private_data The private_data node
* \return a positive value when success otherwise a negative error number
* \brief Returns an environment value.
* \param dst The function puts the handle to the result configuration node
* (with type string) at the address specified by \p dst.
* \param root Handle to the root source node.
* \param src Handle to the source node, with definitions for \c vars and
* \c default.
* \param private_data Handle to the \c private_data node.
* \return Zero if successful, otherwise a negative error code.
*
* Example:
\code
@ -297,17 +299,19 @@ SND_DLSYM_BUILD_VERSION(snd_func_getenv, SND_CONFIG_DLSYM_VERSION_EVALUATE);
#endif
/**
* \brief Get integer environment value
* \param dst The destination node (result type is integer)
* \param root The root source node
* \param src The source node, with vars and default definition
* \param private_data The private_data node
* \return a positive value when success otherwise a negative error number
* \brief Returns an integer environment value.
* \param dst The function puts the handle to the result configuration node
* (with type integer) at the address specified by \p dst.
* \param root Handle to the root source node.
* \param src Handle to the source node, with definitions for \c vars and
* \c default.
* \param private_data Handle to the \c private_data node.
* \return Zero if successful, otherwise a negative error code.
*
* Example:
\code
{
@func getenv
@func igetenv
vars [ MY_DEVICE DEVICE D ]
default 0
}
@ -348,19 +352,19 @@ SND_DLSYM_BUILD_VERSION(snd_func_igetenv, SND_CONFIG_DLSYM_VERSION_EVALUATE);
#endif
/**
* \brief Merge given strings
* \param dst The destination node (result type is string)
* \param root The root source node
* \param src The source node, with strings definition
* \param private_data The private_data node
* \return a positive value when success otherwise a negative error number
* \brief Merges the given strings.
* \param dst The function puts the handle to the result configuration node
* (with type string) at the address specified by \p dst.
* \param root Handle to the root source node.
* \param src Handle to the source node, with a definition for \c strings.
* \param private_data Handle to the \c private_data node.
* \return A non-negative value if successful, otherwise a negative error code.
*
* Example (result is string "a1b2c3" ]:
* Example (result is "a1b2c3"):
\code
{
@func concat
strings [ "a1" "b2" "c3" ]
default 0
}
\endcode
*/
@ -436,14 +440,15 @@ SND_DLSYM_BUILD_VERSION(snd_func_concat, SND_CONFIG_DLSYM_VERSION_EVALUATE);
#endif
/**
* \brief Get data directory
* \param dst The destination node (result type is string)
* \param root The root source node
* \param src The source node
* \param private_data The private_data node (unused)
* \return a positive value when success otherwise a negative error number
* \brief Returns the ALSA data directory.
* \param dst The function puts the handle to the result configuration node
* (with type string) at the address specified by \p dst.
* \param root Handle to the root source node.
* \param src Handle to the source node.
* \param private_data Handle to the \c private_data node. Not used.
* \return A non-negative value if successful, otherwise a negative error code.
*
* Example (result is "/usr/share/alsa" using default paths):
* Example (result is "/usr/share/alsa" using the default paths):
\code
{
@func datadir
@ -488,12 +493,14 @@ static int string_from_integer(char **dst, long v)
#endif
/**
* \brief Get string from private_data
* \param dst The destination node (result type is string)
* \param root The root source node
* \param src The source node
* \param private_data The private_data node (type string, id == "string")
* \return a positive value when success otherwise a negative error number
* \brief Returns the string from \c private_data.
* \param dst The function puts the handle to the result configuration node
* (with type string) at the address specified by \p dst.
* \param root Handle to the root source node.
* \param src Handle to the source node.
* \param private_data Handle to the \c private_data node (type string,
* id "string").
* \return A non-negative value if successful, otherwise a negative error code.
*
* Example:
\code
@ -564,12 +571,14 @@ int snd_determine_driver(int card, char **driver)
#endif
/**
* \brief Get driver identification using private_data
* \param dst The destination node (result type is string)
* \param root The root source node
* \param src The source node
* \param private_data The private_data node (type = integer, id = "card")
* \return a positive value when success otherwise a negative error number
* \brief Returns the driver identification from \c private_data.
* \param dst The function puts the handle to the result configuration node
* (with type string) at the address specified by \p dst.
* \param root Handle to the root source node.
* \param src Handle to the source node.
* \param private_data Handle to the \c private_data node (type integer,
* id "card").
* \return A non-negative value if successful, otherwise a negative error code.
*
* Example:
\code
@ -609,12 +618,13 @@ SND_DLSYM_BUILD_VERSION(snd_func_private_card_driver, SND_CONFIG_DLSYM_VERSION_E
#endif
/**
* \brief Get driver identification
* \param dst The destination node (result type is string)
* \param root The root source node
* \param src The source node
* \param private_data The private_data node
* \return a positive value when success otherwise a negative error number
* \brief Returns the driver identification for a card.
* \param dst The function puts the handle to the result configuration node
* (with type string) at the address specified by \p dst.
* \param root Handle to the root source node.
* \param src Handle to the source node, with a \c card definition.
* \param private_data Handle to the \c private_data node.
* \return A non-negative value if successful, otherwise a negative error code.
*
* Example:
\code
@ -666,12 +676,13 @@ SND_DLSYM_BUILD_VERSION(snd_func_card_driver, SND_CONFIG_DLSYM_VERSION_EVALUATE)
#endif
/**
* \brief Get card identification
* \param dst The destination node (result type is string)
* \param root The root source node
* \param src The source node
* \param private_data The private_data node
* \return a positive value when success otherwise a negative error number
* \brief Returns the identification of a card.
* \param dst The function puts the handle to the result configuration node
* (with type string) at the address specified by \p dst.
* \param root Handle to the root source node.
* \param src Handle to the source node, with a \c card definition.
* \param private_data Handle to the \c private_data node.
* \return A non-negative value if successful, otherwise a negative error code.
*
* Example:
\code
@ -737,12 +748,14 @@ SND_DLSYM_BUILD_VERSION(snd_func_card_id, SND_CONFIG_DLSYM_VERSION_EVALUATE);
#endif
/**
* \brief Get pcm identification
* \param dst The destination node (result type is string)
* \param root The root source node
* \param src The source node
* \param private_data The private_data node
* \return a positive value when success otherwise a negative error number
* \brief Returns the pcm identification of a device.
* \param dst The function puts the handle to the result configuration node
* (with type string) at the address specified by \p dst.
* \param root Handle to the root source node.
* \param src Handle to the source node, with definitions for \c card,
* \c device and (optionally) \c subdevice.
* \param private_data Handle to the \c private_data node.
* \return A non-negative value if successful, otherwise a negative error code.
*
* Example:
\code
@ -831,12 +844,14 @@ SND_DLSYM_BUILD_VERSION(snd_func_pcm_id, SND_CONFIG_DLSYM_VERSION_EVALUATE);
#endif
/**
* \brief Get pcm subdevice using private_data
* \param dst The destination node (result type is integer)
* \param root The root source node
* \param src The source node
* \param private_data The private_data node (type = pointer, id = "pcm_handle")
* \return a positive value when success otherwise a negative error number
* \brief Returns the PCM subdevice from \c private_data.
* \param dst The function puts the handle to the result configuration node
* (with type integer) at the address specified by \p dst.
* \param root Handle to the root source node.
* \param src Handle to the source node.
* \param private_data Handle to the \c private_data node (type pointer,
* id "pcm_handle").
* \return A non-negative value if successful, otherwise a negative error code.
*
* Example:
\code
@ -881,12 +896,16 @@ SND_DLSYM_BUILD_VERSION(snd_func_private_pcm_subdevice, SND_CONFIG_DLSYM_VERSION
#endif
/**
* \brief Copy the referred configuration node
* \param dst The destination node (result type is same as referred node)
* \param root The root source node (can be modified!!!)
* \param src The source node
* \param private_data The private_data node
* \return a positive value when success otherwise a negative error number
* \brief Copies the specified configuration node.
* \param dst The function puts the handle to the result configuration node
* (with the same type as the specified node) at the address
* specified by \p dst.
* \param root Handle to the root source node.
* \param src Handle to the source node, with definitions for \c name and
* (optionally) \c file.
* \param private_data Handle to the \c private_data node.
* \return A non-negative value if successful, otherwise a negative error code.
* \note The root source node can be modified!
*
* Example:
\code

50
src/dlmisc.c
View file

@ -37,13 +37,13 @@ struct snd_dlsym_link *snd_dlsym_start = NULL;
#endif
/**
* \brief Open the dynamic library, with ALSA extension
* \param name name, similar to dlopen
* \param mode mode, similar to dlopen
* \return pointer to handle
* \brief Opens a dynamic library - ALSA wrapper for \c dlopen.
* \param name name of the library, similar to \c dlopen.
* \param mode mode flags, similar to \c dlopen.
* \return Library handle if successful, otherwise \c NULL.
*
* The extension is a special code for the static build of
* the alsa-lib library.
* This function can emulate dynamic linking for the static build of
* the alsa-lib library. In that case, \p name is set to \c NULL.
*/
void *snd_dlopen(const char *name, int mode)
{
@ -55,11 +55,11 @@ void *snd_dlopen(const char *name, int mode)
}
/**
* \brief Close the dynamic library, with ALSA extension
* \param handle handle, similar to dlclose
* \return zero if success, otherwise an error code
* \brief Closes a dynamic library - ALSA wrapper for \c dlclose.
* \param handle Library handle, similar to \c dlclose.
* \return Zero if successful, otherwise an error code.
*
* The extension is a special code for the static build of
* This function can emulate dynamic linking for the static build of
* the alsa-lib library.
*/
int snd_dlclose(void *handle)
@ -72,11 +72,14 @@ int snd_dlclose(void *handle)
}
/**
* \brief Verify dynamically loaded symbol
* \param handle dlopen handle
* \param name name of symbol
* \param version version of symbol
* \return zero is success, otherwise a negative error code
* \brief Verifies a dynamically loaded symbol.
* \param handle Library handle, similar to \c dlsym.
* \param name Symbol name.
* \param version Version of the symbol.
* \return Zero is successful, otherwise a negative error code.
*
* This function checks that the symbol with the version appended to its name
* does exist in the library.
*/
static int snd_dlsym_verify(void *handle, const char *name, const char *version)
{
@ -99,14 +102,17 @@ static int snd_dlsym_verify(void *handle, const char *name, const char *version)
}
/**
* \brief Resolve the symbol, with ALSA extension
* \param handle handle, similar to dlsym
* \param name symbol name
* \param version symbol version
* \brief Resolves a symbol from a dynamic library - ALSA wrapper for \c dlsym.
* \param handle Library handle, similar to \c dlsym.
* \param name Symbol name.
* \param version Version of the symbol.
*
* This special version of dlsym function checks also
* the version of symbol. The version of a symbol should
* be defined using #SND_DLSYM_BUILD_VERSION macro.
* This function can emulate dynamic linking for the static build of
* the alsa-lib library.
*
* This special version of the \c dlsym function checks also the version
* of the symbol. A versioned symbol should be defined using the
* #SND_DLSYM_BUILD_VERSION macro.
*/
void *snd_dlsym(void *handle, const char *name, const char *version)
{

23
src/error.c
View file

@ -43,10 +43,10 @@ static const char *snd_error_codes[] =
};
/**
* \brief Get the error string.
* \param errnum The error code number.
*
* Returns the ASCII description of the given numeric error code.
* \brief Returns the message for an error code.
* \param errnum The error code number, which must be a system error code
* or an ALSA error code.
* \return The ASCII description of the given numeric error code.
*/
const char *snd_strerror(int errnum)
{
@ -65,11 +65,11 @@ const char *snd_strerror(int errnum)
* \param file The filename where the error was hit.
* \param line The line number.
* \param function The function name.
* \param err The error number.
* \param err The error code.
* \param fmt The message (including the format characters).
* \param ... Optional arguments.
*
* Prints the error message including location to stderr.
* Prints the error message including location to \c stderr.
*/
static void snd_lib_error_default(const char *file, int line, const char *function, int err, const char *fmt, ...)
{
@ -86,17 +86,18 @@ static void snd_lib_error_default(const char *file, int line, const char *functi
/**
* \ingroup Error
* Pointer to the error handler function.
* For internal use only.
*/
snd_lib_error_handler_t *snd_lib_error = snd_lib_error_default;
snd_lib_error_handler_t snd_lib_error = snd_lib_error_default;
/**
* \brief Set the error handler.
* \brief Sets the error handler.
* \param handler The pointer to the new error handler function.
*
* This function sets a new error handler or the default one (if the NULL
* parameter is given) which prints the error messages to stderr.
* This function sets a new error handler, or (if \c handler is \c NULL)
* the default one which prints the error messages to \c stderr.
*/
int snd_lib_error_set_handler(snd_lib_error_handler_t *handler)
int snd_lib_error_set_handler(snd_lib_error_handler_t handler)
{
snd_lib_error = handler == NULL ? snd_lib_error_default : handler;
return 0;

83
src/input.c
View file

@ -51,9 +51,9 @@ struct _snd_input {
#endif
/**
* \brief close input handle
* \param input Input handle
* \return 0 on success otherwise a negative error code
* \brief Closes an input handle.
* \param input The input handle to be closed.
* \return Zero if successful, otherwise a negative error code.
*/
int snd_input_close(snd_input_t *input)
{
@ -63,11 +63,13 @@ int snd_input_close(snd_input_t *input)
}
/**
* \brief fscanf(3) like on an input handle
* \param input Input handle
* \param format fscanf format
* \param ... other fscanf arguments
* \return number of input items assigned otherwise a negative error code
* \brief Reads formatted input (like \c fscanf(3)) from an input handle.
* \param input The input handle.
* \param format Format string in \c fscanf format.
* \param ... Other \c fscanf arguments.
* \return The number of input items assigned, or \c EOF.
*
* \bug Reading from a memory buffer doesn't work.
*/
int snd_input_scanf(snd_input_t *input, const char *format, ...)
{
@ -80,11 +82,14 @@ int snd_input_scanf(snd_input_t *input, const char *format, ...)
}
/**
* \brief fgets(3) like on an input handle
* \param input Input handle
* \param str Destination buffer pointer
* \param size Buffer size
* \return Pointer to buffer or NULL on error
* \brief Reads a line from an input handle (like \c fgets(3)).
* \param input The input handle.
* \param str Address of the destination buffer.
* \param size The size of the destination buffer.
* \return Pointer to the buffer if successful, otherwise \c NULL.
*
* Like \c fgets, the returned string is zero-terminated, and contains
* the new-line character \c '\n' if the line fits into the buffer.
*/
char *snd_input_gets(snd_input_t *input, char *str, size_t size)
{
@ -92,9 +97,9 @@ char *snd_input_gets(snd_input_t *input, char *str, size_t size)
}
/**
* \brief fgetc(3) like on an input handle
* \param input Input handle
* \return character read or EOF on end of file or error
* \brief Reads a character from an input handle (like \c fgetc(3)).
* \param input The input handle.
* \return The character read, or \c EOF on end of file or error.
*/
int snd_input_getc(snd_input_t *input)
{
@ -102,10 +107,10 @@ int snd_input_getc(snd_input_t *input)
}
/**
* \brief ungetc(3) like on an input handle
* \param input Input handle
* \param c Char to push back
* \return character pushed back or EOF on error
* \brief Puts the last character read back to an input handle (like \c ungetc(3)).
* \param input The input handle.
* \param c The character to push back.
* \return The character pushed back, or \c EOF on error.
*/
int snd_input_ungetc(snd_input_t *input, int c)
{
@ -162,11 +167,14 @@ static snd_input_ops_t snd_input_stdio_ops = {
#endif
/**
* \brief Create a new input using an existing stdio FILE pointer
* \param inputp Pointer to returned input handle
* \param fp FILE pointer
* \param close Close flag (1 if FILE is fclose'd when input handle is closed)
* \return 0 on success otherwise a negative error code
* \brief Creates a new input object using an existing stdio \c FILE pointer.
* \param inputp The function puts the pointer to the new input object
* at the address specified by \p inputp.
* \param fp The \c FILE pointer to read from.
* Reading begins at the current file position.
* \param close Close flag. Set this to 1 if #snd_input_close should close
* \p fp by calling \c fclose.
* \return Zero if successful, otherwise a negative error code.
*/
int snd_input_stdio_attach(snd_input_t **inputp, FILE *fp, int _close)
{
@ -191,11 +199,12 @@ int snd_input_stdio_attach(snd_input_t **inputp, FILE *fp, int _close)
}
/**
* \brief Open a new input from a file
* \param inputp Pointer to returned input handle
* \param file File name
* \param mode fopen(3) open mode
* \return 0 on success otherwise a negative error code
* \brief Creates a new input object reading from a file.
* \param inputp The functions puts the pointer to the new input object
* at the address specified by \p inputp.
* \param file The name of the file to read from.
* \param mode The open mode, like \c fopen(3).
* \return Zero if successful, otherwise a negative error code.
*/
int snd_input_stdio_open(snd_input_t **inputp, const char *file, const char *mode)
{
@ -284,11 +293,15 @@ static snd_input_ops_t snd_input_buffer_ops = {
#endif
/**
* \brief Open a new input from a memory buffer
* \param inputp Pointer to returned input handle
* \param buf Buffer pointer
* \param size Buffer size
* \return 0 on success otherwise a negative error code
* \brief Creates a new input object from a memory buffer.
* \param inputp The function puts the pointer to the new input object
* at the address specified by \p inputp.
* \param buf Address of the input buffer.
* \param size Size of the input buffer.
* \return 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_buffer_open(snd_input_t **inputp, const char *buf, ssize_t size)
{

85
src/output.c
View file

@ -50,9 +50,9 @@ struct _snd_output {
#endif
/**
* \brief close output handle
* \param output Output handle
* \return 0 on success otherwise a negative error code
* \brief Closes an output handle.
* \param output The output handle to be closed.
* \return Zero if successful, otherwise a negative error code.
*/
int snd_output_close(snd_output_t *output)
{
@ -62,11 +62,11 @@ int snd_output_close(snd_output_t *output)
}
/**
* \brief fprintf(3) like on an output handle
* \param output Output handle
* \param format fprintf format
* \param ... other fprintf arguments
* \return number of characters written otherwise a negative error code
* \brief Writes formatted output (like \c fprintf(3)) to an output handle.
* \param output The output handle.
* \param format Format string in \c fprintf format.
* \param ... Other \c fprintf arguments.
* \return The number of characters written, or a negative error code.
*/
int snd_output_printf(snd_output_t *output, const char *format, ...)
{
@ -79,10 +79,10 @@ int snd_output_printf(snd_output_t *output, const char *format, ...)
}
/**
* \brief fputs(3) like on an output handle
* \param output Output handle
* \param str Buffer pointer
* \return 0 on success otherwise a negative error code
* \brief Writes a string to an output handle (like \c fputs(3)).
* \param output The output handle.
* \param str Pointer to the string.
* \return Zero if successful, otherwise a negative error code or \c EOF.
*/
int snd_output_puts(snd_output_t *output, const char *str)
{
@ -90,10 +90,10 @@ int snd_output_puts(snd_output_t *output, const char *str)
}
/**
* \brief fputs(3) like on an output handle
* \param output Output handle
* \param str Source buffer pointer
* \return 0 on success otherwise a negative error code
* \brief Writes a character to an output handle (like \c putc(3)).
* \param output The output handle.
* \param c The character.
* \return Zero if successful, otherwise a negative error code or \c EOF.
*/
int snd_output_putc(snd_output_t *output, int c)
{
@ -101,9 +101,13 @@ int snd_output_putc(snd_output_t *output, int c)
}
/**
* \brief fflush(3) like on an output handle
* \param output Output handle
* \return 0 on success otherwise a negative error code
* \brief Flushes an output handle (like fflush(3)).
* \param output The output handle.
* \return Zero if successful, otherwise \c EOF.
*
* If the underlying destination is a stdio stream, this function calls
* \c fflush. If the underlying destination is a memory buffer, the write
* position is reset to the beginning of the buffer. \c =:-o
*/
int snd_output_flush(snd_output_t *output)
{
@ -160,11 +164,14 @@ static snd_output_ops_t snd_output_stdio_ops = {
#endif
/**
* \brief Create a new output using an existing stdio FILE pointer
* \param outputp Pointer to returned output handle
* \param fp FILE pointer
* \param close Close flag (1 if FILE is fclose'd when output handle is closed)
* \return 0 on success otherwise a negative error code
* \brief Creates a new output object using an existing stdio \c FILE pointer.
* \param outputp The function puts the pointer to the new output object
* at the address specified by \p outputp.
* \param fp The \c FILE pointer to write to. Characters are written
* to the file starting at the current file position.
* \param close Close flag. Set this to 1 if #snd_output_close should close
* \p fp by calling \c fclose.
* \return Zero if successful, otherwise a negative error code.
*/
int snd_output_stdio_attach(snd_output_t **outputp, FILE *fp, int _close)
{
@ -189,11 +196,12 @@ int snd_output_stdio_attach(snd_output_t **outputp, FILE *fp, int _close)
}
/**
* \brief Open a new output to a file
* \param outputp Pointer to returned output handle
* \param file File name
* \param mode fopen(3) open mode
* \return 0 on success otherwise a negative error code
* \brief Creates a new output object writing to a file.
* \param outputp The function puts the pointer to the new output object
* at the address specified by \p outputp.
* \param file The name of the file to open.
* \param mode The open mode, like \c fopen(3).
* \return Zero if successful, otherwise a negative error code.
*/
int snd_output_stdio_open(snd_output_t **outputp, const char *file, const char *mode)
{
@ -307,10 +315,14 @@ static snd_output_ops_t snd_output_buffer_ops = {
#endif
/**
* \brief Return buffer info for a #SND_OUTPUT_TYPE_BUFFER output handle
* \param output Output handle
* \param buf Pointer to returned buffer
* \return size of data in buffer
* \brief Returns the address of the buffer of a #SND_OUTPUT_TYPE_BUFFER output handle.
* \param output The output handle.
* \param buf The functions puts the current address of the buffer at the
* address specified by \p buf.
* \return 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.
*/
size_t snd_output_buffer_string(snd_output_t *output, char **buf)
{
@ -320,9 +332,10 @@ size_t snd_output_buffer_string(snd_output_t *output, char **buf)
}
/**
* \brief Open a new output to an auto extended memory buffer
* \param outputp Pointer to returned output handle
* \return 0 on success otherwise a negative error code
* \brief Creates a new output object with an auto-extending memory buffer.
* \param outputp The function puts the pointer to the new output object
* at the address specified by \p outputp.
* \return Zero if successful, otherwise a negative error code.
*/
int snd_output_buffer_open(snd_output_t **outputp)
{