1 <!-- ##### SECTION Title ##### -->
4 <!-- ##### SECTION Short_Description ##### -->
5 a system for reporting errors.
7 <!-- ##### SECTION Long_Description ##### -->
10 GLib provides a standard method of reporting errors from a called function to
11 the calling code. (This is the same problem solved by exceptions in other
12 languages.) It's important to understand that this method is both a
13 <emphasis>data type</emphasis> (the #GError object) and a <emphasis>set of
14 rules.</emphasis> If you use #GError incorrectly, then your code will not
15 properly interoperate with other code that uses #GError, and users of your API
16 will probably get confused.
20 First and foremost: <emphasis>#GError should only be used to report
21 recoverable runtime errors, never to report programming errors.</emphasis> If
22 the programmer has screwed up, then you should use g_warning(),
23 g_return_if_fail(), g_assert(), g_error(), or some similar facility.
24 (Incidentally, remember that the g_error() function should
25 <emphasis>only</emphasis> be used for programming errors, it should not be used
26 to print any error reportable via #GError.)
30 Examples of recoverable runtime errors are "file not found" or "failed to parse
31 input." Examples of programming errors are "NULL passed to strcmp()" or
32 "attempted to free the same pointer twice." These two kinds of errors are
33 fundamentally different: runtime errors should be handled or reported to the
34 user, programming errors should be eliminated by fixing the bug in the program.
35 This is why most functions in GLib and GTK+ do not use the #GError facility.
39 Functions that can fail take a return location for a #GError as their last argument.
41 <informalexample><programlisting>
42 gchar* g_file_get_contents (const gchar *filename, GError **error);
43 </programlisting></informalexample>
44 If you pass a non-%NULL value for the <literal>error</literal> argument, it should
45 point to a location where an error can be placed. For example:
46 <informalexample><programlisting>
49 contents = g_file_get_contents ("foo.txt", &err);
50 g_assert ((contents == NULL && err != NULL) || (contents != NULL && err == NULL));
53 /* Report error to user, and free error */
54 g_assert (contents == NULL);
55 fprintf (stderr, "Unable to read file: %s\n", err->message);
60 /* Use file contents */
61 g_assert (contents != NULL);
63 </programlisting></informalexample>
64 Note that <literal>err != NULL</literal> in this example is a
65 <emphasis>reliable</emphasis> indicator of whether
66 g_file_get_contents() failed. Also, g_file_get_contents() uses the
67 convention that a %NULL return value means an error occurred (but not
68 all functions use this convention).
72 Because g_file_get_contents() returns %NULL on failure, if you are only
73 interested in whether it failed and don't need to display an error message, you
74 can pass %NULL for the <literal>error</literal> argument:
75 <informalexample><programlisting>
76 contents = g_file_get_contents ("foo.txt", NULL); /* ignore errors */
78 /* no error occurred */ ;
81 </programlisting></informalexample>
85 The #GError object contains three fields: <literal>domain</literal> indicates
86 the module the error-reporting function is located in, <literal>code</literal>
87 indicates the specific error that occurred, and <literal>message</literal> is a
88 user-readable error message with as many details as possible. Several functions
89 are provided to deal with an error received from a called function:
90 g_error_matches() returns %TRUE if the error matches a given domain and code,
91 g_propagate_error() copies an error into an error location (so the calling
92 function will receive it), and g_clear_error() clears an error location by
93 freeing the error and resetting the location to %NULL. To display an error to the
94 user, simply display <literal>error->message</literal>, perhaps along with
95 additional context known only to the calling function (the file being opened, or
96 whatever -- though in the g_file_get_contents() case,
97 <literal>error->message</literal> already contains a filename).
101 When implementing a function that can report errors, the basic tool is
102 g_set_error(). Typically, if a fatal error occurs you want to g_set_error(),
103 then return immediately. g_set_error() does nothing if the error location passed
104 to it is %NULL. Here's an example:
105 <informalexample><programlisting>
107 foo_open_file (GError **error)
111 fd = open ("file.txt", O_RDONLY);
116 FOO_ERROR, /* error domain */
117 FOO_ERROR_BLAH, /* error code */
118 "Failed to open file: %s", /* error message format string */
125 </programlisting></informalexample>
129 Things are somewhat more complicated if you yourself call another function that
130 can report a #GError. If the sub-function indicates fatal errors in some way
131 other than reporting a #GError, such as by returning %TRUE on success, you can
132 simply do the following:
133 <informalexample><programlisting>
135 my_function_that_can_fail (GError **err)
137 g_return_val_if_fail (err == NULL || *err == NULL, FALSE);
139 if (!sub_function_that_can_fail (err))
141 /* assert that error was set by the sub-function */
142 g_assert (err == NULL || *err != NULL);
146 /* otherwise continue, no error occurred */
147 g_assert (err == NULL || *err == NULL);
149 </programlisting></informalexample>
153 If the sub-function does not indicate errors other than by reporting a #GError,
154 you need to create a temporary #GError since the passed-in one may be %NULL.
155 g_propagate_error() is intended for use in this case.
156 <informalexample><programlisting>
158 my_function_that_can_fail (GError **err)
162 g_return_val_if_fail (err == NULL || *err == NULL, FALSE);
165 sub_function_that_can_fail (&tmp_error);
167 if (tmp_error != NULL)
169 /* store tmp_error in err, if err != NULL,
170 * otherwise call g_error_free(<!-- -->) on tmp_error
172 g_propagate_error (err, tmp_error);
176 /* otherwise continue, no error occurred */
178 </programlisting></informalexample>
182 Error pileups are always a bug. For example, this code is incorrect:
183 <informalexample><programlisting>
185 my_function_that_can_fail (GError **err)
189 g_return_val_if_fail (err == NULL || *err == NULL, FALSE);
192 sub_function_that_can_fail (&tmp_error);
193 other_function_that_can_fail (&tmp_error);
195 if (tmp_error != NULL)
197 g_propagate_error (err, tmp_error);
201 </programlisting></informalexample>
202 <literal>tmp_error</literal> should be checked immediately after
203 <function>sub_function_that_can_fail()</function>, and either cleared or propagated upward. The rule
204 is: <emphasis>after each error, you must either handle the error, or return it to the
205 calling function</emphasis>. Note that passing %NULL for the error location is the
206 equivalent of handling an error by always doing nothing about it. So the
207 following code is fine, assuming errors in <function>sub_function_that_can_fail()</function> are not
208 fatal to <function>my_function_that_can_fail()</function>:
209 <informalexample><programlisting>
211 my_function_that_can_fail (GError **err)
215 g_return_val_if_fail (err == NULL || *err == NULL, FALSE);
217 sub_function_that_can_fail (NULL); /* ignore errors */
220 other_function_that_can_fail (&tmp_error);
222 if (tmp_error != NULL)
224 g_propagate_error (err, tmp_error);
228 </programlisting></informalexample>
232 Note that passing %NULL for the error location <emphasis>ignores</emphasis>
233 errors; it's equivalent to <literal>try { sub_function_that_can_fail (); } catch
234 (...) {}</literal> in C++. It does <emphasis>not</emphasis> mean to leave errors
235 unhandled; it means to handle them by doing nothing.
239 Error domains and codes are conventionally named as follows:
243 The error domain is called
244 <literal><NAMESPACE>_<MODULE>_ERROR</literal>, for example
245 %G_EXEC_ERROR or %G_THREAD_ERROR.
250 The error codes are in an enumeration called
251 <literal><Namespace>_<Module>_Error</literal>; for example,
252 #GThreadError or #GSpawnError.
257 Members of the error code enumeration are called <literal><NAMESPACE>_<MODULE>_ERROR_<CODE></literal>, for example %G_SPAWN_ERROR_FORK or %G_THREAD_ERROR_AGAIN.
262 If there's a "generic" or "unknown" error code for unrecoverable errors it
263 doesn't make sense to distinguish with specific codes, it should be called
264 <literal><NAMESPACE>_<MODULE>_ERROR_FAILED</literal>, for
265 example %G_SPAWN_ERROR_FAILED or %G_THREAD_ERROR_FAILED.
272 Summary of rules for use of #GError:
276 Do not report programming errors via #GError.
282 The last argument of a function that returns an error should be a
283 location where a #GError can be placed (i.e. "#GError** error"). If
284 #GError is used with varargs, the #GError** should be the last
285 argument before the "...".
291 The caller may pass %NULL for the #GError** if they are not interested
292 in details of the exact error that occurred.
298 If %NULL is passed for the #GError** argument, then errors should
299 not be returned to the caller, but your function should still
300 abort and return if an error occurs. That is, control flow should
301 not be affected by whether the caller wants to get a #GError.
307 If a #GError is reported, then your function by definition
308 <emphasis>had a fatal failure and did not complete whatever it was supposed
309 to do</emphasis>. If the failure was not fatal, then you handled it
310 and you should not report it. If it was fatal, then you must report it
311 and discontinue whatever you were doing immediately.
317 A #GError* must be initialized to %NULL before passing its address to
318 a function that can report errors.
324 "Piling up" errors is always a bug. That is, if you assign a new
325 #GError to a #GError* that is non-%NULL, thus overwriting the previous
326 error, it indicates that you should have aborted the operation instead
327 of continuing. If you were able to continue, you should have cleared
328 the previous error with g_clear_error(). g_set_error() will complain
329 if you pile up errors.
336 By convention, if you return a boolean value indicating success
337 then %TRUE means success and %FALSE means failure. If %FALSE is returned,
338 the error <emphasis>must</emphasis> be set to a non-%NULL value.
345 A %NULL return value is also frequently used to mean that an error
346 occurred. You should make clear in your documentation whether %NULL is
347 a valid return value in non-error cases; if %NULL is a valid value,
348 then users must check whether an error was returned to see if the
355 When implementing a function that can report errors, you may want to
356 add a check at the top of your function that the error return location
357 is either %NULL or contains a %NULL error
358 (e.g. <literal>g_return_if_fail (error == NULL || *error ==
367 <!-- ##### SECTION See_Also ##### -->
372 <!-- ##### STRUCT GError ##### -->
374 The <structname>GError</structname> structure contains
375 information about an error that has occurred.
378 @domain: error domain, e.g. #G_FILE_ERROR.
379 @code: error code, e.g. %G_FILE_ERROR_NOENT.
380 @message: human-readable informative error message.
382 <!-- ##### FUNCTION g_error_new ##### -->
394 <!-- ##### FUNCTION g_error_new_literal ##### -->
405 <!-- ##### FUNCTION g_error_free ##### -->
413 <!-- ##### FUNCTION g_error_copy ##### -->
422 <!-- ##### FUNCTION g_error_matches ##### -->
433 <!-- ##### FUNCTION g_set_error ##### -->
445 <!-- ##### FUNCTION g_propagate_error ##### -->
454 <!-- ##### FUNCTION g_clear_error ##### -->
462 sgml-parent-document: ("../glib-docs.sgml" "book" "refsect2" "")