g_return_val_if_fail (err == NULL || *err == NULL, FALSE);  tmp_error = NULL;  sub_function_that_can_fail (&amp;tmp_error);  other_function_that_can_fail (&amp;tmp_error);  if (tmp_error != NULL)    {       g_propagate_error (err, tmp_error);       return FALSE;    }}</pre></div><p><code class="literal">tmp_error</code> should be checked immediately after<code class="function"><code class="function">sub_function_that_can_fail()</code></code>, and either cleared or propagated upward.  The ruleis: <span class="emphasis"><em>after each error, you must either handle the error, or return it to thecalling function</em></span>.  Note that passing <a class="link" href="glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> for the error location is theequivalent of handling an error by always doing nothing about it. So thefollowing code is fine, assuming errors in <code class="function"><code class="function">sub_function_that_can_fail()</code></code> are notfatal to <code class="function"><code class="function">my_function_that_can_fail()</code></code>:</p><div class="informalexample"><pre class="programlisting">gbooleanmy_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 (&amp;tmp_error);  if (tmp_error != NULL)    {       g_propagate_error (err, tmp_error);       return FALSE;    }}</pre></div><p></p><p>Note that passing <a class="link" href="glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> for the error location <span class="emphasis"><em>ignores</em></span>errors; it's equivalent to <code class="literal">try { <code class="function">sub_function_that_can_fail()</code>; } catch(...) {}</code> in C++. It does <span class="emphasis"><em>not</em></span> mean to leave errorsunhandled; 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 <code class="literal">&lt;NAMESPACE&gt;_&lt;MODULE&gt;_ERROR</code>, for example<a class="link" href="glib-Spawning-Processes.html#G-SPAWN-ERROR:CAPS"><code class="literal">G_SPAWN_ERROR</code></a> or <a class="link" href="glib-Threads.html#G-THREAD-ERROR:CAPS"><code class="literal">G_THREAD_ERROR</code></a>:</p><div class="informalexample"><pre class="programlisting">#define G_SPAWN_ERROR g_spawn_error_quark ()GQuarkg_spawn_error_quark (void){  return g_quark_from_static_string ("g-spawn-error-quark");}</pre></div><p></p></li><li><p>The error codes are in an enumeration called <code class="literal">&lt;Namespace&gt;&lt;Module&gt;Error</code>; for example,<a class="link" href="glib-Threads.html#GThreadError"><span class="type">GThreadError</span></a> or <a class="link" href="glib-Spawning-Processes.html#GSpawnError"><span class="type">GSpawnError</span></a>.</p></li><li><p>Members of the error code enumeration are called <code class="literal">&lt;NAMESPACE&gt;_&lt;MODULE&gt;_ERROR_&lt;CODE&gt;</code>, for example <a class="link" href="glib-Spawning-Processes.html#G-SPAWN-ERROR-FORK:CAPS"><code class="literal">G_SPAWN_ERROR_FORK</code></a> or <a class="link" href="glib-Threads.html#G-THREAD-ERROR-AGAIN:CAPS"><code class="literal">G_THREAD_ERROR_AGAIN</code></a>. </p></li><li><p>If there's a "generic" or "unknown" error code for unrecoverable errors itdoesn't make sense to distinguish with specific codes, it should be called <code class="literal">&lt;NAMESPACE&gt;_&lt;MODULE&gt;_ERROR_FAILED</code>, for example <a class="link" href="glib-Spawning-Processes.html#G-SPAWN-ERROR-FAILED:CAPS"><code class="literal">G_SPAWN_ERROR_FAILED</code></a> or <code class="literal">G_THREAD_ERROR_FAILED</code>.</p></li></ul></div><p></p><p>Summary of rules for use of <span class="type">""</span>      </p><div class="itemizedlist"><ul type="disc"><li><p>           Do not report programming errors via <a class="link" 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 class="link" href="glib-Error-Reporting.html#GError"><span class="type">GError</span></a> can be placed (i.e. "<a class="link" href="glib-Error-Reporting.html#GError"><span class="type">GError</span></a>** error").  If          <a class="link" href="glib-Error-Reporting.html#GError"><span class="type">GError</span></a> is used with varargs, the <a class="link" 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 <a class="link" href="glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> for the <a class="link" 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 <a class="link" href="glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> is passed for the <a class="link" 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 class="link" href="glib-Error-Reporting.html#GError"><span class="type">GError</span></a>.	  </p></li><li><p>          If a <a class="link" 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 class="link" href="glib-Error-Reporting.html#GError"><span class="type">GError</span></a>* must be initialized to <a class="link" href="glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> 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 class="link" href="glib-Error-Reporting.html#GError"><span class="type">GError</span></a> to a <a class="link" href="glib-Error-Reporting.html#GError"><span class="type">GError</span></a>* that is non-<a class="link" href="glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>, 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 class="link" href="glib-Error-Reporting.html#g-clear-error"><code class="function">g_clear_error()</code></a>. <a class="link" href="glib-Error-Reporting.html#g-set-error"><code class="function">g_set_error()</code></a> will complain          if you pile up errors.	  </p></li><li><p>          By convention, if you return a boolean value indicating success           then <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> means success and <a class="link" href="glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a> means failure. If <a class="link" href="glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a> is returned,          the error <span class="emphasis"><em>must</em></span> be set to a non-<a class="link" href="glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> value.         </p></li><li><p>          A <a class="link" href="glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> return value is also frequently used to mean that an error          occurred.  You should make clear in your documentation whether <a class="link" href="glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> is          a valid return value in non-error cases; if <a class="link" href="glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> 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 <a class="link" href="glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> or contains a <a class="link" href="glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> error          (e.g. <code class="literal">g_return_if_fail (error == NULL || *error ==          NULL);</code>).	  </p></li></ul></div><p></p></div><div class="refsect1" lang="en"><a name="id2948572"></a><h2>Details</h2><div class="refsect2" lang="en"><a name="id2948582"></a><h3><a name="GError"></a>GError</h3><a class="indexterm" name="id2948595"></a><pre class="programlisting">typedef struct {  GQuark       domain;  gint         code;  gchar       *message;} GError;</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><p><span class="term"><a class="link" href="glib-Quarks.html#GQuark">GQuark</a>&#160;<em class="structfield"><code>domain</code></em>;</span></p></td><td>error domain, e.g. <a class="link" href="glib-File-Utilities.html#G-FILE-ERROR:CAPS"><span class="type">G_FILE_ERROR</span></a>.</td></tr><tr><td><p><span class="term"><a class="link" href="glib-Basic-Types.html#gint">gint</a>&#160;<em class="structfield"><code>code</code></em>;</span></p></td><td>error code, e.g. <a class="link" href="glib-File-Utilities.html#G-FILE-ERROR-NOENT:CAPS"><code class="literal">G_FILE_ERROR_NOENT</code></a>.</td></tr><tr><td><p><span class="term"><a class="link" href="glib-Basic-Types.html#gchar">gchar</a>&#160;*<em class="structfield"><code>message</code></em>;</span></p></td><td>human-readable informative error message.</td></tr></tbody></table></div></div><hr><div class="refsect2" lang="en"><a name="id2948703"></a><h3><a name="g-error-new"></a>g_error_new ()</h3><a class="indexterm" name="id2948715"></a><pre class="programlisting"><a class="link" href="glib-Error-Reporting.html#GError">GError</a>*             g_error_new                         (<a class="link" href="glib-Quarks.html#GQuark">GQuark</a> domain,                                                         <a class="link" href="glib-Basic-Types.html#gint">gint</a> code,                                                         const <a class="link" href="glib-Basic-Types.html#gchar">gchar</a> *format,                                                         ...);</pre><p>Creates a new <a class="link" href="glib-Error-Reporting.html#GError"><span class="type">GError</span></a> with the given <em class="parameter"><code>domain</code></em> and <em class="parameter"><code>code</code></em>,and a message formatted with <em class="parameter"><code>format</code></em>.</p><p></p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><p><span class="term"><em class="parameter"><code>domain</code></em>&#160;:</span></p></td><td> error domain </td></tr><tr><td><p><span class="term"><em class="parameter"><code>code</code></em>&#160;:</span></p></td><td> error code</td></tr><tr><td><p><span class="term"><em class="parameter"><code>format</code></em>&#160;:</span></p></td><td> <code class="function">printf()</code>-style format for error message</td></tr><tr><td><p><span class="term"><em class="parameter"><code>...</code></em>&#160;:</span></p></td><td> parameters for message format</td></tr><tr><td><p><span class="term"><span class="emphasis"><em>Returns</em></span>&#160;:</span></p></td><td> a new <a class="link" 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="id2948878"></a><h3><a name="g-error-new-literal"></a>g_error_new_literal ()</h3><a class="indexterm" name="id2948891"></a><pre class="programlisting"><a class="link" href="glib-Error-Reporting.html#GError">GError</a>*             g_error_new_literal                 (<a class="link" href="glib-Quarks.html#GQuark">GQuark</a> domain,                                                         <a class="link" href="glib-Basic-Types.html#gint">gint</a> code,                                                         const <a class="link" href="glib-Basic-Types.html#gchar">gchar</a> *message);</pre><p>Creates a new <a class="link" href="glib-Error-Reporting.html#GError"><span class="type">GError</span></a>; unlike <a class="link" href="glib-Error-Reporting.html#g-error-new"><code class="function">g_error_new()</code></a>, <em class="parameter"><code>message</code></em> is nota <code class="function">printf()</code>-style format string. Use this function if <em class="parameter"><code>message</code></em> contains text you don't have control over, that could include <code class="function">printf()</code> escape sequences.</p><p></p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><p><span class="term"><em class="parameter"><code>domain</code></em>&#160;:</span></p></td><td> error domain</td></tr><tr><td><p><span class="term"><em class="parameter"><code>code</code></em>&#160;:</span></p></td><td> error code</td></tr><tr><td><p><span class="term"><em class="parameter"><code>message</code></em>&#160;:</span></p></td><td> error message</td></tr><tr><td><p><span class="term"><span class="emphasis"><em>Returns</em></span>&#160;:</span></p></td><td> a new <a class="link" href="glib-Error-Reporting.html#GError"><span class="type">GError</span></a></td></tr></tbody></table></div></div>