26.3 Configuration Files

Properties are usually set in a configuration file. A configuration file contains a 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.

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 indicate leading and trailing whitespace 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 names 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 to retrieve the property value returns the empty string for non-existent properties (see page 673).

Ice reads the contents of a configuration file when you create a communicator. By default, the name of the configuration file is determined by reading the contents of the ICE_CONFIG environment variable. You can set this variable to a relative or absolute pathname of the configuration file, for example:

$ export ICE_CONFIG=/opt/Ice/default_config
$ ./server

This causes the server to read its property settings from the configuration file in /opt/Ice/default_config.

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. See page 675, Section 28.3, and Section 28.23.)

26.3.1 Special Characters

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, to 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 \, #, or =, the backslash and the character following it are both preserved.