Top |
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_propagate_prefixed_error () |
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).
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 |
gint foo_open_file (GError **error) { gint fd; int saved_errno; 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 {
in C++. It does not mean to leave errors unhandled; it means
to handle them by doing nothing.sub_function_that_can_fail()
; } catch (...) {}
Error domains and codes are conventionally named as follows:
-
The error domain is called <NAMESPACE>_<MODULE>_ERROR, for example
G_SPAWN_ERROR
orG_THREAD_ERROR
:1 2 3 4 5 6 7
#define G_SPAWN_ERROR g_spawn_error_quark () GQuark g_spawn_error_quark (void) { return g_quark_from_static_string ("g-spawn-error-quark"); }
The quark function for the error domain is called <namespace>_<module>_error_quark, for example
g_spawn_error_quark()
org_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
orG_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."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 withg_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 andFALSE
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 asg_key_file_has_key()
that are deprecated because of this. IfFALSE
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 ag_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 whetherNULL
is a valid return value in non-error cases; ifNULL
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 aNULL
error (e.g.g_return_if_fail (error == NULL || *error == NULL);
).
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
.
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.
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 |
Since: 2.22
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.
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 |
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.
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
.
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 |
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()
.
Parameters
dest |
error return location |
|
src |
error to move into the return location |
|
format |
printf()-style format string |
|
... |
arguments to |
Since: 2.16
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 |
error domain, e.g. G_FILE_ERROR |
|
gint |
error code, e.g. |
|
gchar * |
human-readable informative error message |