ALSA project - the C library reference
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Data Structures | Macros | Typedefs | Enumerations | Functions | Variables
Configuration Interface

Data Structures

struct  snd_devname_t

Macros

#define SND_CONFIG_DLSYM_VERSION_EVALUATE   _dlsym_config_evaluate_001
 dlsym version for the config evaluate callback.
#define SND_CONFIG_DLSYM_VERSION_HOOK   _dlsym_config_hook_001
 dlsym version for the config hook callback.
#define snd_config_for_each(pos, next, node)   for (pos = snd_config_iterator_first(node), next = snd_config_iterator_next(pos); pos != snd_config_iterator_end(node); pos = next, next = snd_config_iterator_next(pos))
 Helper macro to iterate over the children of a compound node.

Typedefs

typedef struct _snd_config snd_config_t
 Internal structure for a configuration node object.
typedef struct
_snd_config_iterator * 
snd_config_iterator_t
 Type for a configuration compound iterator.
typedef struct _snd_config_update snd_config_update_t
 Internal structure for a configuration private update object.

Enumerations

enum  snd_config_type_t {
  SND_CONFIG_TYPE_INTEGER, SND_CONFIG_TYPE_INTEGER64, SND_CONFIG_TYPE_REAL, SND_CONFIG_TYPE_STRING,
  SND_CONFIG_TYPE_POINTER, SND_CONFIG_TYPE_COMPOUND = 1024
}
 Configuration node type. More...

Functions

int snd_config_top (snd_config_t **config)
 Creates a top level configuration node.
int snd_config_load (snd_config_t *config, snd_input_t *in)
 Loads a configuration tree.
int snd_config_load_override (snd_config_t *config, snd_input_t *in)
 Loads a configuration tree and overrides existing configuration nodes.
int snd_config_save (snd_config_t *config, snd_output_t *out)
 Dumps the contents of a configuration node or tree.
int snd_config_update (void)
 Updates snd_config by rereading the global configuration files (if needed).
int snd_config_update_r (snd_config_t **top, snd_config_update_t **update, const char *path)
 Updates a configuration tree by rereading the configuration files (if needed).
int snd_config_update_free (snd_config_update_t *update)
 Frees a private update structure.
int snd_config_update_free_global (void)
 Frees the global configuration tree in snd_config.
int snd_config_search (snd_config_t *config, const char *key, snd_config_t **result)
 Searches for a node in a configuration tree.
int snd_config_searchv (snd_config_t *config, snd_config_t **result,...)
 Searches for a node in a configuration tree.
int snd_config_search_definition (snd_config_t *config, const char *base, const char *key, snd_config_t **result)
 Searches for a definition in a configuration tree, using aliases and expanding hooks and arguments.
int snd_config_expand (snd_config_t *config, snd_config_t *root, const char *args, snd_config_t *private_data, snd_config_t **result)
 Expands a configuration node, applying arguments and functions.
int snd_config_evaluate (snd_config_t *config, snd_config_t *root, snd_config_t *private_data, snd_config_t **result)
 Evaluates a configuration node at runtime.
int snd_config_add (snd_config_t *config, snd_config_t *leaf)
 Adds a child to a compound configuration node.
int snd_config_delete (snd_config_t *config)
 Frees a configuration node.
int snd_config_delete_compound_members (const snd_config_t *config)
 Deletes the children of a node.
int snd_config_copy (snd_config_t **dst, snd_config_t *src)
 Creates a copy of a configuration node.
int snd_config_make (snd_config_t **config, const char *key, snd_config_type_t type)
 Creates a configuration node.
int snd_config_make_integer (snd_config_t **config, const char *key)
 Creates an integer configuration node.
int snd_config_make_integer64 (snd_config_t **config, const char *key)
 Creates a 64-bit-integer configuration node.
int snd_config_make_real (snd_config_t **config, const char *key)
 Creates a real number configuration node.
int snd_config_make_string (snd_config_t **config, const char *key)
 Creates a string configuration node.
int snd_config_make_pointer (snd_config_t **config, const char *key)
 Creates a pointer configuration node.
int snd_config_make_compound (snd_config_t **config, const char *key, int join)
 Creates an empty compound configuration node.
int snd_config_imake_integer (snd_config_t **config, const char *key, const long value)
 Creates an integer configuration node with the given initial value.
int snd_config_imake_integer64 (snd_config_t **config, const char *key, const long long value)
 Creates a 64-bit-integer configuration node with the given initial value.
int snd_config_imake_real (snd_config_t **config, const char *key, const double value)
 Creates a real number configuration node with the given initial value.
int snd_config_imake_string (snd_config_t **config, const char *key, const char *ascii)
 Creates a string configuration node with the given initial value.
int snd_config_imake_pointer (snd_config_t **config, const char *key, const void *ptr)
 Creates a pointer configuration node with the given initial value.
snd_config_type_t snd_config_get_type (const snd_config_t *config)
 Returns the type of a configuration node.
int snd_config_set_id (snd_config_t *config, const char *id)
 Sets the id of a configuration node.
int snd_config_set_integer (snd_config_t *config, long value)
 Changes the value of an integer configuration node.
int snd_config_set_integer64 (snd_config_t *config, long long value)
 Changes the value of a 64-bit-integer configuration node.
int snd_config_set_real (snd_config_t *config, double value)
 Changes the value of a real-number configuration node.
int snd_config_set_string (snd_config_t *config, const char *value)
 Changes the value of a string configuration node.
int snd_config_set_ascii (snd_config_t *config, const char *ascii)
 Changes the value of a configuration node.
int snd_config_set_pointer (snd_config_t *config, const void *ptr)
 Changes the value of a pointer configuration node.
int snd_config_get_id (const snd_config_t *config, const char **value)
 Returns the id of a configuration node.
int snd_config_get_integer (const snd_config_t *config, long *value)
 Returns the value of an integer configuration node.
int snd_config_get_integer64 (const snd_config_t *config, long long *value)
 Returns the value of a 64-bit-integer configuration node.
int snd_config_get_real (const snd_config_t *config, double *value)
 Returns the value of a real-number configuration node.
int snd_config_get_ireal (const snd_config_t *config, double *value)
 Returns the value of a real or integer configuration node.
int snd_config_get_string (const snd_config_t *config, const char **value)
 Returns the value of a string configuration node.
int snd_config_get_ascii (const snd_config_t *config, char **value)
 Returns the value of a configuration node as a string.
int snd_config_get_pointer (const snd_config_t *config, const void **value)
 Returns the value of a pointer configuration node.
int snd_config_test_id (const snd_config_t *config, const char *id)
 Compares the id of a configuration node to a given string.
snd_config_iterator_t snd_config_iterator_first (const snd_config_t *node)
 Returns an iterator pointing to a node's first child.
snd_config_iterator_t snd_config_iterator_next (const snd_config_iterator_t iterator)
 Returns an iterator pointing to the next sibling.
snd_config_iterator_t snd_config_iterator_end (const snd_config_t *node)
 Returns an iterator that ends a node's children list.
snd_config_tsnd_config_iterator_entry (const snd_config_iterator_t iterator)
 Returns the configuration node handle pointed to by an iterator.
int snd_config_get_bool_ascii (const char *ascii)
 Gets the boolean value from the given ASCII string.
int snd_config_get_bool (const snd_config_t *conf)
 Gets the boolean value from a configuration node.
int snd_config_get_ctl_iface_ascii (const char *ascii)
 Gets the control interface index from the given ASCII string.
int snd_config_get_ctl_iface (const snd_config_t *conf)
 Gets the control interface index from a configuration node.
int snd_names_list (const char *iface, snd_devname_t **list)
 This function is unimplemented.
void snd_names_list_free (snd_devname_t *list)
 This function is unimplemented.

Variables

snd_config_tsnd_config
 Configuration top-level node (the global configuration).
snd_config_tsnd_config = NULL
 Configuration top-level node (the global configuration).

Detailed Description

The configuration functions and types allow you to read, enumerate, modify and write the contents of ALSA configuration files.


Macro Definition Documentation

#define snd_config_for_each (   pos,
  next,
  node 
)    for (pos = snd_config_iterator_first(node), next = snd_config_iterator_next(pos); pos != snd_config_iterator_end(node); pos = next, next = snd_config_iterator_next(pos))

Helper macro to iterate over the children of a compound node.

Parameters:
[in,out]posIterator variable for the current node.
[in,out]nextTemporary iterator variable for the next node.
[in]nodeHandle to the compound configuration node to iterate over.

Use this macro like a for statement, e.g.:

snd_config_for_each(pos, next, node) {
...
}

This macro allows deleting or removing the current node.


Typedef Documentation

typedef struct _snd_config_iterator* snd_config_iterator_t

Type for a configuration compound iterator.

The ALSA library uses this pointer type as a handle to a configuration compound iterator. Applications don't directly access the contents of the structure pointed to by this type.

typedef struct _snd_config snd_config_t

Internal structure for a configuration node object.

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

typedef struct _snd_config_update snd_config_update_t

Internal structure for a configuration private update object.

The ALSA library uses this structure to save private update information.


Enumeration Type Documentation

Configuration node type.

Enumerator:
SND_CONFIG_TYPE_INTEGER 

Integer number.

SND_CONFIG_TYPE_INTEGER64 

64-bit integer number.

SND_CONFIG_TYPE_REAL 

Real number.

SND_CONFIG_TYPE_STRING 

Character string.

SND_CONFIG_TYPE_POINTER 

Pointer (runtime only, cannot be saved).

SND_CONFIG_TYPE_COMPOUND 

Compound node.


Function Documentation

int snd_config_add ( snd_config_t parent,
snd_config_t child 
)

Adds a child to a compound configuration node.

Parameters:
parentHandle to a compound configuration node.
childHandle to the configuration node to be added.
Returns:
Zero if successful, otherwise a negative error code.

This function makes the node child a child of the node parent.

The parent node then owns the child node, i.e., the child node gets deleted together with its parent.

child must have an id.

Errors:
-EINVAL
child does not have an id.
-EINVAL
child already has a parent.
-EEXIST
parent already contains a child node with the same id as child.
Conforming to:
LSB 3.2
int snd_config_copy ( snd_config_t **  dst,
snd_config_t src 
)

Creates a copy of a configuration node.

Parameters:
[out]dstThe function puts the handle to the new configuration node at the address specified by dst.
[in]srcHandle to the source configuration node.
Returns:
A non-negative value if successful, otherwise a negative error code.

This function creates a deep copy, i.e., if src is a compound node, all children are copied recursively.

Errors:
-ENOMEM
Out of memory.
Conforming to:
LSB 3.2
int snd_config_delete ( snd_config_t config)

Frees a configuration node.

Parameters:
configHandle to the configuration node to be deleted.
Returns:
Zero if successful, otherwise a negative error code.

This function frees a configuration node and all its resources.

If the node is a child node, it is removed from the tree before being deleted.

If the node is a compound node, its descendants (the whole subtree) are deleted recursively.

Conforming to:
LSB 3.2
See also:
snd_config_remove
int snd_config_delete_compound_members ( const snd_config_t config)

Deletes the children of a node.

Parameters:
configHandle to the compound configuration node.
Returns:
Zero if successful, otherwise a negative error code.

This function removes and frees all children of a configuration node.

Any compound nodes among the children of config are deleted recursively.

After a successful call to this function, config is an empty compound node.

Errors:
-EINVAL
config is not a compound node.
int snd_config_evaluate ( snd_config_t config,
snd_config_t root,
snd_config_t private_data,
snd_config_t **  result 
)

Evaluates a configuration node at runtime.

Parameters:
[in,out]configHandle to the source configuration node.
[in]rootHandle to the root of the source configuration.
[in]private_dataHandle to the private data node for runtime evaluation.
resultMust be NULL.
Returns:
A non-negative value if successful, otherwise a negative error code.

This function evaluates any functions (@func) in config and replaces those nodes with the respective function results.

int snd_config_expand ( snd_config_t config,
snd_config_t root,
const char *  args,
snd_config_t private_data,
snd_config_t **  result 
)

Expands a configuration node, applying arguments and functions.

Parameters:
[in]configHandle to the configuration node.
[in]rootHandle to the root configuration node.
[in]argsArguments string, can be NULL.
[in]private_dataHandle to the private data node for functions.
[out]resultThe function puts the handle to the result configuration node at the address specified by result.
Returns:
A non-negative value if successful, otherwise a negative error code.

If config has arguments (defined by a child with id @args), this function replaces any string node beginning with $ with the respective argument value, or the default argument value, or nothing. Furthermore, any functions are evaluated (see snd_config_evaluate). The resulting copy of config is returned in result.

int snd_config_get_ascii ( const snd_config_t config,
char **  ascii 
)

Returns the value of a configuration node as a string.

Parameters:
[in]configHandle to the configuration node.
[out]asciiThe function puts the pointer to the returned string at the address specified by ascii.
Returns:
Zero if successful, otherwise a negative error code.

This function dynamically allocates the returned string. The application is responsible for deleting it with free() when it is no longer used.

For a string node with NULL value, the returned string is NULL.

Supported node types are SND_CONFIG_TYPE_INTEGER, SND_CONFIG_TYPE_INTEGER64, SND_CONFIG_TYPE_REAL, and SND_CONFIG_TYPE_STRING.

Errors:
-EINVAL
config is not a (64-bit) integer or real number or string node.
-ENOMEM
Out of memory.
Conforming to:
LSB 3.2
int snd_config_get_bool ( const snd_config_t conf)

Gets the boolean value from a configuration node.

Parameters:
confHandle to the configuration node to be parsed.
Returns:
0 or 1 if successful, otherwise a negative error code.
int snd_config_get_bool_ascii ( const char *  ascii)

Gets the boolean value from the given ASCII string.

Parameters:
asciiThe string to be parsed.
Returns:
0 or 1 if successful, otherwise a negative error code.
int snd_config_get_ctl_iface ( const snd_config_t conf)

Gets the control interface index from a configuration node.

Parameters:
confHandle to the configuration node to be parsed.
Returns:
The control interface index if successful, otherwise a negative error code.
int snd_config_get_ctl_iface_ascii ( const char *  ascii)

Gets the control interface index from the given ASCII string.

Parameters:
asciiThe string to be parsed.
Returns:
The control interface index if successful, otherwise a negative error code.
int snd_config_get_id ( const snd_config_t config,
const char **  id 
)

Returns the id of a configuration node.

Parameters:
[in]configHandle to the configuration node.
[out]idThe function puts the pointer to the id string at the address specified by id.
Returns:
Zero if successful, otherwise a negative error code.

The returned string is owned by the configuration node; the application must not modify or delete it, and the string becomes invalid when the node's id changes or when the node is freed.

If the node does not have an id, *id is set to NULL.

Conforming to:
LSB 3.2
int snd_config_get_integer ( const snd_config_t config,
long *  ptr 
)

Returns the value of an integer configuration node.

Parameters:
[in]configHandle to the configuration node.
[out]ptrThe node's value.
Returns:
Zero if successful, otherwise a negative error code.
Errors:
-EINVAL
config is not an integer node.
Conforming to:
LSB 3.2
int snd_config_get_integer64 ( const snd_config_t config,
long long *  ptr 
)

Returns the value of a 64-bit-integer configuration node.

Parameters:
[in]configHandle to the configuration node.
[out]ptrThe node's value.
Returns:
Zero if successful, otherwise a negative error code.
Errors:
-EINVAL
config is not a 64-bit-integer node.
Conforming to:
LSB 3.2
int snd_config_get_ireal ( const snd_config_t config,
double *  ptr 
)

Returns the value of a real or integer configuration node.

Parameters:
[in]configHandle to the configuration node.
[out]ptrThe node's value.
Returns:
Zero if successful, otherwise a negative error code.

If the node's type is integer or integer64, the value is converted to the double type on the fly.

Errors:
-EINVAL
config is not a number node.
int snd_config_get_pointer ( const snd_config_t config,
const void **  ptr 
)

Returns the value of a pointer configuration node.

Parameters:
[in]configHandle to the configuration node.
[out]ptrThe function puts the node's value at the address specified by ptr.
Returns:
Zero if successful, otherwise a negative error code.
Errors:
-EINVAL
config is not a string node.
int snd_config_get_real ( const snd_config_t config,
double *  ptr 
)

Returns the value of a real-number configuration node.

Parameters:
[in]configHandle to the configuration node.
[out]ptrThe node's value.
Returns:
Zero if successful, otherwise a negative error code.
Errors:
-EINVAL
config is not a real-number node.
int snd_config_get_string ( const snd_config_t config,
const char **  ptr 
)

Returns the value of a string configuration node.

Parameters:
[in]configHandle to the configuration node.
[out]ptrThe function puts the node's value at the address specified by ptr.
Returns:
Zero if successful, otherwise a negative error code.

The returned string is owned by the configuration node; the application must not modify or delete it, and the string becomes invalid when the node's value changes or when the node is freed.

The string may be NULL.

Errors:
-EINVAL
config is not a string node.
Conforming to:
LSB 3.2
snd_config_type_t snd_config_get_type ( const snd_config_t config)

Returns the type of a configuration node.

Parameters:
configHandle to the configuration node.
Returns:
The node's type.
Conforming to:
LSB 3.2
int snd_config_imake_integer ( snd_config_t **  config,
const char *  id,
const long  value 
)

Creates an integer configuration node with the given initial value.

Parameters:
[out]configThe function puts the handle to the new node at the address specified by config.
[in]idThe id of the new node.
[in]valueThe initial value of the new node.
Returns:
Zero if successful, otherwise a negative error code.

This function creates a new node of type SND_CONFIG_TYPE_INTEGER and with value value.

Errors:
-ENOMEM
Out of memory.
Conforming to:
LSB 3.2
int snd_config_imake_integer64 ( snd_config_t **  config,
const char *  id,
const long long  value 
)

Creates a 64-bit-integer configuration node with the given initial value.

Parameters:
[out]configThe function puts the handle to the new node at the address specified by config.
[in]idThe id of the new node.
[in]valueThe initial value of the new node.
Returns:
Zero if successful, otherwise a negative error code.

This function creates a new node of type SND_CONFIG_TYPE_INTEGER64 and with value value.

Errors:
-ENOMEM
Out of memory.
Conforming to:
LSB 3.2
int snd_config_imake_pointer ( snd_config_t **  config,
const char *  id,
const void *  value 
)

Creates a pointer configuration node with the given initial value.

Parameters:
[out]configThe function puts the handle to the new node at the address specified by config.
[in]idThe id of the new node.
[in]valueThe initial value of the new node.
Returns:
Zero if successful, otherwise a negative error code.

This function creates a new node of type SND_CONFIG_TYPE_POINTER and with value value.

Errors:
-ENOMEM
Out of memory.
int snd_config_imake_real ( snd_config_t **  config,
const char *  id,
const double  value 
)

Creates a real number configuration node with the given initial value.

Parameters:
[out]configThe function puts the handle to the new node at the address specified by config.
[in]idThe id of the new node.
[in]valueThe initial value of the new node.
Returns:
Zero if successful, otherwise a negative error code.

This function creates a new node of type SND_CONFIG_TYPE_REAL and with value value.

Errors:
-ENOMEM
Out of memory.
int snd_config_imake_string ( snd_config_t **  config,
const char *  id,
const char *  value 
)

Creates a string configuration node with the given initial value.

Parameters:
[out]configThe function puts the handle to the new node at the address specified by config.
[in]idThe id of the new node.
[in]valueThe initial value of the new node. May be NULL.
Returns:
Zero if successful, otherwise a negative error code.

This function creates a new node of type SND_CONFIG_TYPE_STRING and with a copy of the string value.

Errors:
-ENOMEM
Out of memory.
Conforming to:
LSB 3.2
snd_config_iterator_t snd_config_iterator_end ( const snd_config_t config)

Returns an iterator that ends a node's children list.

Parameters:
[in]configHandle to a configuration node.
Returns:
An iterator that indicates the end of config's children list.

config must be a compound node.

The return value can be understood as pointing past the last child of config.

Conforming to:
LSB 3.2
snd_config_t* snd_config_iterator_entry ( const snd_config_iterator_t  iterator)

Returns the configuration node handle pointed to by an iterator.

Parameters:
[in]iteratorA configuration node iterator.
Returns:
The configuration node handle pointed to by iterator.
Conforming to:
LSB 3.2
snd_config_iterator_t snd_config_iterator_first ( const snd_config_t config)

Returns an iterator pointing to a node's first child.

Parameters:
[in]configHandle to a configuration node.
Returns:
An iterator pointing to config's first child.

config must be a compound node.

The returned iterator is valid if it is not equal to the return value of snd_config_iterator_end on config.

Use snd_config_iterator_entry to get the handle of the node pointed to.

Conforming to:
LSB 3.2
snd_config_iterator_t snd_config_iterator_next ( const snd_config_iterator_t  iterator)

Returns an iterator pointing to the next sibling.

Parameters:
[in]iteratorAn iterator pointing to a child configuration node.
Returns:
An iterator pointing to the next sibling of iterator.

The returned iterator is valid if it is not equal to the return value of snd_config_iterator_end on the node's parent.

Use snd_config_iterator_entry to get the handle of the node pointed to.

Conforming to:
LSB 3.2
int snd_config_load ( snd_config_t config,
snd_input_t in 
)

Loads a configuration tree.

Parameters:
configHandle to a top level configuration node.
inInput handle to read the configuration from.
Returns:
Zero if successful, otherwise a negative error code.

The definitions loaded from the input are added to config, which must be a compound node.

Errors:
Any errors encountered when parsing the input or returned by hooks or functions.
Conforming to:
LSB 3.2
int snd_config_load_override ( snd_config_t config,
snd_input_t in 
)

Loads a configuration tree and overrides existing configuration nodes.

Parameters:
configHandle to a top level configuration node.
inInput handle to read the configuration from.
Returns:
Zero if successful, otherwise a negative error code.

This function loads definitions from in into config like snd_config_load, but the default mode for input nodes is 'override' (!) instead of 'merge+create' (+).

int snd_config_make ( snd_config_t **  config,
const char *  id,
snd_config_type_t  type 
)

Creates a configuration node.

Parameters:
[out]configThe function puts the handle to the new node at the address specified by config.
[in]idThe id of the new node.
[in]typeThe type of the new node.
Returns:
Zero if successful, otherwise a negative error code.

This functions creates a new node of the specified type. The new node has id id, which may be NULL.

The value of the new node is zero (for numbers), or NULL (for strings and pointers), or empty (for compound nodes).

Errors:
-ENOMEM
Out of memory.
int snd_config_make_compound ( snd_config_t **  config,
const char *  id,
int  join 
)

Creates an empty compound configuration node.

Parameters:
[out]configThe function puts the handle to the new node at the address specified by config.
[in]idThe id of the new node.
[in]joinJoin flag.
Returns:
Zero if successful, otherwise a negative error code.

This function creates a new empty node of type SND_CONFIG_TYPE_COMPOUND.

join determines how the compound node's id is printed when the configuration is saved to a text file. For example, if the join flag of compound node a is zero, the output will look as follows:

a {
b "hello"
c 42
}

If, however, the join flag of a is nonzero, its id will be joined with its children's ids, like this:

a.b "hello"
a.c 42

An empty compound node with its join flag set would result in no output, i.e., after saving and reloading the configuration file, that compound node would be lost.

Errors:
-ENOMEM
Out of memory.
Conforming to:
LSB 3.2
int snd_config_make_integer ( snd_config_t **  config,
const char *  id 
)

Creates an integer configuration node.

Parameters:
[out]configThe function puts the handle to the new node at the address specified by config.
[in]idThe id of the new node.
Returns:
Zero if successful, otherwise a negative error code.

This function creates a new node of type SND_CONFIG_TYPE_INTEGER and with value 0.

Errors:
-ENOMEM
Out of memory.
Conforming to:
LSB 3.2
See also:
snd_config_imake_integer
int snd_config_make_integer64 ( snd_config_t **  config,
const char *  id 
)

Creates a 64-bit-integer configuration node.

Parameters:
[out]configThe function puts the handle to the new node at the address specified by config.
[in]idThe id of the new node.
Returns:
Zero if successful, otherwise a negative error code.

This function creates a new node of type SND_CONFIG_TYPE_INTEGER64 and with value 0.

Errors:
-ENOMEM
Out of memory.
Conforming to:
LSB 3.2
See also:
snd_config_imake_integer64
int snd_config_make_pointer ( snd_config_t **  config,
const char *  id 
)

Creates a pointer configuration node.

Parameters:
[out]configThe function puts the handle to the new node at the address specified by config.
[in]idThe id of the new node.
Returns:
Zero if successful, otherwise a negative error code.

This function creates a new node of type SND_CONFIG_TYPE_POINTER and with value NULL.

Errors:
-ENOMEM
Out of memory.
See also:
snd_config_imake_pointer
int snd_config_make_real ( snd_config_t **  config,
const char *  id 
)

Creates a real number configuration node.

Parameters:
[out]configThe function puts the handle to the new node at the address specified by config.
[in]idThe id of the new node.
Returns:
Zero if successful, otherwise a negative error code.

This function creates a new node of type SND_CONFIG_TYPE_REAL and with value 0.0.

Errors:
-ENOMEM
Out of memory.
See also:
snd_config_imake_real
int snd_config_make_string ( snd_config_t **  config,
const char *  id 
)

Creates a string configuration node.

Parameters:
[out]configThe function puts the handle to the new node at the address specified by config.
[in]idThe id of the new node.
Returns:
Zero if successful, otherwise a negative error code.

This function creates a new node of type SND_CONFIG_TYPE_STRING and with value NULL.

Errors:
-ENOMEM
Out of memory.
Conforming to:
LSB 3.2
See also:
snd_config_imake_string
int snd_config_save ( snd_config_t config,
snd_output_t out 
)

Dumps the contents of a configuration node or tree.

Parameters:
configHandle to the (root) configuration node.
outOutput handle.
Returns:
Zero if successful, otherwise a negative error code.

This function writes a textual representation of config's value to the output out.

Errors:
-EINVAL
A node in the tree has a type that cannot be printed, i.e., SND_CONFIG_TYPE_POINTER.
Conforming to:
LSB 3.2
int snd_config_search ( snd_config_t config,
const char *  key,
snd_config_t **  result 
)

Searches for a node in a configuration tree.

Parameters:
[in]configHandle to the root of the configuration (sub)tree to search.
[in]keySearch key: one or more node ids, separated with dots.
[out]resultWhen result != NULL, the function puts the handle to the node found at the address specified by result.
Returns:
Zero if successful, otherwise a negative error code.

This function searches for a child node of config that is identified by key, which contains either the id of a direct child node of config, or a series of ids, separated with dots, where each id specifies a node that is contained in the previous compound node.

In the following example, the comment after each node shows the search key to find that node, assuming that config is a handle to the compound node with id config:

config {
a 42 # "a"
b { # "b"
c "cee" # "b.c"
d { # "b.d"
e 2.71828 # "b.d.e"
}
}
}
Errors:
-ENOENT
An id in key does not exist.
-ENOENT
config or one of its child nodes to be searched is not a compound node.
Conforming to:
LSB 3.2
int snd_config_search_definition ( snd_config_t config,
const char *  base,
const char *  name,
snd_config_t **  result 
)

Searches for a definition in a configuration tree, using aliases and expanding hooks and arguments.

Parameters:
[in]configHandle to the configuration (sub)tree to search.
[in]baseImplicit key base, or NULL for none.
[in]nameKey suffix, optionally with arguments.
[out]resultThe function puts the handle to the expanded found node at the address specified by result.
Returns:
A non-negative value if successful, otherwise a negative error code.

This functions searches for a child node of config, allowing aliases and expanding hooks, like snd_config_search_alias_hooks.

If name contains a colon (:), the rest of the string after the colon contains arguments that are expanded as with snd_config_expand.

In any case, result is a new node that must be freed by the caller.

Errors:
-ENOENT
An id in key or an alias id does not exist.
-ENOENT
config or one of its child nodes to be searched is not a compound node.
Additionally, any errors encountered when parsing the hook definitions or arguments, or returned by (hook) functions.
int snd_config_searchv ( snd_config_t config,
snd_config_t **  result,
  ... 
)

Searches for a node in a configuration tree.

Parameters:
[in]configHandle to the root of the configuration (sub)tree to search.
[out]resultWhen result != NULL, the function puts the handle to the node found at the address specified by result.
[in]...One or more concatenated dot-separated search keys, terminated with NULL.
Returns:
Zero if successful, otherwise a negative error code.

This functions searches for a child node of config like snd_config_search, but the search key is the concatenation of all passed search key strings. For example, the call

snd_config_searchv(cfg, &res, "a", "b.c", "d.e", NULL);

is equivalent to the call

snd_config_search(cfg, "a.b.c.d.e", &res);
Errors:
-ENOENT
An id in a search key does not exist.
-ENOENT
config or one of its child nodes to be searched is not a compound node.
Conforming to:
LSB 3.2
int snd_config_set_ascii ( snd_config_t config,
const char *  ascii 
)

Changes the value of a configuration node.

Parameters:
configHandle to the configuration node.
asciiThe new value for the node, as an ASCII string.
Returns:
Zero if successful, otherwise a negative error code.

This function changes the node's value to a new value that is parsed from the string ascii. ascii must not be NULL, not even for a string node.

The node's type does not change, i.e., the string must contain a valid value with the same type as the node's type. For a string node, the node's new value is a copy of ascii.

Errors:
-EINVAL
config is not a number or string node.
-EINVAL
The value in ascii cannot be parsed.
-ERANGE
The value in ascii is too big for the node's type.
-ENOMEM
Out of memory.
Conforming to:
LSB 3.2
int snd_config_set_id ( snd_config_t config,
const char *  id 
)

Sets the id of a configuration node.

Parameters:
configHandle to the configuration node.
idThe new node id, must not be NULL.
Returns:
Zero if successful, otherwise a negative error code.

This function stores a copy of id in the node.

Errors:
-EEXIST
One of config's siblings already has the id id.
-EINVAL
The id of a node with a parent cannot be set to NULL.
-ENOMEM
Out of memory.
int snd_config_set_integer ( snd_config_t config,
long  value 
)

Changes the value of an integer configuration node.

Parameters:
configHandle to the configuration node.
valueThe new value for the node.
Returns:
Zero if successful, otherwise a negative error code.
Errors:
-EINVAL
config is not an integer node.
Conforming to:
LSB 3.2
int snd_config_set_integer64 ( snd_config_t config,
long long  value 
)

Changes the value of a 64-bit-integer configuration node.

Parameters:
configHandle to the configuration node.
valueThe new value for the node.
Returns:
Zero if successful, otherwise a negative error code.
Errors:
-EINVAL
config is not a 64-bit-integer node.
Conforming to:
LSB 3.2
int snd_config_set_pointer ( snd_config_t config,
const void *  value 
)

Changes the value of a pointer configuration node.

Parameters:
configHandle to the configuration node.
valueThe new value for the node. May be NULL.
Returns:
Zero if successful, otherwise a negative error code.

This function does not free the old pointer in the node.

Errors:
-EINVAL
config is not a pointer node.
int snd_config_set_real ( snd_config_t config,
double  value 
)

Changes the value of a real-number configuration node.

Parameters:
configHandle to the configuration node.
valueThe new value for the node.
Returns:
Zero if successful, otherwise a negative error code.
Errors:
-EINVAL
config is not a real-number node.
int snd_config_set_string ( snd_config_t config,
const char *  value 
)

Changes the value of a string configuration node.

Parameters:
configHandle to the configuration node.
valueThe new value for the node. May be NULL.
Returns:
Zero if successful, otherwise a negative error code.

This function deletes the old string in the node and stores a copy of value string in the node.

Errors:
-EINVAL
config is not a string node.
Conforming to:
LSB 3.2
int snd_config_test_id ( const snd_config_t config,
const char *  id 
)

Compares the id of a configuration node to a given string.

Parameters:
configHandle to the configuration node.
idASCII id.
Returns:
The same value as the result of the strcmp function, i.e., less than zero if config's id is lexicographically less than id, zero if config's id is equal to id, greater than zero otherwise.
int snd_config_top ( snd_config_t **  config)

Creates a top level configuration node.

Parameters:
[out]configHandle to the new node.
Returns:
Zero if successful, otherwise a negative error code.

The returned node is an empty compound node without a parent and without an id.

Errors:
-ENOMEM
Out of memory.
Conforming to:
LSB 3.2
int snd_config_update ( void  )

Updates snd_config by rereading the global configuration files (if needed).

Returns:
0 if snd_config was up to date, 1 if snd_config was updated, otherwise a negative error code.
Warning:
Whenever snd_config is updated, all string pointers and configuration node handles previously obtained from it may become invalid.
Errors:
Any errors encountered when parsing the input or returned by hooks or functions.
Conforming to:
LSB 3.2
int snd_config_update_free ( snd_config_update_t update)

Frees a private update structure.

Parameters:
[in]updateThe private update structure to free.
Returns:
Zero if successful, otherwise a negative error code.
int snd_config_update_free_global ( void  )

Frees the global configuration tree in snd_config.

Returns:
Zero if successful, otherwise a negative error code.

This functions releases all resources of the global configuration tree, and sets snd_config to NULL.

Conforming to:
LSB 3.2
int snd_config_update_r ( snd_config_t **  _top,
snd_config_update_t **  _update,
const char *  cfgs 
)

Updates a configuration tree by rereading the configuration files (if needed).

Parameters:
[in,out]_topAddress of the handle to the top-level node.
[in,out]_updateAddress of a pointer to private update information.
[in]cfgsA list of configuration file names, delimited with ':'. If cfgs is NULL, the default global configuration file is used.
Returns:
0 if _top was up to date, 1 if the configuration files have been reread, otherwise a negative error code.

The variables pointed to by _top and _update can be initialized to NULL before the first call to this function. The private update information holds information about all used configuration files that allows this function to detects changes to them; this data can be freed with snd_config_update_free.

The global configuration files are specified in the environment variable ALSA_CONFIG_PATH.

Warning:
If the configuration tree is reread, all string pointers and configuration node handles previously obtained from this tree become invalid.
Errors:
Any errors encountered when parsing the input or returned by hooks or functions.
int snd_names_list ( const char *  iface,
snd_devname_t **  list 
)

This function is unimplemented.

Deprecated:
Since 1.0.14
void snd_names_list_free ( snd_devname_t *  list)

This function is unimplemented.

Deprecated:
Since 1.0.14

Variable Documentation

snd_config_t* snd_config

Configuration top-level node (the global configuration).

This variable contains a handle to the top-level configuration node, as loaded from global configuration file.

This variable is initialized or updated by snd_config_update. Functions like snd_pcm_open (that use a device name from the global configuration) automatically call snd_config_update. Before the first call to snd_config_update, this variable is NULL.

The global configuration files are specified in the environment variable ALSA_CONFIG_PATH. If this is not set, the default value is "/usr/share/alsa/alsa.conf".

Warning:
Whenever the configuration tree is updated, all string pointers and configuration node handles previously obtained from this variable may become invalid.
Conforming to:
LSB 3.2
snd_config_t* snd_config = NULL

Configuration top-level node (the global configuration).

This variable contains a handle to the top-level configuration node, as loaded from global configuration file.

This variable is initialized or updated by snd_config_update. Functions like snd_pcm_open (that use a device name from the global configuration) automatically call snd_config_update. Before the first call to snd_config_update, this variable is NULL.

The global configuration files are specified in the environment variable ALSA_CONFIG_PATH. If this is not set, the default value is "/usr/share/alsa/alsa.conf".

Warning:
Whenever the configuration tree is updated, all string pointers and configuration node handles previously obtained from this variable may become invalid.
Conforming to:
LSB 3.2