EVOLUTION-MANAGER
Edit File: conf.html
<!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"/> <meta http-equiv="X-UA-Compatible" content="IE=9"/> <meta name="generator" content="Doxygen 1.8.5"/> <title>ALSA project - the C library reference: Configuration files</title> <link href="tabs.css" rel="stylesheet" type="text/css"/> <script type="text/javascript" src="jquery.js"></script> <script type="text/javascript" src="dynsections.js"></script> <link href="search/search.css" rel="stylesheet" type="text/css"/> <script type="text/javascript" src="search/search.js"></script> <script type="text/javascript"> $(document).ready(function() { searchBox.OnSelectItem(0); }); </script> <link href="doxygen.css" rel="stylesheet" type="text/css" /> </head> <body> <div id="top"><!-- do not remove this div, it is closed by doxygen! --> <div id="titlearea"> <table cellspacing="0" cellpadding="0"> <tbody> <tr style="height: 56px;"> <td style="padding-left: 0.5em;"> <div id="projectname">ALSA project - the C library reference </div> </td> </tr> </tbody> </table> </div> <!-- end header part --> <!-- Generated by Doxygen 1.8.5 --> <script type="text/javascript"> var searchBox = new SearchBox("searchBox", "search",false,'Search'); </script> <div id="navrow1" class="tabs"> <ul class="tablist"> <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"> <span class="left"> <img id="MSearchSelect" src="search/mag_sel.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)"/> </span><span class="right"> <a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a> </span> </div> </li> </ul> </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>Macros</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(9)"><span class="SelectionMark"> </span>Groups</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(10)"><span class="SelectionMark"> </span>Pages</a></div> <!-- iframe showing the search results (closed by default) --> <div id="MSearchResultsWindow"> <iframe src="javascript:void(0)" frameborder="0" name="MSearchResults" id="MSearchResults"> </iframe> </div> </div><!-- top --> <div class="header"> <div class="headertitle"> <div class="title">Configuration files </div> </div> </div><!--header--> <div class="contents"> <div class="textblock"><p>Configuration files use a simple format allowing modern data description like nesting and array assignments.</p> <h1><a class="anchor" id="conf_whitespace"></a> Whitespace</h1> <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"><div class="line">a 1 b 2</div> </div><!-- fragment --><p>and</p> <div class="fragment"><div class="line">a 1 </div> <div class="line"> b 2</div> </div><!-- fragment --><p>are lexically equivalent and parse identically to give the four tokens:</p> <div class="fragment"><div class="line">a</div> <div class="line">1</div> <div class="line">b</div> <div class="line">2</div> </div><!-- fragment --><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"><div class="line">name <span class="stringliteral">"John Smith"</span></div> </div><!-- fragment --><p>parses to two tokens, including the single literal-string token "John Smith".</p> <h1><a class="anchor" id="conf_linesplicing"></a> Line continuation with</h1> <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"><div class="line"><span class="stringliteral">"John \</span></div> <div class="line"><span class="stringliteral">Smith"</span></div> </div><!-- fragment --><p>is parsed as "John Smith".</p> <h1><a class="anchor" id="conf_comments"></a> Comments</h1> <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"><div class="line">a 1 # <span class="keyword">this</span> is a comment</div> </div><!-- fragment --><h1><a class="anchor" id="conf_include"></a> Including configuration files</h1> <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"><div class="line"></etc/alsa1.conf></div> <div class="line"><confdir:pcm/surround.conf></div> </div><!-- fragment --><h1><a class="anchor" id="conf_punctuators"></a> Punctuators</h1> <p>The configuration punctuators (also known as separators) are:</p> <div class="fragment"><div class="line">{} [] , ; = . <span class="stringliteral">' " new-line form-feed carriage-return whitespace</span></div> </div><!-- fragment --><h2><a class="anchor" id="conf_braces"></a> Braces</h2> <p>Opening and closing braces { } indicate the start and end of a compound statement:</p> <div class="fragment"><div class="line">a {</div> <div class="line"> b 1</div> <div class="line">}</div> </div><!-- fragment --><h2><a class="anchor" id="conf_brackets"></a> Brackets</h2> <p>Opening and closing brackets indicate a single array definition. The identifiers are automatically generated starting with zero.</p> <div class="fragment"><div class="line">a [</div> <div class="line"> <span class="stringliteral">"first"</span></div> <div class="line"> <span class="stringliteral">"second"</span></div> <div class="line">]</div> </div><!-- fragment --><p>The above code is equal to</p> <div class="fragment"><div class="line">a.0 <span class="stringliteral">"first"</span></div> <div class="line">a.1 <span class="stringliteral">"second"</span></div> </div><!-- fragment --><h2><a class="anchor" id="conf_comma_semicolon"></a> Comma and semicolon</h2> <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"><div class="line">a 1;</div> <div class="line">b 1,</div> </div><!-- fragment --><h2><a class="anchor" id="conf_equal"></a> Equal sign</h2> <p>The equal sign (=) can separate variable declarations from initialization lists:</p> <div class="fragment"><div class="line">a=1</div> <div class="line">b=2</div> </div><!-- fragment --><p>Using equal signs is not required because whitespace suffices to separate tokens.</p> <h1><a class="anchor" id="conf_assigns"></a> Assignments</h1> <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> <h2><a class="anchor" id="conf_single"></a> Single assignments</h2> <div class="fragment"><div class="line">a 1 # is equal to</div> <div class="line">a=1 # is equal to</div> <div class="line">a=1; # is equal to</div> <div class="line">a 1,</div> </div><!-- fragment --><h2><a class="anchor" id="conf_compound"></a> Compound assignments (definitions using braces)</h2> <div class="fragment"><div class="line">a {</div> <div class="line"> b = 1</div> <div class="line">}</div> <div class="line">a={</div> <div class="line"> b 1,</div> <div class="line">}</div> </div><!-- fragment --><h1><a class="anchor" id="conf_compound1"></a> Compound assignments (one key definitions)</h1> <div class="fragment"><div class="line">a.b 1</div> <div class="line">a.b=1</div> </div><!-- fragment --><h2><a class="anchor" id="conf_array"></a> Array assignments (definitions using brackets)</h2> <div class="fragment"><div class="line">a [</div> <div class="line"> <span class="stringliteral">"first"</span></div> <div class="line"> <span class="stringliteral">"second"</span></div> <div class="line">]</div> </div><!-- fragment --><h2><a class="anchor" id="conf_array1"></a> Array assignments (one key definitions)</h2> <div class="fragment"><div class="line">a.0 <span class="stringliteral">"first"</span></div> <div class="line">a.1 <span class="stringliteral">"second"</span></div> </div><!-- fragment --><h1><a class="anchor" id="conf_mode"></a> Operation modes for parsing nodes</h1> <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"><div class="line">defaults.pcm.!device 1</div> </div><!-- fragment --><h1><a class="anchor" id="conf_syntax_summary"></a> Syntax summary</h1> <div class="fragment"><div class="line"><span class="preprocessor"># Configuration file syntax</span></div> <div class="line"><span class="preprocessor"></span></div> <div class="line"><span class="preprocessor"># Include a new configuration file</span></div> <div class="line"><span class="preprocessor"></span><filename></div> <div class="line"></div> <div class="line"><span class="preprocessor"># Simple assignment</span></div> <div class="line"><span class="preprocessor"></span>name [=] value [,|;]</div> <div class="line"></div> <div class="line"><span class="preprocessor"># Compound assignment (first style)</span></div> <div class="line"><span class="preprocessor"></span>name [=] {</div> <div class="line"> name1 [=] value [,|;]</div> <div class="line"> ...</div> <div class="line">}</div> <div class="line"></div> <div class="line"><span class="preprocessor"># Compound assignment (second style)</span></div> <div class="line"><span class="preprocessor"></span>name.name1 [=] value [,|;]</div> <div class="line"></div> <div class="line"><span class="preprocessor"># Array assignment (first style)</span></div> <div class="line"><span class="preprocessor"></span>name [</div> <div class="line"> value0 [,|;]</div> <div class="line"> value1 [,|;]</div> <div class="line"> ...</div> <div class="line">]</div> <div class="line"></div> <div class="line"><span class="preprocessor"># Array assignment (second style)</span></div> <div class="line"><span class="preprocessor"></span>name.0 [=] value0 [,|;]</div> <div class="line">name.1 [=] value1 [,|;]</div> </div><!-- fragment --><h1><a class="anchor" id="conf_syntax_ref"></a> References</h1> <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></div><!-- contents --> <!-- start footer part --> <hr class="footer"/><address class="footer"><small> Generated by  <a href="http://www.doxygen.org/index.html"> <img class="footer" src="doxygen.png" alt="doxygen"/> </a> 1.8.5 </small></address> </body> </html>