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 a byte order marker (BOM) at the beginning of the file.
Here is a simple configuration file:
# Example config file for Ice Ice.MessageSizeMax = 2048 # Largest message size is 2MB Ice.Trace.Network=3 # Highest level of tracing for network Ice.Trace.Protocol= # Disable protocol tracing
Leading and trailing white space is always ignored for property names (whether the white space is escaped or not), but white space within property values is preserved.
For property values, you can preserve leading and trailing white space by escaping the white space with a backslash. For example:
# White space example My.Prop = a property # Value is "a property" My.Prop = a property # Value is "a property" My.Prop = \ \ a property\ \ # Value is " a property " My.Prop = \ \ a \ \ property\ \ # Value is " a property " My.Prop = a \\ property # Value is "a \ property"
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).
A property that contains the empty string (such as Ice.Trace.Protocol in the preceding example) is indistinguishable from a property that is not mentioned at all. This is because the API for retrieving a property value returns the empty string for non-existent properties.
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
The characters = and # 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:
foo\=bar=1 # Name is "foo=bar", value is "1" foo\#bar = 2 # Name is "foo#bar", value is "2" foo bar =3 # Name is "foo bar", value is "3"
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:
A=1 # Name is "A", value is "1" B= 2 3 4 # Name is "B", value is "2 3 4" C=5=\#6 # 7 # Name is "C", value is "5=#6"
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:
AServer=\\\\server\dir # Value is "\\server\dir" BServer=\\server\\dir # Value is "\server\dir"
The preceding example also illustrates that, if a backslash is not followed by a backslash, #, or =, the backslash and the character following it are both preserved.