← Back to branch summary

~n3npq/lsb/t2c-alsa-tests 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html><head>
<meta http-equiv="Content-Type" content="text/html;charset=iso-8859-1"><title>ALSA project - the C library reference: Configuration files</title>

<link href="doxygen.css" rel="stylesheet" type="text/css">
<link href="tabs.css" rel="stylesheet" type="text/css"></head><body>
<!-- Generated by Doxygen 1.5.0 -->
<div class="tabs">
  <ul>
    <li><a href="index.html"><span>Main&nbsp;Page</span></a></li>
    <li><a href="modules.html"><span>Modules</span></a></li>
    <li><a href="annotated.html"><span>Data&nbsp;Structures</span></a></li>
    <li><a href="files.html"><span>Files</span></a></li>
    <li><a href="pages.html"><span>Related&nbsp;Pages</span></a></li>
    <li><a href="examples.html"><span>Examples</span></a></li>
  </ul></div>
<h1><a class="anchor" name="conf">Configuration files</a></h1>Configuration files use a simple format allowing modern data description like nesting and array assignments.<h2><a class="anchor" name="conf_whitespace">
Whitespace</a></h2>
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>
</p><div class="fragment"><pre class="fragment">  a 1 b 2<br></pre></div><p>
and</p><p>
</p><div class="fragment"><pre class="fragment">  a 1 <br>     b 2<br></pre></div><p>
are lexically equivalent and parse identically to give the four tokens:</p><p>
</p><div class="fragment"><pre class="fragment">a<br>1<br>b<br>2<br></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><p>
</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" name="conf_linesplicing">
Line continuation with</a></h2>
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>
</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" name="conf_comments">
Comments</a></h2>
A single-line comment begins with the character #. The comment can start at any position, and extends to the end of the line.<p>
</p><div class="fragment"><pre class="fragment">  a 1  # <span class="keyword">this</span> is a comment<br></pre></div><h2><a class="anchor" name="conf_include">
Including configuration files</a></h2>
To include another configuration file, write the file name in angle brackets. The prefix <code>confdir:</code> will reference the global configuration directory.<p>
</p><div class="fragment"><pre class="fragment">&lt;/etc/alsa1.conf&gt;<br>&lt;confdir:pcm/surround.conf&gt;<br></pre></div><h2><a class="anchor" name="conf_punctuators">
Punctuators</a></h2>
The configuration punctuators (also known as separators) are:<p>
</p><div class="fragment"><pre class="fragment">  {} [] , ; = . ' <span class="stringliteral">" new-line form-feed carriage-return whitespace</span>
</pre></div><h3><a class="anchor" name="conf_braces">
Braces</a></h3>
Opening and closing braces { } indicate the start and end of a compound statement:<p>
</p><div class="fragment"><pre class="fragment">a {<br>  b 1<br>}<br></pre></div><h3><a class="anchor" name="conf_brackets">
Brackets</a></h3>
Opening and closing brackets indicate a single array definition. The identifiers are automatically generated starting with zero.<p>
</p><div class="fragment"><pre class="fragment">a [<br>  <span class="stringliteral">"first"</span>
  <span class="stringliteral">"second"</span>
]
</pre></div><p>
The above code is equal to</p><p>
</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" name="conf_comma_semicolon">
Comma and semicolon</a></h3>
The comma (,) or semicolon (;) can separate value assignments. It is
not strictly required to use these separators because whitespace
suffices to separate tokens.<p>
</p><div class="fragment"><pre class="fragment">a 1;<br>b 1,<br></pre></div><h3><a class="anchor" name="conf_equal">
Equal sign</a></h3>
The equal sign (=) can separate variable declarations from initialization lists:<p>
</p><div class="fragment"><pre class="fragment">a=1<br>b=2<br></pre></div><p>
Using equal signs is not required because whitespace suffices to separate tokens.</p><h2><a class="anchor" name="conf_assigns">
Assignments</a></h2>
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.<h3><a class="anchor" name="conf_single">
Single assignments</a></h3>
<div class="fragment"><pre class="fragment">a 1     # is equal to<br>a=1     # is equal to<br>a=1;    # is equal to<br>a 1,<br></pre></div><h3><a class="anchor" name="conf_compound">
Compound assignments (definitions using braces)</a></h3>
<div class="fragment"><pre class="fragment">a {<br>  b = 1<br>}<br>a={<br>  b 1,<br>}<br></pre></div><h2><a class="anchor" name="conf_compound1">
Compound assignments (one key definitions)</a></h2>
<div class="fragment"><pre class="fragment">a.b 1<br>a.b=1<br></pre></div><h3><a class="anchor" name="conf_array">
Array assignments (definitions using brackets)</a></h3>
<div class="fragment"><pre class="fragment">a [<br>  <span class="stringliteral">"first"</span>
  <span class="stringliteral">"second"</span>
]
</pre></div><h3><a class="anchor" name="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" name="conf_mode">
Operation modes for parsing nodes</a></h2>
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>
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><p>
</p><div class="fragment"><pre class="fragment">defaults.pcm.!device 1<br></pre></div><h2><a class="anchor" name="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>&lt;filename&gt;<br><br><span class="preprocessor"># Simple assignment</span>
<span class="preprocessor"></span>name [=] value [,|;]<br><br><span class="preprocessor"># Compound assignment (first style)</span>
<span class="preprocessor"></span>name [=] {<br>        name1 [=] value [,|;]<br>        ...<br>}<br><br><span class="preprocessor"># Compound assignment (second style)</span>
<span class="preprocessor"></span>name.name1 [=] value [,|;]<br><br><span class="preprocessor"># Array assignment (first style)</span>
<span class="preprocessor"></span>name [<br>        value0 [,|;]<br>        value1 [,|;]<br>        ...<br>]<br><br><span class="preprocessor"># Array assignment (second style)</span>
<span class="preprocessor"></span>name.0 [=] value0 [,|;]<br>name.1 [=] value1 [,|;]<br></pre></div><h2><a class="anchor" name="conf_syntax_ref">
References</a></h2>
<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> <hr size="1"><address style=""><small>Generated on Wed Sep 9 14:37:08 2009 for ALSA project - the C library reference by&nbsp;
<a href="http://www.doxygen.org/index.html">
<img src="doxygen.png" alt="doxygen" align="middle" border="0"></a> 1.5.0 </small></address>
</body></html>