Error Reporting

Error Reporting — a system for reporting errors

Functions

GError * g_error_new ()
GError * g_error_new_literal ()
GError * g_error_new_valist ()
void g_error_free ()
GError * g_error_copy ()
gboolean g_error_matches ()
void g_set_error ()
void g_set_error_literal ()
void g_propagate_error ()
void g_clear_error ()
void g_prefix_error ()
void g_prefix_error_literal ()
void g_propagate_prefixed_error ()
void (*GErrorInitFunc) ()
void (*GErrorCopyFunc) ()
void (*GErrorClearFunc) ()
#define G_DEFINE_EXTENDED_ERROR()
GQuark g_error_domain_register_static ()
GQuark g_error_domain_register ()

Types and Values

struct GError

Includes

#include <glib.h>

Description

GLib provides a standard method of reporting errors from a called function to the calling code. (This is the same problem solved by exceptions in other languages.) It's important to understand that this method is both a data type (the GError struct) and a set of rules. If you use GError incorrectly, then your code will not properly interoperate with other code that uses GError, and users of your API will probably get confused. In most cases, using GError is preferred over numeric error codes, but there are situations where numeric error codes are useful for performance.

First and foremost: GError should only be used to report recoverable runtime errors, never to report programming errors. If the programmer has screwed up, then you should use g_warning(), g_return_if_fail(), g_assert(), g_error(), or some similar facility. (Incidentally, remember that the g_error() function should only be used for programming errors, it should not be used to print any error reportable via GError.)

Examples of recoverable runtime errors are "file not found" or "failed to parse input." Examples of programming errors are "NULL passed to strcmp()" or "attempted to free the same pointer twice." These two kinds of errors are fundamentally different: runtime errors should be handled or reported to the user, programming errors should be eliminated by fixing the bug in the program. This is why most functions in GLib and GTK+ do not use the GError facility.

Functions that can fail take a return location for a GError as their last argument. On error, a new GError instance will be allocated and returned to the caller via this argument. For example:

1
2
3
4
 
gboolean g_file_get_contents (const gchar  *filename,
                              gchar       **contents,
                              gsize        *length,
                              GError      **error);

If you pass a non-NULL value for the error argument, it should point to a location where an error can be placed. For example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
 
gchar *contents;
GError *err = NULL;

g_file_get_contents ("foo.txt", &contents, NULL, &err);
g_assert ((contents == NULL && err != NULL) || (contents != NULL && err == NULL));
if (err != NULL)
  {
    // Report error to user, and free error
    g_assert (contents == NULL);
    fprintf (stderr, "Unable to read file: %s\n", err->message);
    g_error_free (err);
  }
else
  {
    // Use file contents
    g_assert (contents != NULL);
  }

Note that err != NULL in this example is a reliable indicator of whether g_file_get_contents() failed. Additionally, g_file_get_contents() returns a boolean which indicates whether it was successful.

Because g_file_get_contents() returns FALSE on failure, if you are only interested in whether it failed and don't need to display an error message, you can pass NULL for the error argument:

1
2
3
4
5
6
 
if (g_file_get_contents ("foo.txt", &contents, NULL, NULL)) // ignore errors
  // no error occurred 
  ;
else
  // error
  ;

The GError object contains three fields: domain indicates the module the error-reporting function is located in, code indicates the specific error that occurred, and message is a user-readable error message with as many details as possible. Several functions are provided to deal with an error received from a called function: g_error_matches() returns TRUE if the error matches a given domain and code, g_propagate_error() copies an error into an error location (so the calling function will receive it), and g_clear_error() clears an error location by freeing the error and resetting the location to NULL. To display an error to the user, simply display the message , perhaps along with additional context known only to the calling function (the file being opened, or whatever - though in the g_file_get_contents() case, the message already contains a filename).

Since error messages may be displayed to the user, they need to be valid UTF-8 (all GTK widgets expect text to be UTF-8). Keep this in mind in particular when formatting error messages with filenames, which are in the 'filename encoding', and need to be turned into UTF-8 using g_filename_to_utf8(), g_filename_display_name() or g_utf8_make_valid().

Note, however, that many error messages are too technical to display to the user in an application, so prefer to use g_error_matches() to categorize errors from called functions, and build an appropriate error message for the context within your application. Error messages from a GError are more appropriate to be printed in system logs or on the command line. They are typically translated.

When implementing a function that can report errors, the basic tool is g_set_error(). Typically, if a fatal error occurs you want to g_set_error(), then return immediately. g_set_error() does nothing if the error location passed to it is NULL. Here's an example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
 
gint
foo_open_file (GError **error)
{
  gint fd;
  int saved_errno;

  g_return_val_if_fail (error == NULL || *error == NULL, -1);

  fd = open ("file.txt", O_RDONLY);
  saved_errno = errno;

  if (fd < 0)
    {
      g_set_error (error,
                   FOO_ERROR,                 // error domain
                   FOO_ERROR_BLAH,            // error code
                   "Failed to open file: %s", // error message format string
                   g_strerror (saved_errno));
      return -1;
    }
  else
    return fd;
}

Things are somewhat more complicated if you yourself call another function that can report a GError. If the sub-function indicates fatal errors in some way other than reporting a GError, such as by returning TRUE on success, you can simply do the following:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
 
gboolean
my_function_that_can_fail (GError **err)
{
  g_return_val_if_fail (err == NULL || *err == NULL, FALSE);

  if (!sub_function_that_can_fail (err))
    {
      // assert that error was set by the sub-function
      g_assert (err == NULL || *err != NULL);
      return FALSE;
    }

  // otherwise continue, no error occurred
  g_assert (err == NULL || *err == NULL);
}

If the sub-function does not indicate errors other than by reporting a GError (or if its return value does not reliably indicate errors) you need to create a temporary GError since the passed-in one may be NULL. g_propagate_error() is intended for use in this case.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
 
gboolean
my_function_that_can_fail (GError **err)
{
  GError *tmp_error;

  g_return_val_if_fail (err == NULL || *err == NULL, FALSE);

  tmp_error = NULL;
  sub_function_that_can_fail (&tmp_error);

  if (tmp_error != NULL)
    {
      // store tmp_error in err, if err != NULL,
      // otherwise call g_error_free() on tmp_error
      g_propagate_error (err, tmp_error);
      return FALSE;
    }

  // otherwise continue, no error occurred
}

Error pileups are always a bug. For example, this code is incorrect:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
 
gboolean
my_function_that_can_fail (GError **err)
{
  GError *tmp_error;

  g_return_val_if_fail (err == NULL || *err == NULL, FALSE);

  tmp_error = NULL;
  sub_function_that_can_fail (&tmp_error);
  other_function_that_can_fail (&tmp_error);

  if (tmp_error != NULL)
    {
      g_propagate_error (err, tmp_error);
      return FALSE;
    }
}

tmp_error should be checked immediately after sub_function_that_can_fail(), and either cleared or propagated upward. The rule is: after each error, you must either handle the error, or return it to the calling function.

Note that passing NULL for the error location is the equivalent of handling an error by always doing nothing about it. So the following code is fine, assuming errors in sub_function_that_can_fail() are not fatal to my_function_that_can_fail():

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
 
gboolean
my_function_that_can_fail (GError **err)
{
  GError *tmp_error;

  g_return_val_if_fail (err == NULL || *err == NULL, FALSE);

  sub_function_that_can_fail (NULL); // ignore errors

  tmp_error = NULL;
  other_function_that_can_fail (&tmp_error);

  if (tmp_error != NULL)
    {
      g_propagate_error (err, tmp_error);
      return FALSE;
    }
}

Note that passing NULL for the error location ignores errors; it's equivalent to try { sub_function_that_can_fail(); } catch (...) {} in C++. It does not mean to leave errors unhandled; it means to handle them by doing nothing.

Error domains and codes are conventionally named as follows:

  • The error domain is called <NAMESPACE>_<MODULE>_ERROR, for example G_SPAWN_ERROR or G_THREAD_ERROR:

    1
2
3
    		 
    #define G_SPAWN_ERROR g_spawn_error_quark ()

G_DEFINE_QUARK (g-spawn-error-quark, g_spawn_error)

  • The quark function for the error domain is called <namespace>_<module>_error_quark, for example g_spawn_error_quark() or g_thread_error_quark().

  • The error codes are in an enumeration called <Namespace><Module>Error; for example, GThreadError or GSpawnError.

  • Members of the error code enumeration are called <NAMESPACE>_<MODULE>_ERROR_<CODE>, for example G_SPAWN_ERROR_FORK or G_THREAD_ERROR_AGAIN.

  • If there's a "generic" or "unknown" error code for unrecoverable errors it doesn't make sense to distinguish with specific codes, it should be called <NAMESPACE>_<MODULE>_ERROR_FAILED, for example G_SPAWN_ERROR_FAILED. In the case of error code enumerations that may be extended in future releases, you should generally not handle this error code explicitly, but should instead treat any unrecognized error code as equivalent to FAILED.

Comparison of GError and traditional error handling

GError has several advantages over traditional numeric error codes: importantly, tools like gobject-introspection understand GErrors and convert them to exceptions in bindings; the message includes more information than just a code; and use of a domain helps prevent misinterpretation of error codes.

GError has disadvantages though: it requires a memory allocation, and formatting the error message string has a performance overhead. This makes it unsuitable for use in retry loops where errors are a common case, rather than being unusual. For example, using G_IO_ERROR_WOULD_BLOCK means hitting these overheads in the normal control flow. String formatting overhead can be eliminated by using g_set_error_literal() in some cases.

These performance issues can be compounded if a function wraps the GErrors returned by the functions it calls: this multiplies the number of allocations and string formatting operations. This can be partially mitigated by using g_prefix_error().

Rules for use of GError

Summary of rules for use of GError:

  • Do not report programming errors via GError.

  • The last argument of a function that returns an error should be a location where a GError can be placed (i.e. GError **error). If GError is used with varargs, the GError** should be the last argument before the ....

  • The caller may pass NULL for the GError** if they are not interested in details of the exact error that occurred.

  • If NULL is passed for the GError** argument, then errors should not be returned to the caller, but your function should still abort and return if an error occurs. That is, control flow should not be affected by whether the caller wants to get a GError.

  • If a GError is reported, then your function by definition had a fatal failure and did not complete whatever it was supposed to do. If the failure was not fatal, then you handled it and you should not report it. If it was fatal, then you must report it and discontinue whatever you were doing immediately.

  • If a GError is reported, out parameters are not guaranteed to be set to any defined value.

  • A GError* must be initialized to NULL before passing its address to a function that can report errors.

  • GError structs must not be stack-allocated.

  • "Piling up" errors is always a bug. That is, if you assign a new GError to a GError* that is non-NULL, thus overwriting the previous error, it indicates that you should have aborted the operation instead of continuing. If you were able to continue, you should have cleared the previous error with g_clear_error(). g_set_error() will complain if you pile up errors.

  • By convention, if you return a boolean value indicating success then TRUE means success and FALSE means failure. Avoid creating functions which have a boolean return value and a GError parameter, but where the boolean does something other than signal whether the GError is set. Among other problems, it requires C callers to allocate a temporary error. Instead, provide a gboolean * out parameter. There are functions in GLib itself such as g_key_file_has_key() that are hard to use because of this. If FALSE is returned, the error must be set to a non-NULL value. One exception to this is that in situations that are already considered to be undefined behaviour (such as when a g_return_val_if_fail() check fails), the error need not be set. Instead of checking separately whether the error is set, callers should ensure that they do not provoke undefined behaviour, then assume that the error will be set on failure.

  • A NULL return value is also frequently used to mean that an error occurred. You should make clear in your documentation whether NULL is a valid return value in non-error cases; if NULL is a valid value, then users must check whether an error was returned to see if the function succeeded.

  • When implementing a function that can report errors, you may want to add a check at the top of your function that the error return location is either NULL or contains a NULL error (e.g. g_return_if_fail (error == NULL || *error == NULL);).

Extended GError Domains

Since GLib 2.68 it is possible to extend the GError type. This is done with the G_DEFINE_EXTENDED_ERROR() macro. To create an extended GError type do something like this in the header file:

1
2
3
4
5
6
7
8
9
10
 
typedef enum
{
  MY_ERROR_BAD_REQUEST,
} MyError;
#define MY_ERROR (my_error_quark ())
GQuark my_error_quark (void);
int
my_error_get_parse_error_id (GError *error);
const char *
my_error_get_bad_request_details (GError *error);

and in implementation:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
 
typedef struct
{
  int parse_error_id;
  char *bad_request_details;
} MyErrorPrivate;

static void
my_error_private_init (MyErrorPrivate *priv)
{
  priv->parse_error_id = -1;
  // No need to set priv->bad_request_details to NULL,
  // the struct is initialized with zeros.
}

static void
my_error_private_copy (const MyErrorPrivate *src_priv, MyErrorPrivate *dest_priv)
{
  dest_priv->parse_error_id = src_priv->parse_error_id;
  dest_priv->bad_request_details = g_strdup (src_priv->bad_request_details);
}

static void
my_error_private_clear (MyErrorPrivate *priv)
{
  g_free (priv->bad_request_details);
}

// This defines the my_error_get_private and my_error_quark functions.
G_DEFINE_EXTENDED_ERROR (MyError, my_error)

int
my_error_get_parse_error_id (GError *error)
{
  MyErrorPrivate *priv = my_error_get_private (error);
  g_return_val_if_fail (priv != NULL, -1);
  return priv->parse_error_id;
}

const char *
my_error_get_bad_request_details (GError *error)
{
  MyErrorPrivate *priv = my_error_get_private (error);
  g_return_val_if_fail (priv != NULL, NULL);
  g_return_val_if_fail (error->code != MY_ERROR_BAD_REQUEST, NULL);
  return priv->bad_request_details;
}

static void
my_error_set_bad_request (GError     **error,
                          const char  *reason,
                          int          error_id,
                          const char  *details)
{
  MyErrorPrivate *priv;
  g_set_error (error, MY_ERROR, MY_ERROR_BAD_REQUEST, "Invalid request: %s", reason);
  if (error != NULL && *error != NULL)
    {
      priv = my_error_get_private (error);
      g_return_val_if_fail (priv != NULL, NULL);
      priv->parse_error_id = error_id;
      priv->bad_request_details = g_strdup (details);
    }
}

An example of use of the error could be:

1
2
3
4
5
6
7
8
9
10
11
12
13
 
gboolean
send_request (GBytes *request, GError **error)
{
  ParseFailedStatus *failure = validate_request (request);
  if (failure != NULL)
    {
      my_error_set_bad_request (error, failure->reason, failure->error_id, failure->details);
      parse_failed_status_free (failure);
      return FALSE;
    }

  return send_one (request, error);
}

Please note that if you are a library author and your library exposes an existing error domain, then you can't make this error domain an extended one without breaking ABI. This is because earlier it was possible to create an error with this error domain on the stack and then copy it with g_error_copy(). If the new version of your library makes the error domain an extended one, then g_error_copy() called by code that allocated the error on the stack will try to copy more data than it used to, which will lead to undefined behavior. You must not stack-allocate errors with an extended error domain, and it is bad practice to stack-allocate any other GErrors.

Extended error domains in unloadable plugins/modules are not supported.

Functions

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 .

Parameters

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.

Parameters

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 .

Parameters

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.

Parameters

error

a GError

  

g_error_copy ()

GError *
g_error_copy (const GError *error);

Makes a copy of error .

Parameters

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.

If domain contains a FAILED (or otherwise generic) error code, you should generally not check for it explicitly, but should instead treat any not-explicitly-recognized error code as being equivalent to the FAILED code. This way, if the domain is extended in the future to provide a more specific error code for a certain case, your code will still work.

Parameters

error

a GError.

[nullable]

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 .

Parameters

err

a return location for a GError.

[out callee-allocates][optional]

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.

Parameters

err

a return location for a GError.

[out callee-allocates][optional]

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.

src must be non-NULL.

Note that src is no longer valid after this call. If you want to keep using the same GError*, you need to set it to NULL after calling this function on it.

Parameters

dest

error return location.

[out callee-allocates][optional][nullable]

src

error to move into the return location.

[transfer full]

g_clear_error ()

void
g_clear_error (GError **err);

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

Parameters

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.

Parameters

err

a return location for a GError.

[inout][optional][nullable]

format

printf()-style format string

  

...

arguments to format

 

Since: 2.16

g_prefix_error_literal ()

void
g_prefix_error_literal (GError **err,
                        const gchar *prefix);

Prefixes prefix to an existing error message. If err or *err is NULL (i.e.: no error variable) then do nothing.

Parameters

err

a return location for a GError, or NULL.

[allow-none]

prefix

string to prefix err with

  

Since: 2.70

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

Parameters

dest

error return location

  

src

error to move into the return location

  

format

printf()-style format string

  

...

arguments to format

 

Since: 2.16

GErrorInitFunc ()

void
(*GErrorInitFunc) (GError *error);

Specifies the type of function which is called just after an extended error instance is created and its fields filled. It should only initialize the fields in the private data, which can be received with the generated *_get_private() function.

Normally, it is better to use G_DEFINE_EXTENDED_ERROR(), as it already takes care of getting the private data from error .

Parameters

error

extended error

  

Since: 2.68

GErrorCopyFunc ()

void
(*GErrorCopyFunc) (const GError *src_error,
                   GError *dest_error);

Specifies the type of function which is called when an extended error instance is copied. It is passed the pointer to the destination error and source error, and should copy only the fields of the private data from src_error to dest_error .

Normally, it is better to use G_DEFINE_EXTENDED_ERROR(), as it already takes care of getting the private data from src_error and dest_error .

Parameters

src_error

source extended error

  

dest_error

destination extended error

  

Since: 2.68

GErrorClearFunc ()

void
(*GErrorClearFunc) (GError *error);

Specifies the type of function which is called when an extended error instance is freed. It is passed the error pointer about to be freed, and should free the error's private data fields.

Normally, it is better to use G_DEFINE_EXTENDED_ERROR(), as it already takes care of getting the private data from error .

Parameters

error

extended error to clear

  

Since: 2.68

G_DEFINE_EXTENDED_ERROR()

#define             G_DEFINE_EXTENDED_ERROR(ErrorType, error_type)

A convenience macro which defines two functions. First, returning the GQuark for the extended error type ErrorType ; it is called error_type_quark(). Second, returning the private data from a passed GError; it is called error_type_get_private().

For this macro to work, a type named ErrorTypePrivate should be defined, error_type_private_init(), error_type_private_copy() and error_type_private_clear() functions need to be either declared or defined. The functions should be similar to GErrorInitFunc, GErrorCopyFunc and GErrorClearFunc, respectively, but they should receive the private data type instead of GError.

See Extended GError Domains for an example.

Parameters

ErrorType

name to return a GQuark for

  

error_type

prefix for the function name

  

Since: 2.68

g_error_domain_register_static ()

GQuark
g_error_domain_register_static (const char *error_type_name,
                                gsize error_type_private_size,
                                GErrorInitFunc error_type_init,
                                GErrorCopyFunc error_type_copy,
                                GErrorClearFunc error_type_clear);

This function registers an extended GError domain.

error_type_name should not be freed. error_type_private_size must be greater than 0.

error_type_init receives an initialized GError and should then initialize the private data.

error_type_copy is a function that receives both original and a copy GError and should copy the fields of the private error data. The standard GError fields are already handled.

error_type_clear receives the pointer to the error, and it should free the fields of the private error data. It should not free the struct itself though.

Normally, it is better to use G_DEFINE_EXTENDED_ERROR(), as it already takes care of passing valid information to this function.

Parameters

error_type_name

static string to create a GQuark from

  

error_type_private_size

size of the private error data in bytes

  

error_type_init

function initializing fields of the private error data

  

error_type_copy

function copying fields of the private error data

  

error_type_clear

function freeing fields of the private error data

  

Returns

GQuark representing the error domain

Since: 2.68

g_error_domain_register ()

GQuark
g_error_domain_register (const char *error_type_name,
                         gsize error_type_private_size,
                         GErrorInitFunc error_type_init,
                         GErrorCopyFunc error_type_copy,
                         GErrorClearFunc error_type_clear);

This function registers an extended GError domain. error_type_name will be duplicated. Otherwise does the same as g_error_domain_register_static().

Parameters

error_type_name

string to create a GQuark from

  

error_type_private_size

size of the private error data in bytes

  

error_type_init

function initializing fields of the private error data

  

error_type_copy

function copying fields of the private error data

  

error_type_clear

function freeing fields of the private error data

  

Returns

GQuark representing the error domain

Since: 2.68

Types and Values

struct GError

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

The GError structure contains information about an error that has occurred.

Members

GQuark domain;

error domain, e.g. G_FILE_ERROR

  

gint code;

error code, e.g. G_FILE_ERROR_NOENT

  

gchar *message;

human-readable informative error message

  
Generated by GTK-Doc V1.33.1