conf.c File Reference

Configuration helper functions. More...

Include dependency graph for conf.c:

Macros
#define	ALSA_CONFIG_PATH_VAR   "ALSA_CONFIG_PATH"

Functions
int	snd_config_substitute (snd_config_t *dst, snd_config_t *src)
	Substitutes one configuration node to another. More...
int	snd_config_get_type_ascii (const char *ascii, snd_config_type_t *type)
	Converts an ASCII string to a configuration node type. More...
snd_config_type_t	snd_config_get_type (const snd_config_t *config)
	Returns the type of a configuration node. More...
int	snd_config_is_array (const snd_config_t *config)
	Returns if the compound is an array (and count of items). More...
int	snd_config_is_empty (const snd_config_t *config)
	Returns if the compound has no fields (is empty). More...
int	snd_config_get_id (const snd_config_t *config, const char **id)
	Returns the id of a configuration node. More...
int	snd_config_set_id (snd_config_t *config, const char *id)
	Sets the id of a configuration node. More...
int	snd_config_top (snd_config_t **config)
	Creates a top level configuration node. More...
int	snd_config_load (snd_config_t *config, snd_input_t *in)
	Loads a configuration tree. More...
int	snd_config_load_string (snd_config_t **config, const char *s, size_t size)
	Loads a configuration tree from a string. More...
int	snd_config_load_override (snd_config_t *config, snd_input_t *in)
	Loads a configuration tree and overrides existing configuration nodes. More...
int	snd_config_add (snd_config_t *parent, snd_config_t *child)
	Adds a child to a compound configuration node. More...
int	snd_config_add_after (snd_config_t *after, snd_config_t *child)
	Adds a child after another child configuration node. More...
int	snd_config_add_before (snd_config_t *before, snd_config_t *child)
	Adds a child before another child configuration node. More...
int	snd_config_merge (snd_config_t *dst, snd_config_t *src, int override)
	In-place merge of two config handles. More...
int	snd_config_remove (snd_config_t *config)
	Removes a configuration node from its tree. More...
int	snd_config_delete (snd_config_t *config)
	Frees a configuration node. More...
int	snd_config_delete_compound_members (const snd_config_t *config)
	Deletes the children of a node. More...
int	snd_config_make (snd_config_t **config, const char *id, snd_config_type_t type)
	Creates a configuration node. More...
int	snd_config_make_integer (snd_config_t **config, const char *id)
	Creates an integer configuration node. More...
int	snd_config_make_integer64 (snd_config_t **config, const char *id)
	Creates a 64-bit-integer configuration node. More...
int	snd_config_make_real (snd_config_t **config, const char *id)
	Creates a real number configuration node. More...
int	snd_config_make_string (snd_config_t **config, const char *id)
	Creates a string configuration node. More...
int	snd_config_make_pointer (snd_config_t **config, const char *id)
	Creates a pointer configuration node. More...
int	snd_config_make_compound (snd_config_t **config, const char *id, int join)
	Creates an empty compound configuration node. More...
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. More...
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. More...
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. More...
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. More...
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. More...
int	snd_config_imake_safe_string (snd_config_t **config, const char *id, const char *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. More...
int	snd_config_set_integer (snd_config_t *config, long value)
	Changes the value of an integer configuration node. More...
int	snd_config_set_integer64 (snd_config_t *config, long long value)
	Changes the value of a 64-bit-integer configuration node. More...
int	snd_config_set_real (snd_config_t *config, double value)
	Changes the value of a real-number configuration node. More...
int	snd_config_set_string (snd_config_t *config, const char *value)
	Changes the value of a string configuration node. More...
int	snd_config_set_pointer (snd_config_t *config, const void *value)
	Changes the value of a pointer configuration node. More...
int	snd_config_set_ascii (snd_config_t *config, const char *ascii)
	Changes the value of a configuration node. More...
int	snd_config_get_integer (const snd_config_t *config, long *ptr)
	Returns the value of an integer configuration node. More...
int	snd_config_get_integer64 (const snd_config_t *config, long long *ptr)
	Returns the value of a 64-bit-integer configuration node. More...
int	snd_config_get_real (const snd_config_t *config, double *ptr)
	Returns the value of a real-number configuration node. More...
int	snd_config_get_ireal (const snd_config_t *config, double *ptr)
	Returns the value of a real or integer configuration node. More...
int	snd_config_get_string (const snd_config_t *config, const char **ptr)
	Returns the value of a string configuration node. More...
int	snd_config_get_pointer (const snd_config_t *config, const void **ptr)
	Returns the value of a pointer configuration node. More...
int	snd_config_get_ascii (const snd_config_t *config, char **ascii)
	Returns the value of a configuration node as a string. More...
int	snd_config_test_id (const snd_config_t *config, const char *id)
	Compares the id of a configuration node to a given string. More...
int	snd_config_save (snd_config_t *config, snd_output_t *out)
	Dumps the contents of a configuration node or tree. More...
int	snd_config_search (snd_config_t *config, const char *key, snd_config_t **result)
	Searches for a node in a configuration tree. More...
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. More...
int	snd_config_searchv (snd_config_t *config, snd_config_t **result,...)
	Searches for a node in a configuration tree. More...
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. More...
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. More...
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. More...
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. More...
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. More...
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. More...
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. More...
snd_config_t *	_snd_config_hook_private_data (int card, const char *driver)
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. More...
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). More...
int	snd_config_update (void)
	Updates snd_config by rereading the global configuration files (if needed). More...
int	snd_config_update_ref (snd_config_t **top)
	Updates snd_config and takes its reference. More...
void	snd_config_ref (snd_config_t *cfg)
	Take the reference of the config tree. More...
void	snd_config_unref (snd_config_t *cfg)
	Unreference the config tree. More...
int	snd_config_update_free (snd_config_update_t *update)
	Frees a private update structure. More...
int	snd_config_update_free_global (void)
	Frees the global configuration tree in snd_config. More...
snd_config_iterator_t	snd_config_iterator_first (const snd_config_t *config)
	Returns an iterator pointing to a node's first child. More...
snd_config_iterator_t	snd_config_iterator_next (const snd_config_iterator_t iterator)
	Returns an iterator pointing to the next sibling. More...
snd_config_iterator_t	snd_config_iterator_end (const snd_config_t *config)
	Returns an iterator that ends a node's children list. More...
snd_config_t *	snd_config_iterator_entry (const snd_config_iterator_t iterator)
	Returns the configuration node handle pointed to by an iterator. More...
int	snd_config_copy (snd_config_t **dst, snd_config_t *src)
	Creates a copy of a configuration node. More...
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. More...
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. More...
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. More...
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. More...
size_t	page_size (void)
size_t	page_align (size_t size)
size_t	page_ptr (size_t object_offset, size_t object_size, size_t *offset, size_t *mmap_offset)

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

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_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_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_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);

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