ALSA project - the C library reference
Macros | Functions | Variables
conf.c File Reference

Configuration helper functions. More...

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_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_tsnd_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 (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_tsnd_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]asciiA string containing a configuration node type.
[out]typeThe 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]rootHandle to the root configuration node.
[in]configHandle to the configuration node for this hook.
[out]dstThe function puts the handle to the configuration node loaded from the file(s) at the address specified by dst.
[in]private_dataHandle 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]rootHandle to the root configuration node.
[in]configHandle to the configuration node for this hook.
[out]dstThe function puts the handle to the configuration node loaded from the file(s) at the address specified by dst.
[in]private_dataHandle 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]configHandle to the root of the configuration (sub)tree to search.
[in]baseSearch key base, or NULL.
[in]keySearch key suffix.
[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 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]configHandle to the root of the configuration (sub)tree to search.
[in]baseSearch key base, or NULL.
[in]keySearch key suffix.
[out]resultThe 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]configHandle to the root of the configuration (sub)tree to search.
[in]keySearch key: one or more node keys, separated with dots.
[out]resultThe 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]rootHandle to the root configuration node containing alias definitions.
[in]configHandle to the root of the configuration (sub)tree to search.
[in]keySearch key: one or more node keys, 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 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]rootHandle to the root configuration node containing alias definitions.
[in,out]configHandle to the root of the configuration (sub)tree to search.
[in]keySearch key: one or more node keys, separated with dots.
[out]resultThe 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]rootHandle to the root configuration node containing alias definitions.
[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 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]rootHandle to the root configuration node containing alias definitions.
[in,out]configHandle to the root of the configuration (sub)tree to search.
[out]resultThe 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_substitute()

int snd_config_substitute ( snd_config_t dst,
snd_config_t src 
)

Substitutes one configuration node to another.

Parameters
dstHandle to the destination node.
srcHandle 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.