GError: GConf Reference Manual

GError

GError — error reporting.

Functions

GError *	gconf_error_new ()
GQuark	gconf_error_quark ()
void	gconf_set_error ()
GError *	gconf_compose_errors ()

Types and Values

enum	GConfError

Description

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);
      g_error_free(err);
      err = NULL;
    }

Functions

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().

Parameters

en	the error number.
format	printf()-style format for error description.

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.

Types and Values

enum 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.

Members

GCONF_ERROR_SUCCESS	indicates that no error occurred, won't be returned in a GError.
GCONF_ERROR_FAILED	indicates failure, but no more specific GConfError applied.
GCONF_ERROR_NO_SERVER	indicates that the GConf server couldn't be contacted, probably a CORBA problem.
GCONF_ERROR_NO_PERMISSION	indicates that permission to access some resource was denied.
GCONF_ERROR_BAD_ADDRESS	indicates that a configuration source address was syntactically invalid or impossible to resolve.
GCONF_ERROR_BAD_KEY	indicates that a key was malformed.
GCONF_ERROR_PARSE_ERROR	indicates that some parsing was done (perhaps in a backend) and it failed.
GCONF_ERROR_CORRUPT	indicates that some part of the database is corrupt.
GCONF_ERROR_TYPE_MISMATCH	indicates that a specific type was required, and another type was found.
GCONF_ERROR_IS_DIR	indicates that an operation only applicable to keys was performed on a directory.
GCONF_ERROR_IS_KEY	indicates that an operation only applicable to directories was performed on a key.
GCONF_ERROR_OVERRIDDEN	indicates that the administrator has imposed a mandatory value, and it could not be changed.
GCONF_ERROR_OAF_ERROR
GCONF_ERROR_LOCAL_ENGINE
GCONF_ERROR_LOCK_FAILED
GCONF_ERROR_NO_WRITABLE_DATABASE
GCONF_ERROR_IN_SHUTDOWN