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 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:

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
            xml:readonly:/etc/gconf.xml.mandatory
            include "$(HOME)/.gconf.path"
            xml:readonly:/etc/gconf.xml.defaults
            # imaginary, no LDAP backend exists right now
            ldap::/foo/bar/whatever/ldap/address
          

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.