# /builddir/build/BUILD/alsa-lib-1.1.0/src/conf.c File Reference

Configuration helper functions. More...

## Defines

#define | ALSA_CONFIG_PATH_VAR "ALSA_CONFIG_PATH"
#define | ALSA_CONFIG_PATH_DEFAULT ALSA_CONFIG_DIR "/alsa.conf"

## Functions

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

## Detailed Description

Configuration helper functions.

Author:
  Abramo Bagnara <abramo@alsa-project.org>
  Jaroslav Kysela <perex@perex.cz>

Date:
  2000-2001

Tree based, full nesting configuration functions.

See the Configuration files page for more details.

## Define Documentation

#define ALSA_CONFIG_PATH_DEFAULT ALSA_CONFIG_DIR "/alsa.conf"

The name of the default files used by snd_config_update.

#define ALSA_CONFIG_PATH_VAR "ALSA_CONFIG_PATH"

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

## Function Documentation

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.

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.

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.

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

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.

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.

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.

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.

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.

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.

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.

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 are appended to the destination compound node.

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.

All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines