Configuration helper functions. More...

Macros
#define	ALSA_CONFIG_PATH_VAR "ALSA_CONFIG_PATH"

Functions
const char *	snd_config_topdir (void)
	Returns the default top-level config directory.

int	snd_config_substitute (snd_config_t dst, snd_config_t src)
	Substitutes one configuration node to another.

int	snd_config_get_type_ascii (const char ascii, snd_config_type_t type)
	Converts an ASCII string to a configuration node type.

snd_config_type_t	snd_config_get_type (const snd_config_t *config)
	Returns the type of a configuration node.

int	snd_config_is_array (const snd_config_t *config)
	Returns if the compound is an array (and count of items).

int	snd_config_is_empty (const snd_config_t *config)
	Returns if the compound has no fields (is empty).

int	snd_config_get_id (const snd_config_t config, const char *id)
	Returns the id 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_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_string (snd_config_t *config, const char s, size_t size)
	Loads a configuration tree from a string.

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_add (snd_config_t parent, snd_config_t child)
	Adds a child to a compound configuration node.

int	snd_config_add_after (snd_config_t after, snd_config_t child)
	Adds a child after another child configuration node.

int	snd_config_add_before (snd_config_t before, snd_config_t child)
	Adds a child before another child configuration node.

int	snd_config_merge (snd_config_t dst, snd_config_t src, int override)
	In-place merge of two config handles.

int	snd_config_remove (snd_config_t *config)
	Removes a configuration node from its tree.

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_make (snd_config_t *config, const char id, snd_config_type_t type)
	Creates a configuration node.

int	snd_config_make_integer (snd_config_t *config, const char id)
	Creates an integer configuration node.

int	snd_config_make_integer64 (snd_config_t *config, const char id)
	Creates a 64-bit-integer configuration node.

int	snd_config_make_real (snd_config_t *config, const char id)
	Creates a real number configuration node.

int	snd_config_make_string (snd_config_t *config, const char id)
	Creates a string configuration node.

int	snd_config_make_pointer (snd_config_t *config, const char id)
	Creates a pointer configuration node.

int	snd_config_make_compound (snd_config_t *config, const char id, int join)
	Creates an empty compound configuration node.

int	snd_config_make_path (snd_config_t *config, snd_config_t root, const char *key, int join, int override)
	Creates an empty compound configuration node in the path.

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.

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.

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.

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.

int	snd_config_imake_safe_string (snd_config_t *config, const char id, const char *value)
	Creates a string configuration node with the given initial value.

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.

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_pointer (snd_config_t config, const void value)
	Changes the value of a pointer configuration node.

int	snd_config_set_ascii (snd_config_t config, const char ascii)
	Changes the value of a configuration node.

int	snd_config_get_integer (const snd_config_t config, long ptr)
	Returns the value of an integer configuration node.

int	snd_config_get_integer64 (const snd_config_t config, long long ptr)
	Returns the value of a 64-bit-integer configuration node.

int	snd_config_get_real (const snd_config_t config, double ptr)
	Returns the value of a real-number configuration node.

int	snd_config_get_ireal (const snd_config_t config, double ptr)
	Returns the value of a real or integer configuration node.

int	snd_config_get_string (const snd_config_t config, const char *ptr)
	Returns the value of a string configuration node.

int	snd_config_get_pointer (const snd_config_t config, const void *ptr)
	Returns the value of a pointer configuration node.

int	snd_config_get_ascii (const snd_config_t config, char *ascii)
	Returns the value of a configuration node as a string.

int	snd_config_test_id (const snd_config_t config, const char id)
	Compares the id of a configuration node to a given string.

int	snd_config_save (snd_config_t config, snd_output_t out)
	Dumps the contents of a configuration node or tree.

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_searcha (snd_config_t root, snd_config_t config, const char key, snd_config_t *result)
	Searches for a node in a configuration tree, expanding aliases.

int	snd_config_searchv (snd_config_t config, snd_config_t *result,...)
	Searches for a node in a configuration tree.

int	snd_config_searchva (snd_config_t root, snd_config_t config, snd_config_t **result,...)
	Searches for a node in a configuration tree, expanding aliases.

int	snd_config_search_alias (snd_config_t config, const char base, const char key, snd_config_t *result)
	Searches for a node in a configuration tree, expanding aliases.

int	snd_config_search_hooks (snd_config_t config, const char key, snd_config_t **result)
	Searches for a node in a configuration tree and expands hooks.

int	snd_config_searcha_hooks (snd_config_t root, snd_config_t config, const char key, snd_config_t *result)
	Searches for a node in a configuration tree, expanding aliases and hooks.

int	snd_config_searchva_hooks (snd_config_t root, snd_config_t config, snd_config_t **result,...)
	Searches for a node in a configuration tree, expanding aliases and hooks.

int	snd_config_search_alias_hooks (snd_config_t config, const char base, const char key, snd_config_t *result)
	Searches for a node in a configuration tree, using an alias and expanding hooks.

int	snd_config_hook_load (snd_config_t root, snd_config_t config, snd_config_t *dst, snd_config_t private_data)
	Loads and parses the given configurations files.

int	snd_config_hook_load_for_all_cards (snd_config_t root, snd_config_t config, snd_config_t *dst, snd_config_t private_data)
	Loads and parses the given configurations files for each installed sound card.

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

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

int	snd_config_update_ref (snd_config_t **top)
	Updates snd_config and takes its reference.

void	snd_config_ref (snd_config_t *cfg)
	Take the reference of the config tree.

void	snd_config_unref (snd_config_t *cfg)
	Unreference the config tree.

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.

snd_config_iterator_t	snd_config_iterator_first (const snd_config_t *config)
	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 *config)
	Returns an iterator that ends a node's children list.

snd_config_t *	snd_config_iterator_entry (const snd_config_iterator_t iterator)
	Returns the configuration node handle pointed to by an iterator.

int	snd_config_copy (snd_config_t *dst, snd_config_t src)
	Creates a copy of a configuration 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.

int	snd_config_expand_custom (snd_config_t config, snd_config_t root, snd_config_expand_fcn_t fcn, void private_data, snd_config_t *result)
	Expands a configuration node, applying arguments and functions.

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

Variables
snd_config_t *	snd_config = NULL
	Configuration top-level node (the global configuration).

Detailed Description

Configuration helper functions.

Author: Abramo Bagnara abram.nosp@m.o@al.nosp@m.sa-pr.nosp@m.ojec.nosp@m.t.org; Jaroslav Kysela perex.nosp@m.@per.nosp@m.ex.cz

Date: 2000-2001

Tree based, full nesting configuration functions.

See the Configuration files page for more details.

Macro Definition Documentation

◆ ALSA_CONFIG_PATH_VAR

#define ALSA_CONFIG_PATH_VAR "ALSA_CONFIG_PATH"

The name of the environment variable containing the files list for snd_config_update.

Function Documentation

◆ snd_config_add()

int snd_config_add	(	snd_config_t *	parent,
		snd_config_t *	child )

Adds a child to a compound configuration node.

Parameters

parent	Handle to a compound configuration node.
child	Handle 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

◆ snd_config_add_after()

int snd_config_add_after	(	snd_config_t *	after,
		snd_config_t *	child )

Adds a child after another child configuration node.

Parameters

after	Handle to the start configuration node.
child	Handle 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 parent of the node after.

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.

◆ snd_config_add_before()

int snd_config_add_before	(	snd_config_t *	before,
		snd_config_t *	child )

Adds a child before another child configuration node.

Parameters

before	Handle to the start configuration node.
child	Handle 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 parent of the node before.

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.

◆ snd_config_copy()

int snd_config_copy	(	snd_config_t **	dst,
		snd_config_t *	src )

Creates a copy of a configuration node.

Parameters

[out]	dst	The function puts the handle to the new configuration node at the address specified by dst.
[in]	src	Handle 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

◆ snd_config_delete()

int snd_config_delete ( snd_config_t * config )

Frees a configuration node.

Parameters

config Handle 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.

The function is supposed to be called only for locally copied config trees. For the global tree, take the reference via snd_config_update_ref and free it via snd_config_unref.

Conforming to:: LSB 3.2

See also: snd_config_remove

◆ snd_config_delete_compound_members()

int snd_config_delete_compound_members ( const snd_config_t * config )

Deletes the children of a node.

Parameters

config Handle 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.

◆ snd_config_evaluate()

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]	config	Handle to the source configuration node.
[in]	root	Handle to the root of the source configuration.
[in]	private_data	Handle to the private data node for runtime evaluation.
	result	Must 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.

◆ snd_config_expand()

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]	config	Handle to the configuration node.
[in]	root	Handle to the root configuration node.
[in]	args	Arguments string, can be `NULL`.
[in]	private_data	Handle to the private data node for functions.
[out]	result	The 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.

◆ snd_config_expand_custom()

int snd_config_expand_custom	(	snd_config_t *	config,
		snd_config_t *	root,
		snd_config_expand_fcn_t	fcn,
		void *	private_data,
		snd_config_t **	result )

Expands a configuration node, applying arguments and functions.

Parameters

[in]	config	Handle to the configuration node.
[in]	root	Handle to the root configuration node.
[in]	fcn	Custom function to obtain the referred variable name
[in]	private_data	Private data node for the custom function
[out]	result	The 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.

The new tree is not evaluated (snd_config_evaluate).

◆ snd_config_get_ascii()

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

Returns the value of a configuration node as a string.

Parameters

[in]	config	Handle to the configuration node.
[out]	ascii	The 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

◆ snd_config_get_id()

int snd_config_get_id	(	const snd_config_t *	config,
		const char **	id )

Returns the id of a configuration node.

Parameters

[in]	config	Handle to the configuration node.
[out]	id	The 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

◆ snd_config_get_integer()

int snd_config_get_integer	(	const snd_config_t *	config,
		long *	ptr )

Returns the value of an integer configuration node.

Parameters

[in]	config	Handle to the configuration node.
[out]	ptr	The 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

◆ snd_config_get_integer64()

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]	config	Handle to the configuration node.
[out]	ptr	The 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

◆ snd_config_get_ireal()

int snd_config_get_ireal	(	const snd_config_t *	config,
		double *	ptr )

Returns the value of a real or integer configuration node.

Parameters

[in]	config	Handle to the configuration node.
[out]	ptr	The 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.

◆ snd_config_get_pointer()

int snd_config_get_pointer	(	const snd_config_t *	config,
		const void **	ptr )

Returns the value of a pointer configuration node.

Parameters

[in]	config	Handle to the configuration node.
[out]	ptr	The 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.

◆ snd_config_get_real()

int snd_config_get_real	(	const snd_config_t *	config,
		double *	ptr )

Returns the value of a real-number configuration node.

Parameters

[in]	config	Handle to the configuration node.
[out]	ptr	The node's value.

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

Errors:

-EINVAL: config is not a real-number node.

◆ snd_config_get_string()

int snd_config_get_string	(	const snd_config_t *	config,
		const char **	ptr )

Returns the value of a string configuration node.

Parameters

[in]	config	Handle to the configuration node.
[out]	ptr	The 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_get_type()

snd_config_type_t snd_config_get_type ( const snd_config_t * config )

Returns the type of a configuration node.

Parameters

config Handle to the configuration node.

Returns: The node's type.

Conforming to:: LSB 3.2

◆ snd_config_get_type_ascii()

int snd_config_get_type_ascii	(	const char *	ascii,
		snd_config_type_t *	type )

Converts an ASCII string to a configuration node type.

Parameters

[in]	ascii	A string containing a configuration node type.
[out]	type	The node type corresponding to ascii.

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

This function recognizes at least the following node types:

integer<dt>#SND_CONFIG_TYPE_INTEGER
integer64<dt>#SND_CONFIG_TYPE_INTEGER64
real<dt>#SND_CONFIG_TYPE_REAL
string<dt>#SND_CONFIG_TYPE_STRING
compound<dt>#SND_CONFIG_TYPE_COMPOUND

Errors:

-EINVAL: Unknown note type in type.

◆ snd_config_hook_load()

int snd_config_hook_load	(	snd_config_t *	root,
		snd_config_t *	config,
		snd_config_t **	dst,
		snd_config_t *	private_data )

Loads and parses the given configurations files.

Parameters

[in]	root	Handle to the root configuration node.
[in]	config	Handle to the configuration node for this hook.
[out]	dst	The function puts the handle to the configuration node loaded from the file(s) at the address specified by dst.
[in]	private_data	Handle to the private data configuration node.

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

See Hooks in configuration files for an example.

◆ snd_config_hook_load_for_all_cards()

int snd_config_hook_load_for_all_cards	(	snd_config_t *	root,
		snd_config_t *	config,
		snd_config_t **	dst,
		snd_config_t *	private_data )

Loads and parses the given configurations files for each installed sound card.

Parameters

[in]	root	Handle to the root configuration node.
[in]	config	Handle to the configuration node for this hook.
[out]	dst	The function puts the handle to the configuration node loaded from the file(s) at the address specified by dst.
[in]	private_data	Handle to the private data configuration node.

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

This function works like snd_config_hook_load, but the files are loaded once for each sound card. The driver name is available with the private_string function to customize the file name.

◆ snd_config_imake_integer()

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]	config	The function puts the handle to the new node at the address specified by config.
[in]	id	The id of the new node.
[in]	value	The 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

◆ snd_config_imake_integer64()

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]	config	The function puts the handle to the new node at the address specified by config.
[in]	id	The id of the new node.
[in]	value	The 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

◆ snd_config_imake_pointer()

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]	config	The function puts the handle to the new node at the address specified by config.
[in]	id	The id of the new node.
[in]	value	The 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.

◆ snd_config_imake_real()

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]	config	The function puts the handle to the new node at the address specified by config.
[in]	id	The id of the new node.
[in]	value	The 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.

◆ snd_config_imake_safe_string()

int snd_config_imake_safe_string	(	snd_config_t **	config,
		const char *	id,
		const char *	value )

Creates a string configuration node with the given initial value.

Parameters

[out]	config	The function puts the handle to the new node at the address specified by config.
[in]	id	The id of the new node.
[in]	value	The 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. The node contains with a copy of the string value, replacing any character other than alphanumeric, space, or '-' with the character '_'.

Errors:

-ENOMEM: Out of memory.

Conforming to:: LSB 3.2

◆ snd_config_imake_string()

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]	config	The function puts the handle to the new node at the address specified by config.
[in]	id	The id of the new node.
[in]	value	The 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_is_array()

int snd_config_is_array ( const snd_config_t * config )

Returns if the compound is an array (and count of items).

Parameters

config Handle to the configuration node.

Returns: A count of items in array, zero when the compound is not an array, otherwise a negative error code.

◆ snd_config_is_empty()

int snd_config_is_empty ( const snd_config_t * config )

Returns if the compound has no fields (is empty).

Parameters

config Handle to the configuration node.

Returns: A positive value when true, zero when false, otherwise a negative error code.

◆ snd_config_iterator_end()

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] config Handle 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_iterator_entry()

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] iterator A configuration node iterator.

Returns: The configuration node handle pointed to by iterator.

Conforming to:: LSB 3.2

◆ snd_config_iterator_first()

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] config Handle 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_next()

snd_config_iterator_t snd_config_iterator_next ( const snd_config_iterator_t iterator )

Returns an iterator pointing to the next sibling.

Parameters

[in] iterator An 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

◆ snd_config_load()

int snd_config_load	(	snd_config_t *	config,
		snd_input_t *	in )

Loads a configuration tree.

Parameters

config	Handle to a top level configuration node.
in	Input 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

◆ snd_config_load_override()

int snd_config_load_override	(	snd_config_t *	config,
		snd_input_t *	in )

Loads a configuration tree and overrides existing configuration nodes.

Parameters

config	Handle to a top level configuration node.
in	Input 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' (+).

◆ snd_config_load_string()

int snd_config_load_string	(	snd_config_t **	config,
		const char *	s,
		size_t	size )

Loads a configuration tree from a string.

Parameters

[out]	config	The function puts the handle to the configuration node loaded from the file(s) at the address specified by config.
[in]	s	String with the ASCII configuration
[in]	size	String size, if zero, a C string is expected (with termination)

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

The definitions loaded from the string are put to config, which is created as a new top node.

Errors:: Any errors encountered when parsing the input or returned by hooks or functions.

◆ snd_config_make()

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

Creates a configuration node.

Parameters

[out]	config	The function puts the handle to the new node at the address specified by config.
[in]	id	The id of the new node.
[in]	type	The 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.

◆ snd_config_make_compound()

int snd_config_make_compound	(	snd_config_t **	config,
		const char *	id,
		int	join )

Creates an empty compound configuration node.

Parameters

[out]	config	The function puts the handle to the new node at the address specified by config.
[in]	id	The id of the new node.
[in]	join	Join 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

◆ snd_config_make_integer()

int snd_config_make_integer	(	snd_config_t **	config,
		const char *	id )

Creates an integer configuration node.

Parameters

[out]	config	The function puts the handle to the new node at the address specified by config.
[in]	id	The 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

◆ snd_config_make_integer64()

int snd_config_make_integer64	(	snd_config_t **	config,
		const char *	id )

Creates a 64-bit-integer configuration node.

Parameters

[out]	config	The function puts the handle to the new node at the address specified by config.
[in]	id	The 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

◆ snd_config_make_path()

int snd_config_make_path	(	snd_config_t **	config,
		snd_config_t *	root,
		const char *	key,
		int	join,
		int	override )

Creates an empty compound configuration node in the path.

Parameters

[out]	config	The function puts the handle to the new or existing compound node at the address specified by config.
[in]	root	The id of the new node.
[in]	key	The id of the new node.
[in]	join	Join flag.
[in]	override	Override flag.

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

This function creates a new empty node of type #SND_CONFIG_TYPE_COMPOUND if the path does not exist. Otherwise, the node from the current configuration tree is returned without any modification. The join argument is ignored in this case.

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.
-EACCESS: Path exists, but it's not a compound (!override)

◆ snd_config_make_pointer()

int snd_config_make_pointer	(	snd_config_t **	config,
		const char *	id )

Creates a pointer configuration node.

Parameters

[out]	config	The function puts the handle to the new node at the address specified by config.
[in]	id	The 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

◆ snd_config_make_real()

int snd_config_make_real	(	snd_config_t **	config,
		const char *	id )

Creates a real number configuration node.

Parameters

[out]	config	The function puts the handle to the new node at the address specified by config.
[in]	id	The 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

◆ snd_config_make_string()

int snd_config_make_string	(	snd_config_t **	config,
		const char *	id )

Creates a string configuration node.

Parameters

[out]	config	The function puts the handle to the new node at the address specified by config.
[in]	id	The 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

◆ snd_config_merge()

int snd_config_merge	(	snd_config_t *	dst,
		snd_config_t *	src,
		int	override )

In-place merge of two config handles.

Parameters

[out]	dst	Config handle for the merged contents
[in]	src	Config handle to merge into dst (may be NULL)
[in]	override	Override flag

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

This function merges all fields from the source compound to the destination compound. When the override flag is set, the related subtree in dst is replaced from src.

When override is not set, the child compounds are traversed and merged.

The configuration elements other than compounds are always substituted (overwritten) from the src config handle.

The src handle is deleted.

Note: On error, config handles may be modified.

Errors:

-EEXIST: identifier already exists (!override)
-ENOMEM: not enough memory

◆ snd_config_ref()

void snd_config_ref ( snd_config_t * cfg )

Take the reference of the config tree.

Increases a reference counter of the given config tree.

This function is supposed to be thread-safe.

◆ snd_config_remove()

int snd_config_remove ( snd_config_t * config )

Removes a configuration node from its tree.

Parameters

config Handle to the configuration node to be removed.

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

This function makes config a top-level node, i.e., if config has a parent, then config is removed from the list of the parent's children.

This functions does not free the removed node.

See also: snd_config_delete

◆ snd_config_save()

int snd_config_save	(	snd_config_t *	config,
		snd_output_t *	out )

Dumps the contents of a configuration node or tree.

Parameters

config	Handle to the (root) configuration node.
out	Output 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

◆ snd_config_search()

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]	config	Handle to the root of the configuration (sub)tree to search.
[in]	key	Search key: one or more node ids, separated with dots.
[out]	result	When 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

◆ snd_config_search_alias()

int snd_config_search_alias	(	snd_config_t *	config,
		const char *	base,
		const char *	key,
		snd_config_t **	result )

Searches for a node in a configuration tree, expanding aliases.

Parameters

[in]	config	Handle to the root of the configuration (sub)tree to search.
[in]	base	Search key base, or `NULL`.
[in]	key	Search key suffix.
[out]	result	When 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 functions searches for a child node of config, allowing aliases, like snd_config_searcha. However, alias definitions are searched below config (there is no separate root parameter), and base specifies a seach key that identifies a compound node that is used to search for an alias definitions that is not found directly below config and that does not contain a period. In other words, when "id" is not found in config, this function also tries "base.id".

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 or string node.

◆ snd_config_search_alias_hooks()

int snd_config_search_alias_hooks	(	snd_config_t *	config,
		const char *	base,
		const char *	key,
		snd_config_t **	result )

Searches for a node in a configuration tree, using an alias and expanding hooks.

Parameters

[in]	config	Handle to the root of the configuration (sub)tree to search.
[in]	base	Search key base, or `NULL`.
[in]	key	Search key suffix.
[out]	result	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 functions searches for a child node of config, allowing aliases, like snd_config_search_alias, and expanding hooks, like snd_config_search_hooks.

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 returned by the hook functions.

◆ snd_config_search_definition()

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]	config	Handle to the configuration (sub)tree to search.
[in]	base	Implicit key base, or `NULL` for none.
[in]	name	Key suffix, optionally with arguments.
[out]	result	The 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.

◆ snd_config_search_hooks()

int snd_config_search_hooks	(	snd_config_t *	config,
		const char *	key,
		snd_config_t **	result )

Searches for a node in a configuration tree and expands hooks.

Parameters

[in,out]	config	Handle to the root of the configuration (sub)tree to search.
[in]	key	Search key: one or more node keys, separated with dots.
[out]	result	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 functions searches for a child node of config like snd_config_search, but any compound nodes to be searched that contain hooks are modified by the respective hook functions.

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.

Additionally, any errors encountered when parsing the hook definitions or returned by the hook functions.

◆ snd_config_searcha()

int snd_config_searcha	(	snd_config_t *	root,
		snd_config_t *	config,
		const char *	key,
		snd_config_t **	result )

Searches for a node in a configuration tree, expanding aliases.

Parameters

[in]	root	Handle to the root configuration node containing alias definitions.
[in]	config	Handle to the root of the configuration (sub)tree to search.
[in]	key	Search key: one or more node keys, separated with dots.
[out]	result	When 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 functions searches for a child node of config like snd_config_search. However, any compound node can also be identified by an alias, which is a string node whose value is taken as the id of a compound node below root.

root must be a compound node. root and config may be the same node.

For example, with the following configuration, the call

snd_config_searcha(root, config, "a.b.c.d", &result);

snd_config_searcha

int snd_config_searcha(snd_config_t *root, snd_config_t *config, const char *key, snd_config_t **result)

Searches for a node in a configuration tree, expanding aliases.

Definition conf.c:3680

would return the node with id d:

config {
    a {
        b bb
    }
}
root {
    bb {
        c cc
    }
    cc ccc
    ccc {
        d {
            x "icks"
        }
    }
}

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 or string node.

◆ snd_config_searcha_hooks()

int snd_config_searcha_hooks	(	snd_config_t *	root,
		snd_config_t *	config,
		const char *	key,
		snd_config_t **	result )

Searches for a node in a configuration tree, expanding aliases and hooks.

Parameters

[in]	root	Handle to the root configuration node containing alias definitions.
[in,out]	config	Handle to the root of the configuration (sub)tree to search.
[in]	key	Search key: one or more node keys, separated with dots.
[out]	result	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, allowing aliases, like snd_config_searcha, and expanding hooks, like snd_config_search_hooks.

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 returned by the hook functions.

◆ snd_config_searchv()

int snd_config_searchv	(	snd_config_t *	config,
		snd_config_t **	result,
			... )

Searches for a node in a configuration tree.

Parameters

[in]	config	Handle to the root of the configuration (sub)tree to search.
[out]	result	When 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);

snd_config_searchv

int snd_config_searchv(snd_config_t *config, snd_config_t **result,...)

Searches for a node in a configuration tree.

Definition conf.c:3716

is equivalent to the call

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

snd_config_search

int snd_config_search(snd_config_t *config, const char *key, snd_config_t **result)

Searches for a node in a configuration tree.

Definition conf.c:3625

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

◆ snd_config_searchva()

int snd_config_searchva	(	snd_config_t *	root,
		snd_config_t *	config,
		snd_config_t **	result,
			... )

Searches for a node in a configuration tree, expanding aliases.

Parameters

[in]	root	Handle to the root configuration node containing alias definitions.
[in]	config	Handle to the root of the configuration (sub)tree to search.
[out]	result	When 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 function searches for a child node of config, allowing aliases, like snd_config_searcha, but the search key is the concatenation of all passed seach key strings, like with snd_config_searchv.

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 or string node.

◆ snd_config_searchva_hooks()

int snd_config_searchva_hooks	(	snd_config_t *	root,
		snd_config_t *	config,
		snd_config_t **	result,
			... )

Searches for a node in a configuration tree, expanding aliases and hooks.

Parameters

[in]	root	Handle to the root configuration node containing alias definitions.
[in,out]	config	Handle to the root of the configuration (sub)tree to search.
[out]	result	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 function searches for a child node of config, allowing aliases and expanding hooks like snd_config_searcha_hooks, but the search key is the concatenation of all passed seach key strings, like with snd_config_searchv.

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 returned by the hook functions.

◆ snd_config_set_ascii()

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

Changes the value of a configuration node.

Parameters

config	Handle to the configuration node.
ascii	The 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

◆ snd_config_set_id()

int snd_config_set_id	(	snd_config_t *	config,
		const char *	id )

Sets the id of a configuration node.

Parameters

config	Handle to the configuration node.
id	The 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.

◆ snd_config_set_integer()

int snd_config_set_integer	(	snd_config_t *	config,
		long	value )

Changes the value of an integer configuration node.

Parameters

config	Handle to the configuration node.
value	The 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

◆ snd_config_set_integer64()

int snd_config_set_integer64	(	snd_config_t *	config,
		long long	value )

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

Parameters

config	Handle to the configuration node.
value	The 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

◆ snd_config_set_pointer()

int snd_config_set_pointer	(	snd_config_t *	config,
		const void *	value )

Changes the value of a pointer configuration node.

Parameters

config	Handle to the configuration node.
value	The 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.

◆ snd_config_set_real()

int snd_config_set_real	(	snd_config_t *	config,
		double	value )

Changes the value of a real-number configuration node.

Parameters

config	Handle to the configuration node.
value	The new value for the node.

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

Errors:

-EINVAL: config is not a real-number node.

◆ snd_config_set_string()

int snd_config_set_string	(	snd_config_t *	config,
		const char *	value )

Changes the value of a string configuration node.

Parameters

config	Handle to the configuration node.
value	The 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

◆ snd_config_substitute()

int snd_config_substitute	(	snd_config_t *	dst,
		snd_config_t *	src )

Substitutes one configuration node to another.

Parameters

dst	Handle to the destination node.
src	Handle to the source node. Must not be the same as dst.

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

If both nodes are compounds, the source compound node members will be moved to the destination compound node. The original destination compound node members will be deleted (overwritten).

If the destination node is a compound and the source node is an ordinary type, the compound members are deleted (including their contents).

Otherwise, the source node's value replaces the destination node's value.

In any case, a successful call to this function frees the source node.

◆ snd_config_test_id()

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

config	Handle to the configuration node.
id	ASCII 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.

◆ snd_config_top()

int snd_config_top ( snd_config_t ** config )

Creates a top level configuration node.

Parameters

[out] config Handle 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

◆ snd_config_topdir()

const char * snd_config_topdir ( void )

Returns the default top-level config directory.

Returns: The top-level config directory path string

This function returns the string of the top-level config directory path. If the path is specified via the environment variable ALSA_CONFIG_DIR and the value is a valid path, it returns this value. If unspecified, it returns the default value, "/usr/share/alsa".

◆ snd_config_unref()

void snd_config_unref ( snd_config_t * cfg )

Unreference the config tree.

Decreases a reference counter of the given config tree, and eventually deletes the tree if all references are gone. This is the counterpart of snd_config_unref.

Also, the config taken via snd_config_update_ref must be unreferenced by this function, too.

This function is supposed to be thread-safe.

◆ snd_config_update()

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. For safer operations, use snd_config_update_ref and release the config via snd_config_unref.

Errors:: Any errors encountered when parsing the input or returned by hooks or functions.

Conforming to:: LSB 3.2

◆ snd_config_update_free()

int snd_config_update_free ( snd_config_update_t * update )

Frees a private update structure.

Parameters

[in] update The private update structure to free.

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

◆ snd_config_update_free_global()

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

Examples: /test/latency.c.

◆ snd_config_update_r()

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]	_top	Address of the handle to the top-level node.
[in,out]	_update	Address of a pointer to private update information.
[in]	cfgs	A 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.

◆ snd_config_update_ref()

int snd_config_update_ref ( snd_config_t ** top )

Updates snd_config and takes its reference.

Returns: 0 if snd_config was up to date, 1 if snd_config was updated, otherwise a negative error code.

Unlike snd_config_update, this function increases a reference counter so that the obtained tree won't be deleted until unreferenced by snd_config_unref.

This function is supposed to be thread-safe.

Variable Documentation

◆ snd_config

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

Macros

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ ALSA_CONFIG_PATH_VAR

Function Documentation

◆ snd_config_add()

◆ snd_config_add_after()

◆ snd_config_add_before()

◆ snd_config_copy()

◆ snd_config_delete()

◆ snd_config_delete_compound_members()

◆ snd_config_evaluate()

◆ snd_config_expand()

◆ snd_config_expand_custom()

◆ snd_config_get_ascii()

◆ snd_config_get_id()

◆ snd_config_get_integer()

◆ snd_config_get_integer64()

◆ snd_config_get_ireal()

◆ snd_config_get_pointer()

◆ snd_config_get_real()

◆ snd_config_get_string()

◆ snd_config_get_type()

◆ snd_config_get_type_ascii()

◆ snd_config_hook_load()

◆ snd_config_hook_load_for_all_cards()

◆ snd_config_imake_integer()

◆ snd_config_imake_integer64()

◆ snd_config_imake_pointer()

◆ snd_config_imake_real()

◆ snd_config_imake_safe_string()

◆ snd_config_imake_string()

◆ snd_config_is_array()

◆ snd_config_is_empty()

◆ snd_config_iterator_end()

◆ snd_config_iterator_entry()

◆ snd_config_iterator_first()

◆ snd_config_iterator_next()

◆ snd_config_load()

◆ snd_config_load_override()

◆ snd_config_load_string()

◆ snd_config_make()

◆ snd_config_make_compound()

◆ snd_config_make_integer()

◆ snd_config_make_integer64()

◆ snd_config_make_path()

◆ snd_config_make_pointer()

◆ snd_config_make_real()

◆ snd_config_make_string()

◆ snd_config_merge()

◆ snd_config_ref()

◆ snd_config_remove()

◆ snd_config_save()

◆ snd_config_search()

◆ snd_config_search_alias()

◆ snd_config_search_alias_hooks()

◆ snd_config_search_definition()

◆ snd_config_search_hooks()

◆ snd_config_searcha()

◆ snd_config_searcha_hooks()

◆ snd_config_searchv()

◆ snd_config_searchva()

◆ snd_config_searchva_hooks()

◆ snd_config_set_ascii()

◆ snd_config_set_id()

◆ snd_config_set_integer()

◆ snd_config_set_integer64()

◆ snd_config_set_pointer()

◆ snd_config_set_real()

◆ snd_config_set_string()

◆ snd_config_substitute()

◆ snd_config_test_id()

◆ snd_config_top()

◆ snd_config_topdir()

◆ snd_config_unref()

◆ snd_config_update()

◆ snd_config_update_free()

◆ snd_config_update_free_global()