GError — error reporting.


enum                GConfError;
GError *            gconf_error_new                     (GConfError en,
                                                         const gchar *format,
GQuark              gconf_error_quark                   (void);
void                gconf_set_error                     (GError **err,
                                                         GConfError en,
                                                         const gchar *format,
GError *            gconf_compose_errors                (GError *err1,
                                                         GError *err2);


The GError object is used to report errors that occur in GConf library routines. All functions that report errors work the same way:

  • The last argument to the function is a GError**, a pointer to a location where a GError* can be placed.

  • This last argument may be NULL, in which case no error will be returned.

  • If non-NULL, the argument should be the address of a GError* variable, which should be initialized to NULL.

  • If an error occurs, a GError will be allocated and placed in the return location; the caller must free the GError with g_error_free(). If no error occurs, the return location will be left untouched. That is, the test error != NULL should always be a reliable indicator of whether the operation failed.

It's also common that the return value of a function indicates whether or not an error occurred. Typically, TRUE is returned on success. In some cases, a NULL return value indicates failure. Either way, if the return value indicates failure and you passed a non-NULL value for the last argument to the function, a GError will be returned. If the return value indicates success, then a GError will never be returned. These relationships are guaranteed; that is, you can reliably use the return value to decide whether a GError was placed in the return location. If a function does not indicate success/failure by return value, you must check whether the GError is NULL to detect errors.

Here's a short error handling example:

  GError* err = NULL;
  if (!gconf_init(&err))
      fprintf(stderr, _("Failed to init GConf: %s\n"), err->message);
      err = NULL;


enum GConfError

typedef enum {
  GCONF_ERROR_FAILED = 1,        /* Something didn't work, don't know why, probably unrecoverable
                                    so there's no point having a more specific errno */

  GCONF_ERROR_NO_SERVER = 2,     /* Server can't be launched/contacted */
  GCONF_ERROR_NO_PERMISSION = 3, /* don't have permission for that */
  GCONF_ERROR_BAD_ADDRESS = 4,   /* Address couldn't be resolved */
  GCONF_ERROR_BAD_KEY = 5,       /* directory or key isn't valid (contains bad
                                    characters, or malformed slash arrangement) */
  GCONF_ERROR_PARSE_ERROR = 6,   /* Syntax error when parsing */
  GCONF_ERROR_CORRUPT = 7,       /* Fatal error parsing/loading information inside the backend */
  GCONF_ERROR_TYPE_MISMATCH = 8, /* Type requested doesn't match type found */
  GCONF_ERROR_IS_DIR = 9,        /* Requested key operation on a dir */
  GCONF_ERROR_IS_KEY = 10,       /* Requested dir operation on a key */
  GCONF_ERROR_OVERRIDDEN = 11,   /* Read-only source at front of path has set the value */
  GCONF_ERROR_OAF_ERROR = 12,    /* liboaf error */
  GCONF_ERROR_LOCAL_ENGINE = 13, /* Tried to use remote operations on a local engine */
  GCONF_ERROR_LOCK_FAILED = 14,  /* Failed to get a lockfile */
  GCONF_ERROR_NO_WRITABLE_DATABASE = 15, /* nowhere to write a value */
  GCONF_ERROR_IN_SHUTDOWN = 16   /* server is shutting down */
} GConfError;

The GConfError enumeration allows client applications to differentiate between different kinds of error. You may wish to take specific actions depending on the error type.


indicates that no error occurred, won't be returned in a GError.


indicates failure, but no more specific GConfError applied.


indicates that the GConf server couldn't be contacted, probably a CORBA problem.


indicates that permission to access some resource was denied.


indicates that a configuration source address was syntactically invalid or impossible to resolve.


indicates that a key was malformed.


indicates that some parsing was done (perhaps in a backend) and it failed.


indicates that some part of the database is corrupt.


indicates that a specific type was required, and another type was found.


indicates that an operation only applicable to keys was performed on a directory.


indicates that an operation only applicable to directories was performed on a key.


indicates that the administrator has imposed a mandatory value, and it could not be changed.






gconf_error_new ()

GError *            gconf_error_new                     (GConfError en,
                                                         const gchar *format,

Creates a new error. Normally the GConf library does this, but you might find a reason to do it as well. en is the error number, format is a printf()-style format for the error message, and the variable argument list is the same as in printf().

en :

the error number.

format :

printf()-style format for error description.

Varargs :

arguments required by the format.

Returns :

newly-allocated GError.

gconf_error_quark ()

GQuark              gconf_error_quark                   (void);

Converts the string 'gconf-error-quark' to a GQuark and returns the value.

Returns :

the GQuark representing the string.

gconf_set_error ()

void                gconf_set_error                     (GError **err,
                                                         GConfError en,
                                                         const gchar *format,

Internal function.

gconf_compose_errors ()

GError *            gconf_compose_errors                (GError *err1,
                                                         GError *err2);

Internal function.