<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html><head><meta http-equiv="Content-Type" content="text/html;charset=iso-8859-1">
<title>Configuration files</title>
<link href="doxygen.css" rel="stylesheet" type="text/css">
</head><body>
<!-- Generated by Doxygen 1.2.18 -->
<center>
<a class="qindex" href="index.html">Main Page</a> <a class="qindex" href="modules.html">Modules</a> <a class="qindex" href="annotated.html">Data Structures</a> <a class="qindex" href="files.html">File List</a> <a class="qindex" href="functions.html">Data Fields</a> <a class="qindex" href="globals.html">Globals</a> <a class="qindex" href="pages.html">Related Pages</a> <a class="qindex" href="examples.html">Examples</a> </center>
<hr><h1><a name="conf">Configuration files</a>
</h1>
<p>
<p>
Configuration files use a simple format allowing modern data description like nesting and array assignments.
<p>
<h2><a name="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> a 1 b 2
</pre></div>
<p>
and
<p>
<div class="fragment"><pre> a 1
b 2
</pre></div>
<p>
are lexically equivalent and parse identically to give the four tokens:
<p>
<div class="fragment"><pre>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> 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 name="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><span class="stringliteral">"John \</span>
<span class="stringliteral">Smith"</span>
</pre></div>
<p>
is parsed as "John Smith".
<p>
<h2><a name="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> a 1 # <span class="keyword">this</span> is a comment
</pre></div>
<p>
<h2><a name="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></etc/alsa1.conf>
<confdir:pcm/surround.conf>
</pre></div>
<p>
<h2><a name="conf_punctuators">Punctuators</a>
</h2>
<p>
The configuration punctuators (also known as separators) are:
<p>
<div class="fragment"><pre> {} [] , ; = . ' <span class="stringliteral">" new-line form-feed carriage-return whitespace</span>
</pre></div>
<p>
<h3><a name="conf_braces">Braces</a>
</h3>
<p>
Opening and closing braces { } indicate the start and end of a compound statement:
<p>
<div class="fragment"><pre>a {
b 1
}
</pre></div>
<p>
<h3><a name="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>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>a.0 <span class="stringliteral">"first"</span>
a.1 <span class="stringliteral">"second"</span>
</pre></div>
<p>
<h3><a name="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>a 1;
b 1,
</pre></div>
<p>
<h3><a name="conf_equal">Equal sign</a>
</h3>
<p>
The equal sign (=) can separate variable declarations from initialization lists:
<p>
<div class="fragment"><pre>a=1
b=2
</pre></div>
<p>
Using equal signs is not required because whitespace suffices to separate tokens.
<p>
<h2><a name="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 name="conf_single">Single assignments</a>
</h3>
<p>
<div class="fragment"><pre>a 1 # is equal to
a=1 # is equal to
a=1; # is equal to
a 1,
</pre></div>
<p>
<h3><a name="conf_compound">Compound assignments (definitions using braces)</a>
</h3>
<p>
<div class="fragment"><pre>a {
b = 1
}
a={
b 1,
}
</pre></div>
<p>
<h2><a name="conf_compound1">Compound assignments (one key definitions)</a>
</h2>
<p>
<div class="fragment"><pre>a.b 1
a.b=1
</pre></div>
<p>
<h3><a name="conf_array">Array assignments (definitions using brackets)</a>
</h3>
<p>
<div class="fragment"><pre>a [
<span class="stringliteral">"first"</span>
<span class="stringliteral">"second"</span>
]
</pre></div>
<p>
<h3><a name="conf_array1">Array assignments (one key definitions)</a>
</h3>
<p>
<div class="fragment"><pre>a.0 <span class="stringliteral">"first"</span>
a.1 <span class="stringliteral">"second"</span>
</pre></div>
<p>
<h2><a name="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>
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>
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>
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>defaults.pcm.!device 1
</pre></div>
<p>
<h2><a name="conf_syntax_summary">Syntax summary</a>
</h2>
<p>
<div class="fragment"><pre><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>
<p>
<h2><a name="conf_syntax_ref">References</a>
</h2>
<p>
<a href="confarg.html#confarg">Runtime arguments in configuration files</a> <a href="conffunc.html#conffunc">Runtime functions in configuration files</a> <a href="confhooks.html#confhooks">Hooks in configuration files</a>
<p>
<hr><address style="align: right;"><small>Generated on Wed Apr 2 16:06:36 2003 for ALSA project - the C library reference by
<a href="http://www.doxygen.org/index.html">
<img src="doxygen.png" alt="doxygen" align="middle" border=0
width=110 height=53></a>1.2.18 </small></address>
</body>
</html>
distrib
>
Mandriva
>
9.1
>
ppc
>
media
>
updates
>
by-pkgid
>
18785641029f14f23cccc82925607ace
>
files
>
14
