This page describes the syntax of an Ice configuration file.
On this page:
Configuration File Format
A configuration file contains any number of name-value pairs, with each pair on a separate line. Empty lines and lines consisting entirely of white space characters are ignored. The
# character introduces a comment that extends to the end of the current line.
Configuration files can be ASCII text files or use the UTF-8 character encoding with an optional byte order marker (BOM) at the beginning of the file.
Here is a simple configuration file:
White space within property keys and values is preserved, whether escaped with a backslash or not escaped.
Leading and trailing white space is always ignored for property names (whether the white space is escaped or not), for example:
For property values, you can preserve leading and trailing white space by escaping the white space with a backslash, for example:
This example shows that leading and trailing white space for property values is ignored unless escaped with a backslash whereas, white space that is surrounded by non-white space characters is preserved exactly, whether it is escaped or not. As usual, you can insert a literal backslash into a property value by using a double backslash.
If you set the same property more than once, the last setting prevails and overrides any previous setting. Note that assigning nothing to a property clears that property (that is, sets it to the empty string).
Ice treats properties that contain the empty string (such as
Ice.Trace.Protocol in the preceding example) like a property that is not set at all, and we recommend that your Ice-based applications do the same. With
getPropertyAsListWithDefault, you cannot distinguish between a property that is not set and a property set to the empty string; however,
getPropertyWithDefault allows you to make this distinction, for example:
Property values can include characters from non-English alphabets. The Ice run time expects the configuration file to use UTF-8 encoding for such characters. (With C++, you can specify a string converter when you read the file.)
Special Characters in Configuration Files
# have special meaning in a configuration file:
=marks the end of the property name and the beginning of the property value
#starts a comment that extends to the end of the line
These characters must be escaped when they appear in a property name. Consider the following examples:
In a property value, a
# character must be escaped to prevent it from starting a comment, but an
= character does not require an escape. Consider these examples:
Note that, two successive backslashes in a property value become a single backslash. To get two consecutive backslashes, you must escape each one with another backslash:
The preceding example also illustrates that, if a backslash is not followed by a backslash,
=, the backslash and the character following it are both preserved.