<!-- This comment will put IE 6, 7 and 8 in quirks mode -->
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<title>ALSA project - the C library reference: Configuration files</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javaScript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css"/>
</head>
<body onload='searchBox.OnSelectItem(0);'>
<!-- Generated by Doxygen 1.6.3 -->
<script type="text/javascript"><!--
var searchBox = new SearchBox("searchBox", "search",false,'Search');
--></script>
<div class="navigation" id="top">
<div class="tabs">
<ul>
<li><a href="index.html"><span>Main Page</span></a></li>
<li class="current"><a href="pages.html"><span>Related Pages</span></a></li>
<li><a href="modules.html"><span>Modules</span></a></li>
<li><a href="annotated.html"><span>Data Structures</span></a></li>
<li><a href="files.html"><span>Files</span></a></li>
<li><a href="examples.html"><span>Examples</span></a></li>
<li>
<div id="MSearchBox" class="MSearchBoxInactive">
<img id="MSearchSelect" src="search/search.png"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
alt=""/>
<input type="text" id="MSearchField" value="Search" accesskey="S"
onfocus="searchBox.OnSearchFieldFocus(true)"
onblur="searchBox.OnSearchFieldFocus(false)"
onkeyup="searchBox.OnSearchFieldChange(event)"/>
<a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a>
</div>
</li>
</ul>
</div>
</div>
<div class="contents">
<h1><a class="anchor" id="conf">Configuration files </a></h1><p>Configuration files use a simple format allowing modern data description like nesting and array assignments.</p>
<h2><a class="anchor" id="conf_whitespace">
Whitespace</a></h2>
<p>Whitespace is the collective name given to spaces (blanks), horizontal and vertical tabs, newline characters, and comments. Whitespace can indicate where configuration tokens start and end, but beyond this function, any surplus whitespace is discarded. For example, the two sequences</p>
<div class="fragment"><pre class="fragment"> a 1 b 2
</pre></div><p>and</p>
<div class="fragment"><pre class="fragment"> a 1
b 2
</pre></div><p>are lexically equivalent and parse identically to give the four tokens:</p>
<div class="fragment"><pre class="fragment">a
1
b
2
</pre></div><p>The ASCII characters representing whitespace can occur within literal strings, in which case they are protected from the normal parsing process (they remain as part of the string). For example:</p>
<div class="fragment"><pre class="fragment"> name <span class="stringliteral">"John Smith"</span>
</pre></div><p>parses to two tokens, including the single literal-string token "John
Smith".</p>
<h2><a class="anchor" id="conf_linesplicing">
Line continuation with</a></h2>
<p>A special case occurs if a newline character in a string is preceded by a backslash (\). The backslash and the new line are both discarded, allowing two physical lines of text to be treated as one unit.</p>
<div class="fragment"><pre class="fragment"><span class="stringliteral">"John \</span>
<span class="stringliteral">Smith"</span>
</pre></div><p>is parsed as "John Smith".</p>
<h2><a class="anchor" id="conf_comments">
Comments</a></h2>
<p>A single-line comment begins with the character #. The comment can start at any position, and extends to the end of the line.</p>
<div class="fragment"><pre class="fragment"> a 1 # <span class="keyword">this</span> is a comment
</pre></div><h2><a class="anchor" id="conf_include">
Including configuration files</a></h2>
<p>To include another configuration file, write the file name in angle brackets. The prefix <code>confdir:</code> will reference the global configuration directory.</p>
<div class="fragment"><pre class="fragment"></etc/alsa1.conf>
<confdir:pcm/surround.conf>
</pre></div><h2><a class="anchor" id="conf_punctuators">
Punctuators</a></h2>
<p>The configuration punctuators (also known as separators) are:</p>
<div class="fragment"><pre class="fragment"> {} [] , ; = . <span class="stringliteral">' " new-line form-feed carriage-return whitespace</span>
</pre></div><h3><a class="anchor" id="conf_braces">
Braces</a></h3>
<p>Opening and closing braces { } indicate the start and end of a compound statement:</p>
<div class="fragment"><pre class="fragment">a {
b 1
}
</pre></div><h3><a class="anchor" id="conf_brackets">
Brackets</a></h3>
<p>Opening and closing brackets indicate a single array definition. The identifiers are automatically generated starting with zero.</p>
<div class="fragment"><pre class="fragment">a [
<span class="stringliteral">"first"</span>
<span class="stringliteral">"second"</span>
]
</pre></div><p>The above code is equal to</p>
<div class="fragment"><pre class="fragment">a.0 <span class="stringliteral">"first"</span>
a.1 <span class="stringliteral">"second"</span>
</pre></div><h3><a class="anchor" id="conf_comma_semicolon">
Comma and semicolon</a></h3>
<p>The comma (,) or semicolon (;) can separate value assignments. It is not strictly required to use these separators because whitespace suffices to separate tokens.</p>
<div class="fragment"><pre class="fragment">a 1;
b 1,
</pre></div><h3><a class="anchor" id="conf_equal">
Equal sign</a></h3>
<p>The equal sign (=) can separate variable declarations from initialization lists:</p>
<div class="fragment"><pre class="fragment">a=1
b=2
</pre></div><p>Using equal signs is not required because whitespace suffices to separate tokens.</p>
<h2><a class="anchor" id="conf_assigns">
Assignments</a></h2>
<p>The configuration file defines id (key) and value pairs. The id (key) can be composed from ASCII digits, characters from a to z and A to Z, and the underscore (_). The value can be either a string, an integer, a real number, or a compound statement.</p>
<h3><a class="anchor" id="conf_single">
Single assignments</a></h3>
<div class="fragment"><pre class="fragment">a 1 # is equal to
a=1 # is equal to
a=1; # is equal to
a 1,
</pre></div><h3><a class="anchor" id="conf_compound">
Compound assignments (definitions using braces)</a></h3>
<div class="fragment"><pre class="fragment">a {
b = 1
}
a={
b 1,
}
</pre></div><h2><a class="anchor" id="conf_compound1">
Compound assignments (one key definitions)</a></h2>
<div class="fragment"><pre class="fragment">a.b 1
a.b=1
</pre></div><h3><a class="anchor" id="conf_array">
Array assignments (definitions using brackets)</a></h3>
<div class="fragment"><pre class="fragment">a [
<span class="stringliteral">"first"</span>
<span class="stringliteral">"second"</span>
]
</pre></div><h3><a class="anchor" id="conf_array1">
Array assignments (one key definitions)</a></h3>
<div class="fragment"><pre class="fragment">a.0 <span class="stringliteral">"first"</span>
a.1 <span class="stringliteral">"second"</span>
</pre></div><h2><a class="anchor" id="conf_mode">
Operation modes for parsing nodes</a></h2>
<p>By default, the node operation mode is 'merge+create', i.e., if a configuration node is not present a new one is created, otherwise the latest assignment is merged (if possible - type checking). The 'merge+create' operation mode is specified with the prefix character plus (+).</p>
<p>The operation mode 'merge' merges the node with the old one (which must exist). Type checking is done, so strings cannot be assigned to integers and so on. This mode is specified with the prefix character minus (-).</p>
<p>The operation mode 'do not override' ignores a new configuration node if a configuration node with the same name exists. This mode is specified with the prefix character question mark (?).</p>
<p>The operation mode 'override' always overrides the old configuration node with new contents. This mode is specified with the prefix character exclamation mark (!).</p>
<div class="fragment"><pre class="fragment">defaults.pcm.!device 1
</pre></div><h2><a class="anchor" id="conf_syntax_summary">
Syntax summary</a></h2>
<div class="fragment"><pre class="fragment"><span class="preprocessor"># Configuration file syntax</span>
<span class="preprocessor"></span>
<span class="preprocessor"># Include a new configuration file</span>
<span class="preprocessor"></span><filename>
<span class="preprocessor"># Simple assignment</span>
<span class="preprocessor"></span>name [=] value [,|;]
<span class="preprocessor"># Compound assignment (first style)</span>
<span class="preprocessor"></span>name [=] {
name1 [=] value [,|;]
...
}
<span class="preprocessor"># Compound assignment (second style)</span>
<span class="preprocessor"></span>name.name1 [=] value [,|;]
<span class="preprocessor"># Array assignment (first style)</span>
<span class="preprocessor"></span>name [
value0 [,|;]
value1 [,|;]
...
]
<span class="preprocessor"># Array assignment (second style)</span>
<span class="preprocessor"></span>name.0 [=] value0 [,|;]
name.1 [=] value1 [,|;]
</pre></div><h2><a class="anchor" id="conf_syntax_ref">
References</a></h2>
<p><a class="el" href="confarg.html">Runtime arguments in configuration files</a> <a class="el" href="conffunc.html">Runtime functions in configuration files</a> <a class="el" href="confhooks.html">Hooks in configuration files</a> </p>
</div>
<!--- window showing the filter options -->
<div id="MSearchSelectWindow"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
onkeydown="return searchBox.OnSearchSelectKey(event)">
<a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(0)"><span class="SelectionMark"> </span>All</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(1)"><span class="SelectionMark"> </span>Data Structures</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(2)"><span class="SelectionMark"> </span>Files</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(3)"><span class="SelectionMark"> </span>Functions</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(4)"><span class="SelectionMark"> </span>Variables</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(5)"><span class="SelectionMark"> </span>Typedefs</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(6)"><span class="SelectionMark"> </span>Enumerations</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(7)"><span class="SelectionMark"> </span>Enumerator</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(8)"><span class="SelectionMark"> </span>Defines</a></div>
<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="" frameborder="0"
name="MSearchResults" id="MSearchResults">
</iframe>
</div>
<hr class="footer"/><address style="text-align: right;"><small>Generated on Sat Nov 20 07:42:24 2010 for ALSA project - the C library reference by
<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.6.3 </small></address>
</body>
</html>
