error_reporting.sgml

GLib是GTK+和GNOME工程的基础底层核心程序库

          location where a <link linkend="GError">GError</link> can be placed (i.e. "<link linkend="GError">GError</link>** error").  If
          <link linkend="GError">GError</link> is used with varargs, the <link linkend="GError">GError</link>** should be the last
          argument before the "...".
        </para>
      </listitem>

      <listitem>
        <para>
          The caller may pass <literal>NULL</literal> for the <link linkend="GError">GError</link>** if they are not interested
          in details of the exact error that occurred.
        </para>
      </listitem>

	<listitem>
	  <para>
           If <literal>NULL</literal> is passed for the <link linkend="GError">GError</link>** 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 <link linkend="GError">GError</link>.
	  </para>
	</listitem>

      <listitem>
        <para>
          If a <link linkend="GError">GError</link> is reported, then your function by definition  
          <emphasis>had a fatal failure and did not complete whatever it was supposed
            to do</emphasis>. 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.
        </para>
      </listitem>

	<listitem>
	  <para>
          A <link linkend="GError">GError</link>* must be initialized to <literal>NULL</literal> before passing its address to
          a function that can report errors.
	  </para>
	</listitem>

	<listitem>
	  <para>
          "Piling up" errors is always a bug. That is, if you assign a new
          <link linkend="GError">GError</link> to a <link linkend="GError">GError</link>* that is non-<literal>NULL</literal>, 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 <link linkend="g-clear-error">g_clear_error</link>(). <link linkend="g-set-error">g_set_error</link>() will complain
          if you pile up errors.
	  </para>
	</listitem>


	<listitem>
	  <para>
          By convention, if you return a boolean value indicating success 
          then <literal>TRUE</literal> means success and <literal>FALSE</literal> means failure. If <literal>FALSE</literal> is returned,
          the error <emphasis>must</emphasis> be set to a non-<literal>NULL</literal> value. 
        </para>
	</listitem>


	<listitem>
	  <para>
          A <literal>NULL</literal> return value is also frequently used to mean that an error
          occurred.  You should make clear in your documentation whether <literal>NULL</literal> is
          a valid return value in non-error cases; if <literal>NULL</literal> is a valid value,
          then users must check whether an error was returned to see if the
          function succeeded.
	  </para>
	</listitem>

	<listitem>
	  <para>
          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 <literal>NULL</literal> or contains a <literal>NULL</literal> error
          (e.g. <literal>g_return_if_fail (error == NULL || *error ==
          NULL);</literal>).
	  </para>
	</listitem>


</itemizedlist>
</para>
</refsect1>

<refsect1>
<title>Details</title>
<refsect2>
<title><anchor id="GError">struct GError</title>
<programlisting>struct GError
{
  GQuark       domain;
  gint         code;
  gchar       *message;
};
</programlisting>
<para>
The <structname>GError</structname> structure contains 
information about an error that has occurred.
</para><informaltable pgwide="1" frame="none" role="struct">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row>
<entry><link linkend="GQuark">GQuark</link> <structfield>domain</structfield></entry>
<entry>error domain, e.g. <link linkend="G-FILE-ERROR-CAPS">G_FILE_ERROR</link>.
</entry>
</row>
<row>
<entry><link linkend="gint">gint</link> <structfield>code</structfield></entry>
<entry>error code, e.g. <literal>G_FILE_ERROR_NOENT</literal>.
</entry>
</row>
<row>
<entry><link linkend="gchar">gchar</link> *<structfield>message</structfield></entry>
<entry>human-readable informative error message.

</entry>
</row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-error-new">g_error_new ()</title>
<programlisting><link linkend="GError">GError</link>*     g_error_new                     (<link linkend="GQuark">GQuark</link> domain,
                                             <link linkend="gint">gint</link> code,
                                             const <link linkend="gchar">gchar</link> *format,
                                             ...);</programlisting>
<para>
Creates a new <link linkend="GError">GError</link> with the given <parameter>domain</parameter> and <parameter>code</parameter>,
and a message formatted with <parameter>format</parameter>.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>domain</parameter>&nbsp;:</entry>
<entry> error domain 
</entry></row>
<row><entry align="right"><parameter>code</parameter>&nbsp;:</entry>
<entry> error code
</entry></row>
<row><entry align="right"><parameter>format</parameter>&nbsp;:</entry>
<entry> <function>printf()</function>-style format for error message
</entry></row>
<row><entry align="right"><parameter>...</parameter>&nbsp;:</entry>
<entry> parameters for message format
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> a new <link linkend="GError">GError</link>
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-error-new-literal">g_error_new_literal ()</title>
<programlisting><link linkend="GError">GError</link>*     g_error_new_literal             (<link linkend="GQuark">GQuark</link> domain,
                                             <link linkend="gint">gint</link> code,
                                             const <link linkend="gchar">gchar</link> *message);</programlisting>
<para>
Creates a new <link linkend="GError">GError</link>; unlike <link linkend="g-error-new">g_error_new</link>(), <parameter>message</parameter> is not
a <function>printf()</function>-style format string. Use this 
function if <parameter>message</parameter> contains text you don't have control over, 
that could include <function>printf()</function> escape sequences.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>domain</parameter>&nbsp;:</entry>
<entry> error domain
</entry></row>
<row><entry align="right"><parameter>code</parameter>&nbsp;:</entry>
<entry> error code
</entry></row>
<row><entry align="right"><parameter>message</parameter>&nbsp;:</entry>
<entry> error message
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> a new <link linkend="GError">GError</link>
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-error-free">g_error_free ()</title>
<programlisting>void        g_error_free                    (<link linkend="GError">GError</link> *error);</programlisting>
<para>
Frees a <link linkend="GError">GError</link> and associated resources.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>error</parameter>&nbsp;:</entry>
<entry> a <link linkend="GError">GError</link>
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-error-copy">g_error_copy ()</title>
<programlisting><link linkend="GError">GError</link>*     g_error_copy                    (const <link linkend="GError">GError</link> *error);</programlisting>
<para>
Makes a copy of <parameter>error</parameter>.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>error</parameter>&nbsp;:</entry>
<entry> a <link linkend="GError">GError</link>
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> a new <link linkend="GError">GError</link>
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-error-matches">g_error_matches ()</title>
<programlisting><link linkend="gboolean">gboolean</link>    g_error_matches                 (const <link linkend="GError">GError</link> *error,
                                             <link linkend="GQuark">GQuark</link> domain,
                                             <link linkend="gint">gint</link> code);</programlisting>
<para>
Returns <literal>TRUE</literal> if <parameter>error</parameter> matches <parameter>domain</parameter> and <parameter>code</parameter>, <literal>FALSE</literal>
otherwise.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>error</parameter>&nbsp;:</entry>
<entry> a <link linkend="GError">GError</link>
</entry></row>
<row><entry align="right"><parameter>domain</parameter>&nbsp;:</entry>
<entry> an error domain
</entry></row>
<row><entry align="right"><parameter>code</parameter>&nbsp;:</entry>
<entry> an error code
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> whether <parameter>error</parameter> has <parameter>domain</parameter> and <parameter>code</parameter>
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-set-error">g_set_error ()</title>
<programlisting>void        g_set_error                     (<link linkend="GError">GError</link> **err,
                                             <link linkend="GQuark">GQuark</link> domain,
                                             <link linkend="gint">gint</link> code,
                                             const <link linkend="gchar">gchar</link> *format,
                                             ...);</programlisting>
<para>
Does nothing if <parameter>err</parameter> is <literal>NULL</literal>; if <parameter>err</parameter> is non-<literal>NULL</literal>, then *<parameter>err</parameter> must
be <literal>NULL</literal>. A new <link linkend="GError">GError</link> is created and assigned to *<parameter>err</parameter>.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>err</parameter>&nbsp;:</entry>
<entry> a return location for a <link linkend="GError">GError</link>, or <literal>NULL</literal>
</entry></row>
<row><entry align="right"><parameter>domain</parameter>&nbsp;:</entry>
<entry> error domain
</entry></row>
<row><entry align="right"><parameter>code</parameter>&nbsp;:</entry>
<entry> error code 
</entry></row>
<row><entry align="right"><parameter>format</parameter>&nbsp;:</entry>
<entry> <function>printf()</function>-style format
</entry></row>
<row><entry align="right"><parameter>...</parameter>&nbsp;:</entry>
<entry> args for <parameter>format</parameter> 
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-propagate-error">g_propagate_error ()</title>
<programlisting>void        g_propagate_error               (<link linkend="GError">GError</link> **dest,
                                             <link linkend="GError">GError</link> *src);</programlisting>
<para>
If <parameter>dest</parameter> is <literal>NULL</literal>, free <parameter>src</parameter>; otherwise,
moves <parameter>src</parameter> into *<parameter>dest</parameter>. *<parameter>dest</parameter> must be <literal>NULL</literal>.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>dest</parameter>&nbsp;:</entry>
<entry> error return location
</entry></row>
<row><entry align="right"><parameter>src</parameter>&nbsp;:</entry>
<entry> error to move into the return location
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-clear-error">g_clear_error ()</title>
<programlisting>void        g_clear_error                   (<link linkend="GError">GError</link> **err);</programlisting>
<para>
If <parameter>err</parameter> is <literal>NULL</literal>, does nothing. If <parameter>err</parameter> is non-<literal>NULL</literal>,
calls <link linkend="g-error-free">g_error_free</link>() on *<parameter>err</parameter> and sets *<parameter>err</parameter> to <literal>NULL</literal>.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>err</parameter>&nbsp;:</entry>
<entry> a <link linkend="GError">GError</link> return location
</entry></row>
</tbody></tgroup></informaltable></refsect2>

</refsect1>




</refentry>