Error Reporting

Error Reporting

Synopsis


#include <glib.h>

                    GError;
GError*             g_error_new                         (GQuark domain,
                                                         gint code,
                                                         const gchar *format,
                                                         ...);
GError*             g_error_new_literal                 (GQuark domain,
                                                         gint code,
                                                         const gchar *message);
GError*             g_error_new_valist                  (GQuark domain,
                                                         gint code,
                                                         const gchar *format,
                                                         va_list args);
void                g_error_free                        (GError *error);
GError*             g_error_copy                        (const GError *error);
gboolean            g_error_matches                     (const GError *error,
                                                         GQuark domain,
                                                         gint code);
void                g_set_error                         (GError **err,
                                                         GQuark domain,
                                                         gint code,
                                                         const gchar *format,
                                                         ...);
void                g_set_error_literal                 (GError **err,
                                                         GQuark domain,
                                                         gint code,
                                                         const gchar *message);
void                g_propagate_error                   (GError **dest,
                                                         GError *src);
void                g_clear_error                       (GError **err);
void                g_prefix_error                      (GError **err,
                                                         const gchar *format,
                                                         ...);
void                g_propagate_prefixed_error          (GError **dest,
                                                         GError *src,
                                                         const gchar *format,
                                                         ...);

Description

Details

GError

typedef struct {
  GQuark       domain;
  gint         code;
  gchar       *message;
} GError;


g_error_new ()

GError*             g_error_new                         (GQuark domain,
                                                         gint code,
                                                         const gchar *format,
                                                         ...);

Creates a new GError with the given domain and code, and a message formatted with format.

domain :

error domain

code :

error code

format :

printf()-style format for error message

... :

parameters for message format

Returns :

a new GError

g_error_new_literal ()

GError*             g_error_new_literal                 (GQuark domain,
                                                         gint code,
                                                         const gchar *message);

Creates a new GError; unlike g_error_new(), message is not a printf()-style format string. Use this function if message contains text you don't have control over, that could include printf() escape sequences.

domain :

error domain

code :

error code

message :

error message

Returns :

a new GError

g_error_new_valist ()

GError*             g_error_new_valist                  (GQuark domain,
                                                         gint code,
                                                         const gchar *format,
                                                         va_list args);

Creates a new GError with the given domain and code, and a message formatted with format.

domain :

error domain

code :

error code

format :

printf()-style format for error message

args :

va_list of parameters for the message format

Returns :

a new GError

Since 2.22


g_error_free ()

void                g_error_free                        (GError *error);

Frees a GError and associated resources.

error :

a GError

g_error_copy ()

GError*             g_error_copy                        (const GError *error);

Makes a copy of error.

error :

a GError

Returns :

a new GError

g_error_matches ()

gboolean            g_error_matches                     (const GError *error,
                                                         GQuark domain,
                                                         gint code);

Returns TRUE if error matches domain and code, FALSE otherwise. In particular, when error is NULL, FALSE will be returned.

error :

a GError or NULL

domain :

an error domain

code :

an error code

Returns :

whether error has domain and code

g_set_error ()

void                g_set_error                         (GError **err,
                                                         GQuark domain,
                                                         gint code,
                                                         const gchar *format,
                                                         ...);

Does nothing if err is NULL; if err is non-NULL, then *err must be NULL. A new GError is created and assigned to *err.

err :

a return location for a GError, or NULL

domain :

error domain

code :

error code

format :

printf()-style format

... :

args for format

g_set_error_literal ()

void                g_set_error_literal                 (GError **err,
                                                         GQuark domain,
                                                         gint code,
                                                         const gchar *message);

Does nothing if err is NULL; if err is non-NULL, then *err must be NULL. A new GError is created and assigned to *err. Unlike g_set_error(), message is not a printf()-style format string. Use this function if message contains text you don't have control over, that could include printf() escape sequences.

err :

a return location for a GError, or NULL

domain :

error domain

code :

error code

message :

error message

Since 2.18


g_propagate_error ()

void                g_propagate_error                   (GError **dest,
                                                         GError *src);

If dest is NULL, free src; otherwise, moves src into *dest. The error variable dest points to must be NULL.

dest :

error return location

src :

error to move into the return location

g_clear_error ()

void                g_clear_error                       (GError **err);

If err is NULL, does nothing. If err is non-NULL, calls g_error_free() on *err and sets *err to NULL.

err :

a GError return location

g_prefix_error ()

void                g_prefix_error                      (GError **err,
                                                         const gchar *format,
                                                         ...);

Formats a string according to format and prefix it to an existing error message. If err is NULL (ie: no error variable) then do nothing.

If *err is NULL (ie: an error variable is present but there is no error condition) then also do nothing. Whether or not it makes sense to take advantage of this feature is up to you.

err :

a return location for a GError, or NULL

format :

printf()-style format string

... :

arguments to format

Since 2.16


g_propagate_prefixed_error ()

void                g_propagate_prefixed_error          (GError **dest,
                                                         GError *src,
                                                         const gchar *format,
                                                         ...);

If dest is NULL, free src; otherwise, moves src into *dest. *dest must be NULL. After the move, add a prefix as with g_prefix_error().

dest :

error return location

src :

error to move into the return location

format :

printf()-style format string

... :

arguments to format

Since 2.16