glib-error-reporting.html

glid编写实例

</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 (&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 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 <code class="literal">NULL</code> 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 <code class="function"><code class="function">sub_function_that_can_fail()</code></code> are not
fatal to <code class="function"><code class="function">my_function_that_can_fail()</code></code>:
</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 (&amp;tmp_error);

  if (tmp_error != NULL)
    {
       g_propagate_error (err, tmp_error);
       return FALSE;
    }
}
</pre></div>
<p>
</p>
<p>
Note that passing <code class="literal">NULL</code> 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 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
<code class="literal">&lt;NAMESPACE&gt;_&lt;MODULE&gt;_ERROR</code>, for example
<code class="literal">G_EXEC_ERROR</code> or <code class="literal">G_THREAD_ERROR</code>.
</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 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 <code class="literal">&lt;NAMESPACE&gt;_&lt;MODULE&gt;_ERROR_&lt;CODE&gt;</code>, for example <code class="literal">G_SPAWN_ERROR_FORK</code> or <code class="literal">G_THREAD_ERROR_AGAIN</code>. 
</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 
<code class="literal">&lt;NAMESPACE&gt;_&lt;MODULE&gt;_ERROR_FAILED</code>, for 
example <code class="literal">G_SPAWN_ERROR_FAILED</code> or <code class="literal">G_THREAD_ERROR_FAILED</code>.
</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 <code class="literal">NULL</code> 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 <code class="literal">NULL</code> 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 <code class="literal">NULL</code> 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-<code class="literal">NULL</code>, 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"><code class="function">g_clear_error()</code></a>. <a 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 <code class="literal">TRUE</code> means success and <code class="literal">FALSE</code> means failure. If <code class="literal">FALSE</code> is returned,
          the error <span class="emphasis"><em>must</em></span> be set to a non-<code class="literal">NULL</code> value. 
        </p></li>
<li><p>
          A <code class="literal">NULL</code> return value is also frequently used to mean that an error
          occurred.  You should make clear in your documentation whether <code class="literal">NULL</code> is
          a valid return value in non-error cases; if <code class="literal">NULL</code> 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 <code class="literal">NULL</code> or contains a <code class="literal">NULL</code> 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="id2925505"></a><h2>Details</h2>
<div class="refsect2" lang="en">
<a name="id2925511"></a><h3>
<a name="GError"></a>GError</h3>
<a class="indexterm" name="id2925521"></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>
<span class="term"><a href="glib-Quarks.html#GQuark">GQuark</a>&#160;<em class="structfield"><code>domain</code></em>;</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>&#160;<em class="structfield"><code>code</code></em>;</span></td>
<td>error code, e.g. <code class="literal">G_FILE_ERROR_NOENT</code>.
</td>
</tr>
<tr>
<td>
<span class="term"><a href="glib-Basic-Types.html#gchar">gchar</a>&#160;*<em class="structfield"><code>message</code></em>;</span></td>
<td>human-readable informative error message.

</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id2925624"></a><h3>
<a name="g-error-new"></a>g_error_new ()</h3>
<a class="indexterm" name="id2925634"></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 <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>
<span class="term"><em class="parameter"><code>domain</code></em>&#160;:</span></td>
<td> error domain 
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>code</code></em>&#160;:</span></td>
<td> error code
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>format</code></em>&#160;:</span></td>
<td> <code class="function">printf()</code>-style format for error message
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>...</code></em>&#160;:</span></td>
<td> parameters for message format
</td>
</tr>
<tr>
<td>
<span class="term"><span class="emphasis"><em>Returns</em></span>&#160;:</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">