06/04/2008 11:35 PM
Tip #2: understanding io-media configuration files
Even though io-media's default configuration parameters are often sufficient, knowing what they are and how they can be
changed may be useful. Some of the default values are the result of an attempt to find a reasonable balance between
conflicting requirements, such as memory versus speed, and of course someone who knows the exact design and requirements
of the particular target system has a good chance of coming up with an even better balance.
This article (let's admit it: it's more than a mere "tip"!) is just a general introduction that does not try to describe
all the details of all the settings. Instead, its aim is to explain enough of the syntax and architecture to help you
read io-media configuration files, make guesses about the purpose of the various settings you find there, and ask
relevant questions in forums such as this.
Chapter 1: "It's a file, even when it isn't."
At startup, io-media always parses a configuration file. This is true even when there is no configuration file. When
there's no real file, io-media parses the contents of a file that was generated at build time, then turned into a C
character array, and compiled into the executable. The actual file may not exist any more, but what io-media parses is
a literal copy of its contents, including newline characters and tabs and comments and so on; only a very tiny portion
of io-media knows that the lines of text are coming from a string built into the executable rather than from a real file
in the filesystem.
The advantage of this is that you can ask io-media for a copy of those contents. If you run io-media with the -C option
, it will write its default configuration to standard output and then exit. That's a great way to produce the initial
version of a configuration file that you will then modify according to your needs - it's better than copying it from the
documentation, because it's guaranteed to work even if the io-media you're running is not exactly the version that you
have documentation for, or if there is a new setting that was added just before the release, and the only place we
managed to mention it in the documentation is in a release note.
Once you have generated a real configuration file, you can ask io-media to use it instead of its built-in default:
# io-media-generic -C > /etc/iomedia.cfg -- this creates the file
# io-media-generic -c /etc/iomedia.cfg -- and this starts io-media for real
Chapter 2: "It's more like XML than it looks."
The configuration file has a hierarchical structure modelled after XML, with "elements" that have "attributes" and other
elements as "children". Just like in XML, the order of attributes of an element doesn't matter but the order of its
children might. But unlike in XML, there is no such thing as "character data" between "tags"; there's not really such a
thing as "tags", either - as you will easily notice, the syntax is completely different from XML.
First of all, the syntax is very line-oriented. Instead of tags in angle brackets, it uses curly braces to delimit
elements, and allows child elements and attributes to be mixed together in any order. (XML wants attributes to be
inside the opening tag but children outside of it - but here we don't have "tags".) Each attribute must occupy its own
line. Comments are allowed too, but they look like shell comments - they start at a # character and extend to the end
of the line. Comments are *not* recognized in a line that defines an attribute - all the characters between the = sign
and the end of line, less any leading and trailing whitespace, are considered to be the value of the attribute. The
only exception is that if the first of those characters is a single or double quote, then the last must be the same kind
of a quote, and both are stripped away. You can use quotes for aesthetic purposes, or to define an attribute whose
value is a zero-length string or starts or ends with a whitespace or a quote...
View Full Message