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

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. For example:

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:

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:

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 error->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, error->message already contains a filename).

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:

gint
foo_open_file (GError **error)
{
  gint fd;

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

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

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

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:

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

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:

Summary of rules for use of ""

Details

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

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

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

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_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,
                                                         ...);