Terms and Concepts

This section introduces the basic GConf structure and terminology.


The GConf namespace is almost exactly like the UNIX filesystem; that is, a tree structured directory hierarchy. Each name is either a "file" (a configuration key storing a value) or a "directory" (a list of child configuration key names). A name is specified with a slash-separated path. A full path is referred to as a key. Characters in a path should be alphanumeric or underscore. Path components may not start with a period. You should follow the conventions outlined in GConf Conventions when choosing what names to use for your keys.

GConf Data Types

GConf can only store a small, fixed set of data types. This keeps the database implementation simple and efficient. GConf should not be used to store data files or any other large amount of information; it is designed for simple configuration data only. There are any number of better solutions available for storing documents and other large data chunks. You might want to store a filename, URL, or Bonobo moniker in GConf pointing to a larger piece of data, if you need the GConf notification facilities.

Here are the GConf datatypes:


Integer values are simple C-style integers, that is, they are limited to 32 bits and can be positive or negative.


String values can contain any text you like, but not binary data (such as the NULL character). GConf should handle any string the C library string functions can handle.


Float values are floating point numbers. Given differences between machine architectures and C libraries, there is no guaranteed degree of precision, other than "a reasonable degree."


Boolean values are true or false.


Schemas store a GConfSchema data type, which contains meta-information about a key, such as documentation and its type.


List values store a group of values. All values in a list must have the same primitive type. Heterogeneous lists are not allowed. Lists of lists and lists of pairs are not allowed.


Pairs store two primitive values. The two values do not necessarily have the same type. Pairs can not contain pairs or lists, only primitive types.

Configuration Sources

Users can specify configuration sources which will be used by the gconfd per-user configuration server. gconfd loads the file /etc/gconf/2/path (or ${sysconfdir}/gconf/${version}/path) on startup; this file contains a list of configuration source addresses. A source address is similar to a URL; it contains a "protocol" name (in this case, the name of the backend to use), followed by a colon, standard flags separated by commands, another colon, and then backend-specific information. For example, the address xml:readonly:/home/hp/.gconf.xml refers to an XML backend file tree rooted at /home/hp/.gconf.xml that should be "mounted readonly" so that no data is written to it.

/etc/gconf/2/path stores a list of addresses, which form a configuration source path. When looking up a value, GConf will begin with the first source in the path, and continue checking each source until the value is found or there are no more sources. When setting a value, GConf will use the first writable source. Administrators can impose mandatory settings on their users by placing only read-only configuration sources in the path, or by placing a read-only source at the front of the path and setting specific values in that source. Administrators can provide default values by placing a systemwide source at the end of the configuration source path.

The source configuration file can contain "include" statements and some magic variables; you can use this to include a .gconf.path file from the user's home directory. Variables are placed in $(). Two variables are built-in to GConf: $(HOME) is the user's home directory, and $(USER) is the username. You can also access any environment variable by prepending ENV_ to the variable name. For example, $(ENV_FOO) will be replaced by the FOO environment variable.

So once everything is working a /etc/gconf/path file might look like this:

            # GConf configuration path file with an include statement
            include "$(HOME)/.gconf.path"
            # imaginary, no LDAP backend exists right now

Note that particular backend modules may have their own special configuration. For example, you may need to configure the details of an LDAP backend.


A schema describes some configuration key. Its primary purpose is to provide documentation about the key to system administrators manipulating the GConf database. Secondarily, schemas contain a good default value for the key; GConf will automatically return this value when a key is unset. Schemas also include the name of the application that created a key (useful when trying to clean old junk out of the database, for example).

Schemas are normally installed from special schema description files; the gconftool program knows how to read these and install the schemas into the GConf database. Normally, schemas are not installed by application code, though the interface for doing so is a public part of the GConf API.