glib-Error-Reporting.html [plain text]
<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Error Reporting</title><meta name="generator" content="DocBook XSL Stylesheets V1.65.1"><link rel="home" href="index.html" title="GLib Reference Manual"><link rel="up" href="glib-core.html" title="GLib Core Application Support"><link rel="previous" href="glib-IO-Channels.html" title="IO Channels"><link rel="next" href="glib-Warnings-and-Assertions.html" title="Message Output and Debugging Functions"><link rel="chapter" href="glib.html" title="GLib Overview"><link rel="refentry" href="glib-building.html" title="Compiling the GLib package"><link rel="refentry" href="glib-cross-compiling.html" title="Cross-compiling the GLib package"><link rel="refentry" href="glib-compiling.html" title="Compiling GLib Applications"><link rel="refentry" href="glib-running.html" title="Running GLib Applications"><link rel="refentry" href="glib-changes.html" title="Changes to GLib"><link rel="refentry" href="glib-resources.html" title="Mailing lists and bug reports"><link rel="chapter" href="glib-fundamentals.html" title="GLib Fundamentals"><link rel="refentry" href="glib-Basic-Types.html" title="Basic Types"><link rel="refentry" href="glib-Limits-of-Basic-Types.html" title="Limits of Basic Types"><link rel="refentry" href="glib-Standard-Macros.html" title="Standard Macros"><link rel="refentry" href="glib-Type-Conversion-Macros.html" title="Type Conversion Macros"><link rel="refentry" href="glib-Byte-Order-Macros.html" title="Byte Order Macros"><link rel="refentry" href="glib-Numerical-Definitions.html" title="Numerical Definitions"><link rel="refentry" href="glib-Miscellaneous-Macros.html" title="Miscellaneous Macros"><link rel="refentry" href="glib-Atomic-Operations.html" title="Atomic Operations"><link rel="chapter" href="glib-core.html" title="GLib Core Application Support"><link rel="refentry" href="glib-The-Main-Event-Loop.html" title="The Main Event Loop"><link rel="refentry" href="glib-Threads.html" title="
Threads"><link rel="refentry" href="glib-Thread-Pools.html" title="Thread Pools"><link rel="refentry" href="glib-Asynchronous-Queues.html" title="Asynchronous Queues"><link rel="refentry" href="glib-Dynamic-Loading-of-Modules.html" title="Dynamic Loading of Modules"><link rel="refentry" href="glib-Memory-Allocation.html" title="Memory Allocation"><link rel="refentry" href="glib-IO-Channels.html" title="IO Channels"><link rel="refentry" href="glib-Error-Reporting.html" title="Error Reporting"><link rel="refentry" href="glib-Warnings-and-Assertions.html" title="Message Output and Debugging Functions"><link rel="refentry" href="glib-Message-Logging.html" title="Message Logging"><link rel="chapter" href="glib-utilities.html" title="GLib Utilities"><link rel="refentry" href="glib-String-Utility-Functions.html" title="String Utility Functions"><link rel="refentry" href="glib-Character-Set-Conversion.html" title="Character Set Conversion"><link rel="refentry" href="glib-Unicode-Manipulation.html" title="Unicode Manipulation"><link rel="refentry" href="glib-I18N.html" title="Internationalization"><link rel="refentry" href="glib-Date-and-Time-Functions.html" title="Date and Time Functions"><link rel="refentry" href="glib-Random-Numbers.html" title="Random Numbers"><link rel="refentry" href="glib-Hook-Functions.html" title="Hook Functions"><link rel="refentry" href="glib-Miscellaneous-Utility-Functions.html" title="Miscellaneous Utility Functions"><link rel="refentry" href="glib-Lexical-Scanner.html" title="Lexical Scanner"><link rel="refentry" href="glib-Automatic-String-Completion.html" title="Automatic String Completion"><link rel="refentry" href="glib-Timers.html" title="Timers"><link rel="refentry" href="glib-Spawning-Processes.html" title="Spawning Processes"><link rel="refentry" href="glib-File-Utilities.html" title="File Utilities"><link rel="refentry" href="glib-Shell-related-Utilities.html" title="Shell-related Utilities"><link rel="refentry" href="glib-Glob-style-pattern-matching.html" title="Glob-style pattern matching"><link rel="refentry" href="glib-Simple-XML-Subset-Parser.html" title="Simple XML Subset Parser"><link rel="refentry" href="glib-Windows-Compatability-Functions.html" title="Windows Compatibility Functions"><link rel="chapter" href="glib-data-types.html" title="GLib Data Types"><link rel="refentry" href="glib-Memory-Chunks.html" title="Memory Chunks"><link rel="refentry" href="glib-Doubly-Linked-Lists.html" title="Doubly-Linked Lists"><link rel="refentry" href="glib-Singly-Linked-Lists.html" title="Singly-Linked Lists"><link rel="refentry" href="glib-Double-ended-Queues.html" title="Double-ended Queues"><link rel="refentry" href="glib-Trash-Stacks.html" title="Trash Stacks"><link rel="refentry" href="glib-Hash-Tables.html" title="Hash Tables"><link rel="refentry" href="glib-Strings.html" title="Strings"><link rel="refentry" href="glib-String-Chunks.html" title="String Chunks"><link rel="refentry" href="glib-Arrays.html" title="Arrays"><link rel="refentry" href="glib-Pointer-Arrays.html" title="Pointer Arrays"><link rel="refentry" href="glib-Byte-Arrays.html" title="Byte Arrays"><link rel="refentry" href="glib-Balanced-Binary-Trees.html" title="Balanced Binary Trees"><link rel="refentry" href="glib-N-ary-Trees.html" title="N-ary Trees"><link rel="refentry" href="glib-Quarks.html" title="Quarks"><link rel="refentry" href="glib-Keyed-Data-Lists.html" title="Keyed Data Lists"><link rel="refentry" href="glib-Datasets.html" title="Datasets"><link rel="refentry" href="glib-Relations-and-Tuples.html" title="Relations and Tuples"><link rel="refentry" href="glib-Caches.html" title="Caches"><link rel="refentry" href="glib-Memory-Allocators.html" title="Memory Allocators"><link rel="chapter" href="tools.html" title="GLib Tools"><link rel="refentry" href="glib-gettextize.html" title="glib-gettextize"><link rel="index" href="ix01.html" title="Index"><link rel="section" href="glib-Error-Reporting.html#id3083558" title="Description"><link rel="section" href="glib-Error-Reporting.html#id3084698" title="Details"><meta name="generator" content="GTK-Doc V1.2 (XML mode)"><link rel="stylesheet" href="style.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table class="navigation" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2"><tr valign="middle"><td><a accesskey="p" href="glib-IO-Channels.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td><td><a accesskey="u" href="glib-core.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td><td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td><th width="100%" align="center">GLib Reference Manual</th><td><a accesskey="n" href="glib-Warnings-and-Assertions.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td></tr></table><div class="refentry" lang="en"><a name="glib-Error-Reporting"></a><div class="titlepage"><div></div><div></div></div><div class="refnamediv"><h2><span class="refentrytitle">Error Reporting</span></h2><p>Error Reporting — a system for reporting errors.</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
#include <glib.h>
struct <a href="glib-Error-Reporting.html#GError">GError</a>;
<a href="glib-Error-Reporting.html#GError">GError</a>* <a href="glib-Error-Reporting.html#g-error-new">g_error_new</a> (<a href="glib-Quarks.html#GQuark">GQuark</a> domain,
<a href="glib-Basic-Types.html#gint">gint</a> code,
const <a href="glib-Basic-Types.html#gchar">gchar</a> *format,
...);
<a href="glib-Error-Reporting.html#GError">GError</a>* <a href="glib-Error-Reporting.html#g-error-new-literal">g_error_new_literal</a> (<a href="glib-Quarks.html#GQuark">GQuark</a> domain,
<a href="glib-Basic-Types.html#gint">gint</a> code,
const <a href="glib-Basic-Types.html#gchar">gchar</a> *message);
void <a href="glib-Error-Reporting.html#g-error-free">g_error_free</a> (<a href="glib-Error-Reporting.html#GError">GError</a> *error);
<a href="glib-Error-Reporting.html#GError">GError</a>* <a href="glib-Error-Reporting.html#g-error-copy">g_error_copy</a> (const <a href="glib-Error-Reporting.html#GError">GError</a> *error);
<a href="glib-Basic-Types.html#gboolean">gboolean</a> <a href="glib-Error-Reporting.html#g-error-matches">g_error_matches</a> (const <a href="glib-Error-Reporting.html#GError">GError</a> *error,
<a href="glib-Quarks.html#GQuark">GQuark</a> domain,
<a href="glib-Basic-Types.html#gint">gint</a> code);
void <a href="glib-Error-Reporting.html#g-set-error">g_set_error</a> (<a href="glib-Error-Reporting.html#GError">GError</a> **err,
<a href="glib-Quarks.html#GQuark">GQuark</a> domain,
<a href="glib-Basic-Types.html#gint">gint</a> code,
const <a href="glib-Basic-Types.html#gchar">gchar</a> *format,
...);
void <a href="glib-Error-Reporting.html#g-propagate-error">g_propagate_error</a> (<a href="glib-Error-Reporting.html#GError">GError</a> **dest,
<a href="glib-Error-Reporting.html#GError">GError</a> *src);
void <a href="glib-Error-Reporting.html#g-clear-error">g_clear_error</a> (<a href="glib-Error-Reporting.html#GError">GError</a> **err);
</pre></div><div class="refsect1" lang="en"><a name="id3083558"></a><h2>Description</h2><p>
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
<span class="emphasis"><em>data type</em></span> (the <a href="glib-Error-Reporting.html#GError"><span class="type">GError</span></a> object) and a <span class="emphasis"><em>set of
rules.</em></span> If you use <a href="glib-Error-Reporting.html#GError"><span class="type">GError</span></a> incorrectly, then your code will not
properly interoperate with other code that uses <a href="glib-Error-Reporting.html#GError"><span class="type">GError</span></a>, and users of your API
will probably get confused.
</p><p>
First and foremost: <span class="emphasis"><em><a href="glib-Error-Reporting.html#GError"><span class="type">GError</span></a> should only be used to report
recoverable runtime errors, never to report programming errors.</em></span> If
the programmer has screwed up, then you should use <a href="glib-Message-Logging.html#g-warning"><tt class="function">g_warning()</tt></a>,
<a href="glib-Warnings-and-Assertions.html#g-return-if-fail"><tt class="function">g_return_if_fail()</tt></a>, <a href="glib-Warnings-and-Assertions.html#g-assert"><tt class="function">g_assert()</tt></a>, <a href="glib-Message-Logging.html#g-error"><tt class="function">g_error()</tt></a>, or some similar facility.
(Incidentally, remember that the <a href="glib-Message-Logging.html#g-error"><tt class="function">g_error()</tt></a> function should
<span class="emphasis"><em>only</em></span> be used for programming errors, it should not be used
to print any error reportable via <a href="glib-Error-Reporting.html#GError"><span class="type">GError</span></a>.)
</p><p>
Examples of recoverable runtime errors are "file not found" or "failed to parse
input." Examples of programming errors are "NULL passed to <tt class="function">strcmp()</tt>" 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 <a href="glib-Error-Reporting.html#GError"><span class="type">GError</span></a> facility.
</p><p>
Functions that can fail take a return location for a <a href="glib-Error-Reporting.html#GError"><span class="type">GError</span></a> as their last argument.
For example:
</p><div class="informalexample"><pre class="programlisting">
gboolean g_file_get_contents (const gchar *filename,
gchar **contents,
gsize *length,
GError **error);
</pre></div><p>
If you pass a non-<tt class="literal">NULL</tt> value for the <tt class="literal">error</tt> argument, it should
point to a location where an error can be placed. For example:
</p><div class="informalexample"><pre class="programlisting">
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);
}
</pre></div><p>
Note that <tt class="literal">err != NULL</tt> in this example is a
<span class="emphasis"><em>reliable</em></span> indicator of whether
<a href="glib-File-Utilities.html#g-file-get-contents"><tt class="function">g_file_get_contents()</tt></a> failed. Additionally, <a href="glib-File-Utilities.html#g-file-get-contents"><tt class="function">g_file_get_contents()</tt></a> returns
a boolean which indicates whether it was successful.
</p><p>
Because <a href="glib-File-Utilities.html#g-file-get-contents"><tt class="function">g_file_get_contents()</tt></a> returns <tt class="literal">FALSE</tt> on failure, if you are only
interested in whether it failed and don't need to display an error message, you
can pass <tt class="literal">NULL</tt> for the <tt class="literal">error</tt> argument:
</p><div class="informalexample"><pre class="programlisting">
if (g_file_get_contents ("foo.txt", &contents, NULL, NULL)) /* ignore errors */
/* no error occurred */ ;
else
/* error */ ;
</pre></div><p>
</p><p>
The <a href="glib-Error-Reporting.html#GError"><span class="type">GError</span></a> object contains three fields: <tt class="literal">domain</tt> indicates
the module the error-reporting function is located in, <tt class="literal">code</tt>
indicates the specific error that occurred, and <tt class="literal">message</tt> 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:
<a href="glib-Error-Reporting.html#g-error-matches"><tt class="function">g_error_matches()</tt></a> returns <tt class="literal">TRUE</tt> if the error matches a given domain and code,
<a href="glib-Error-Reporting.html#g-propagate-error"><tt class="function">g_propagate_error()</tt></a> copies an error into an error location (so the calling
function will receive it), and <a href="glib-Error-Reporting.html#g-clear-error"><tt class="function">g_clear_error()</tt></a> clears an error location by
freeing the error and resetting the location to <tt class="literal">NULL</tt>. To display an error to the
user, simply display <tt class="literal">error->message</tt>, perhaps along with
additional context known only to the calling function (the file being opened, or
whatever -- though in the <a href="glib-File-Utilities.html#g-file-get-contents"><tt class="function">g_file_get_contents()</tt></a> case,
<tt class="literal">error->message</tt> already contains a filename).
</p><p>
When implementing a function that can report errors, the basic tool is
<a href="glib-Error-Reporting.html#g-set-error"><tt class="function">g_set_error()</tt></a>. Typically, if a fatal error occurs you want to <a href="glib-Error-Reporting.html#g-set-error"><tt class="function">g_set_error()</tt></a>,
then return immediately. <a href="glib-Error-Reporting.html#g-set-error"><tt class="function">g_set_error()</tt></a> does nothing if the error location passed
to it is <tt class="literal">NULL</tt>. Here's an example:
</p><div class="informalexample"><pre class="programlisting">
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;
}
</pre></div><p>
</p><p>
Things are somewhat more complicated if you yourself call another function that
can report a <a href="glib-Error-Reporting.html#GError"><span class="type">GError</span></a>. If the sub-function indicates fatal errors in some way
other than reporting a <a href="glib-Error-Reporting.html#GError"><span class="type">GError</span></a>, such as by returning <tt class="literal">TRUE</tt> on success, you can
simply do the following:
</p><div class="informalexample"><pre class="programlisting">
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);
}
</pre></div><p>
</p><p>
If the sub-function does not indicate errors other than by reporting a <a href="glib-Error-Reporting.html#GError"><span class="type">GError</span></a>,
you need to create a temporary <a href="glib-Error-Reporting.html#GError"><span class="type">GError</span></a> since the passed-in one may be <tt class="literal">NULL</tt>.
<a href="glib-Error-Reporting.html#g-propagate-error"><tt class="function">g_propagate_error()</tt></a> is intended for use in this case.
</p><div class="informalexample"><pre class="programlisting">
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 */
}
</pre></div><p>
</p><p>
Error pileups are always a bug. For example, this code is incorrect:
</p><div class="informalexample"><pre class="programlisting">
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;
}
}
</pre></div><p>
<tt class="literal">tmp_error</tt> should be checked immediately after
<tt class="function"><tt class="function">sub_function_that_can_fail()</tt></tt>, and either cleared or propagated upward. The rule
is: <span class="emphasis"><em>after each error, you must either handle the error, or return it to the
calling function</em></span>. Note that passing <tt class="literal">NULL</tt> 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 <tt class="function"><tt class="function">sub_function_that_can_fail()</tt></tt> are not
fatal to <tt class="function"><tt class="function">my_function_that_can_fail()</tt></tt>:
</p><div class="informalexample"><pre class="programlisting">
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;
}
}
</pre></div><p>
</p><p>
Note that passing <tt class="literal">NULL</tt> for the error location <span class="emphasis"><em>ignores</em></span>
errors; it's equivalent to <tt class="literal">try { <tt class="function">sub_function_that_can_fail()</tt>; } catch
(...) {}</tt> in C++. It does <span class="emphasis"><em>not</em></span> mean to leave errors
unhandled; it means to handle them by doing nothing.
</p><p>
Error domains and codes are conventionally named as follows:
</p><div class="itemizedlist"><ul type="disc"><li><p>
The error domain is called
<tt class="literal"><NAMESPACE>_<MODULE>_ERROR</tt>, for example
<tt class="literal">G_EXEC_ERROR</tt> or <tt class="literal">G_THREAD_ERROR</tt>.
</p></li><li><p>
The error codes are in an enumeration called
<tt class="literal"><Namespace>_<Module>_Error</tt>; for example,
<a href="glib-Threads.html#GThreadError"><span class="type">GThreadError</span></a> or <a href="glib-Spawning-Processes.html#GSpawnError"><span class="type">GSpawnError</span></a>.
</p></li><li><p>
Members of the error code enumeration are called <tt class="literal"><NAMESPACE>_<MODULE>_ERROR_<CODE></tt>, for example <tt class="literal">G_SPAWN_ERROR_FORK</tt> or <tt class="literal">G_THREAD_ERROR_AGAIN</tt>.
</p></li><li><p>
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
<tt class="literal"><NAMESPACE>_<MODULE>_ERROR_FAILED</tt>, for
example <tt class="literal">G_SPAWN_ERROR_FAILED</tt> or <tt class="literal">G_THREAD_ERROR_FAILED</tt>.
</p></li></ul></div><p>
</p><p>
Summary of rules for use of <a href="glib-Error-Reporting.html#GError"><span class="type">GError</span></a>:
</p><div class="itemizedlist"><ul type="disc"><li><p>
Do not report programming errors via <a href="glib-Error-Reporting.html#GError"><span class="type">GError</span></a>.
</p></li><li><p>
The last argument of a function that returns an error should be a
location where a <a href="glib-Error-Reporting.html#GError"><span class="type">GError</span></a> can be placed (i.e. "<a href="glib-Error-Reporting.html#GError"><span class="type">GError</span></a>** error"). If
<a href="glib-Error-Reporting.html#GError"><span class="type">GError</span></a> is used with varargs, the <a href="glib-Error-Reporting.html#GError"><span class="type">GError</span></a>** should be the last
argument before the "...".
</p></li><li><p>
The caller may pass <tt class="literal">NULL</tt> for the <a href="glib-Error-Reporting.html#GError"><span class="type">GError</span></a>** if they are not interested
in details of the exact error that occurred.
</p></li><li><p>
If <tt class="literal">NULL</tt> is passed for the <a href="glib-Error-Reporting.html#GError"><span class="type">GError</span></a>** 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 <a href="glib-Error-Reporting.html#GError"><span class="type">GError</span></a>.
</p></li><li><p>
If a <a href="glib-Error-Reporting.html#GError"><span class="type">GError</span></a> is reported, then your function by definition
<span class="emphasis"><em>had a fatal failure and did not complete whatever it was supposed
to do</em></span>. 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.
</p></li><li><p>
A <a href="glib-Error-Reporting.html#GError"><span class="type">GError</span></a>* must be initialized to <tt class="literal">NULL</tt> before passing its address to
a function that can report errors.
</p></li><li><p>
"Piling up" errors is always a bug. That is, if you assign a new
<a href="glib-Error-Reporting.html#GError"><span class="type">GError</span></a> to a <a href="glib-Error-Reporting.html#GError"><span class="type">GError</span></a>* that is non-<tt class="literal">NULL</tt>, 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 <a href="glib-Error-Reporting.html#g-clear-error"><tt class="function">g_clear_error()</tt></a>. <a href="glib-Error-Reporting.html#g-set-error"><tt class="function">g_set_error()</tt></a> will complain
if you pile up errors.
</p></li><li><p>
By convention, if you return a boolean value indicating success
then <tt class="literal">TRUE</tt> means success and <tt class="literal">FALSE</tt> means failure. If <tt class="literal">FALSE</tt> is returned,
the error <span class="emphasis"><em>must</em></span> be set to a non-<tt class="literal">NULL</tt> value.
</p></li><li><p>
A <tt class="literal">NULL</tt> return value is also frequently used to mean that an error
occurred. You should make clear in your documentation whether <tt class="literal">NULL</tt> is
a valid return value in non-error cases; if <tt class="literal">NULL</tt> is a valid value,
then users must check whether an error was returned to see if the
function succeeded.
</p></li><li><p>
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 <tt class="literal">NULL</tt> or contains a <tt class="literal">NULL</tt> error
(e.g. <tt class="literal">g_return_if_fail (error == NULL || *error ==
NULL);</tt>).
</p></li></ul></div><p>
</p></div><div class="refsect1" lang="en"><a name="id3084698"></a><h2>Details</h2><div class="refsect2" lang="en"><a name="id3084704"></a><h3><a name="GError"></a>struct GError</h3><a class="indexterm" name="id3084715"></a><pre class="programlisting">struct GError {
GQuark domain;
gint code;
gchar *message;
};
</pre><p>
The <span class="structname">GError</span> structure contains
information about an error that has occurred.
</p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><a href="glib-Quarks.html#GQuark">GQuark</a> <i class="structfield"><tt>domain</tt></i></span></td><td>error domain, e.g. <a href="glib-File-Utilities.html#G-FILE-ERROR-CAPS"><span class="type">G_FILE_ERROR</span></a>.
</td></tr><tr><td><span class="term"><a href="glib-Basic-Types.html#gint">gint</a> <i class="structfield"><tt>code</tt></i></span></td><td>error code, e.g. <tt class="literal">G_FILE_ERROR_NOENT</tt>.
</td></tr><tr><td><span class="term"><a href="glib-Basic-Types.html#gchar">gchar</a> *<i class="structfield"><tt>message</tt></i></span></td><td>human-readable informative error message.
</td></tr></tbody></table></div></div><hr><div class="refsect2" lang="en"><a name="id3084813"></a><h3><a name="g-error-new"></a>g_error_new ()</h3><a class="indexterm" name="id3084824"></a><pre class="programlisting"><a href="glib-Error-Reporting.html#GError">GError</a>* g_error_new (<a href="glib-Quarks.html#GQuark">GQuark</a> domain,
<a href="glib-Basic-Types.html#gint">gint</a> code,
const <a href="glib-Basic-Types.html#gchar">gchar</a> *format,
...);</pre><p>
Creates a new <a href="glib-Error-Reporting.html#GError"><span class="type">GError</span></a> with the given <i class="parameter"><tt>domain</tt></i> and <i class="parameter"><tt>code</tt></i>,
and a message formatted with <i class="parameter"><tt>format</tt></i>.</p><p>
</p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><i class="parameter"><tt>domain</tt></i> :</span></td><td> error domain
</td></tr><tr><td><span class="term"><i class="parameter"><tt>code</tt></i> :</span></td><td> error code
</td></tr><tr><td><span class="term"><i class="parameter"><tt>format</tt></i> :</span></td><td> <tt class="function">printf()</tt>-style format for error message
</td></tr><tr><td><span class="term"><i class="parameter"><tt>...</tt></i> :</span></td><td> parameters for message format
</td></tr><tr><td><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td><td> a new <a href="glib-Error-Reporting.html#GError"><span class="type">GError</span></a>
</td></tr></tbody></table></div></div><hr><div class="refsect2" lang="en"><a name="id3084986"></a><h3><a name="g-error-new-literal"></a>g_error_new_literal ()</h3><a class="indexterm" name="id3084998"></a><pre class="programlisting"><a href="glib-Error-Reporting.html#GError">GError</a>* g_error_new_literal (<a href="glib-Quarks.html#GQuark">GQuark</a> domain,
<a href="glib-Basic-Types.html#gint">gint</a> code,
const <a href="glib-Basic-Types.html#gchar">gchar</a> *message);</pre><p>
Creates a new <a href="glib-Error-Reporting.html#GError"><span class="type">GError</span></a>; unlike <a href="glib-Error-Reporting.html#g-error-new"><tt class="function">g_error_new()</tt></a>, <i class="parameter"><tt>message</tt></i> is not
a <tt class="function">printf()</tt>-style format string. Use this
function if <i class="parameter"><tt>message</tt></i> contains text you don't have control over,
that could include <tt class="function">printf()</tt> escape sequences.</p><p>
</p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><i class="parameter"><tt>domain</tt></i> :</span></td><td> error domain
</td></tr><tr><td><span class="term"><i class="parameter"><tt>code</tt></i> :</span></td><td> error code
</td></tr><tr><td><span class="term"><i class="parameter"><tt>message</tt></i> :</span></td><td> error message
</td></tr><tr><td><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td><td> a new <a href="glib-Error-Reporting.html#GError"><span class="type">GError</span></a>
</td></tr></tbody></table></div></div><hr><div class="refsect2" lang="en"><a name="id3085160"></a><h3><a name="g-error-free"></a>g_error_free ()</h3><a class="indexterm" name="id3085172"></a><pre class="programlisting">void g_error_free (<a href="glib-Error-Reporting.html#GError">GError</a> *error);</pre><p>
Frees a <a href="glib-Error-Reporting.html#GError"><span class="type">GError</span></a> and associated resources.</p><p>
</p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><i class="parameter"><tt>error</tt></i> :</span></td><td> a <a href="glib-Error-Reporting.html#GError"><span class="type">GError</span></a>
</td></tr></tbody></table></div></div><hr><div class="refsect2" lang="en"><a name="id3085237"></a><h3><a name="g-error-copy"></a>g_error_copy ()</h3><a class="indexterm" name="id3085248"></a><pre class="programlisting"><a href="glib-Error-Reporting.html#GError">GError</a>* g_error_copy (const <a href="glib-Error-Reporting.html#GError">GError</a> *error);</pre><p>
Makes a copy of <i class="parameter"><tt>error</tt></i>.</p><p>
</p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><i class="parameter"><tt>error</tt></i> :</span></td><td> a <a href="glib-Error-Reporting.html#GError"><span class="type">GError</span></a>
</td></tr><tr><td><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td><td> a new <a href="glib-Error-Reporting.html#GError"><span class="type">GError</span></a>
</td></tr></tbody></table></div></div><hr><div class="refsect2" lang="en"><a name="id3085329"></a><h3><a name="g-error-matches"></a>g_error_matches ()</h3><a class="indexterm" name="id3085340"></a><pre class="programlisting"><a href="glib-Basic-Types.html#gboolean">gboolean</a> g_error_matches (const <a href="glib-Error-Reporting.html#GError">GError</a> *error,
<a href="glib-Quarks.html#GQuark">GQuark</a> domain,
<a href="glib-Basic-Types.html#gint">gint</a> code);</pre><p>
Returns <tt class="literal">TRUE</tt> if <i class="parameter"><tt>error</tt></i> matches <i class="parameter"><tt>domain</tt></i> and <i class="parameter"><tt>code</tt></i>, <tt class="literal">FALSE</tt>
otherwise.</p><p>
</p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><i class="parameter"><tt>error</tt></i> :</span></td><td> a <a href="glib-Error-Reporting.html#GError"><span class="type">GError</span></a>
</td></tr><tr><td><span class="term"><i class="parameter"><tt>domain</tt></i> :</span></td><td> an error domain
</td></tr><tr><td><span class="term"><i class="parameter"><tt>code</tt></i> :</span></td><td> an error code
</td></tr><tr><td><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td><td> whether <i class="parameter"><tt>error</tt></i> has <i class="parameter"><tt>domain</tt></i> and <i class="parameter"><tt>code</tt></i>
</td></tr></tbody></table></div></div><hr><div class="refsect2" lang="en"><a name="id3085498"></a><h3><a name="g-set-error"></a>g_set_error ()</h3><a class="indexterm" name="id3085509"></a><pre class="programlisting">void g_set_error (<a href="glib-Error-Reporting.html#GError">GError</a> **err,
<a href="glib-Quarks.html#GQuark">GQuark</a> domain,
<a href="glib-Basic-Types.html#gint">gint</a> code,
const <a href="glib-Basic-Types.html#gchar">gchar</a> *format,
...);</pre><p>
Does nothing if <i class="parameter"><tt>err</tt></i> is <tt class="literal">NULL</tt>; if <i class="parameter"><tt>err</tt></i> is non-<tt class="literal">NULL</tt>, then *<i class="parameter"><tt>err</tt></i> must
be <tt class="literal">NULL</tt>. A new <a href="glib-Error-Reporting.html#GError"><span class="type">GError</span></a> is created and assigned to *<i class="parameter"><tt>err</tt></i>.</p><p>
</p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><i class="parameter"><tt>err</tt></i> :</span></td><td> a return location for a <a href="glib-Error-Reporting.html#GError"><span class="type">GError</span></a>, or <tt class="literal">NULL</tt>
</td></tr><tr><td><span class="term"><i class="parameter"><tt>domain</tt></i> :</span></td><td> error domain
</td></tr><tr><td><span class="term"><i class="parameter"><tt>code</tt></i> :</span></td><td> error code
</td></tr><tr><td><span class="term"><i class="parameter"><tt>format</tt></i> :</span></td><td> <tt class="function">printf()</tt>-style format
</td></tr><tr><td><span class="term"><i class="parameter"><tt>...</tt></i> :</span></td><td> args for <i class="parameter"><tt>format</tt></i>
</td></tr></tbody></table></div></div><hr><div class="refsect2" lang="en"><a name="id3085716"></a><h3><a name="g-propagate-error"></a>g_propagate_error ()</h3><a class="indexterm" name="id3085727"></a><pre class="programlisting">void g_propagate_error (<a href="glib-Error-Reporting.html#GError">GError</a> **dest,
<a href="glib-Error-Reporting.html#GError">GError</a> *src);</pre><p>
If <i class="parameter"><tt>dest</tt></i> is <tt class="literal">NULL</tt>, free <i class="parameter"><tt>src</tt></i>; otherwise,
moves <i class="parameter"><tt>src</tt></i> into *<i class="parameter"><tt>dest</tt></i>. *<i class="parameter"><tt>dest</tt></i> must be <tt class="literal">NULL</tt>.</p><p>
</p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><i class="parameter"><tt>dest</tt></i> :</span></td><td> error return location
</td></tr><tr><td><span class="term"><i class="parameter"><tt>src</tt></i> :</span></td><td> error to move into the return location
</td></tr></tbody></table></div></div><hr><div class="refsect2" lang="en"><a name="id3085840"></a><h3><a name="g-clear-error"></a>g_clear_error ()</h3><a class="indexterm" name="id3085851"></a><pre class="programlisting">void g_clear_error (<a href="glib-Error-Reporting.html#GError">GError</a> **err);</pre><p>
If <i class="parameter"><tt>err</tt></i> is <tt class="literal">NULL</tt>, does nothing. If <i class="parameter"><tt>err</tt></i> is non-<tt class="literal">NULL</tt>,
calls <a href="glib-Error-Reporting.html#g-error-free"><tt class="function">g_error_free()</tt></a> on *<i class="parameter"><tt>err</tt></i> and sets *<i class="parameter"><tt>err</tt></i> to <tt class="literal">NULL</tt>.</p><p>
</p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><i class="parameter"><tt>err</tt></i> :</span></td><td> a <a href="glib-Error-Reporting.html#GError"><span class="type">GError</span></a> return location
</td></tr></tbody></table></div></div></div></div><table class="navigation" width="100%" summary="Navigation footer" cellpadding="2" cellspacing="0"><tr valign="middle"><td align="left"><a accesskey="p" href="glib-IO-Channels.html"><b><< IO Channels</b></a></td><td align="right"><a accesskey="n" href="glib-Warnings-and-Assertions.html"><b>Message Output and Debugging Functions >></b></a></td></tr></table></body></html>