Jump to ID:

Project Home




Project Info
Forum Topic - Tip #2: understanding io-media configuration files: (1 Item)
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