PageRenderTime 6ms CodeModel.GetById 2ms app.highlight 12ms RepoModel.GetById 1ms app.codeStats 1ms

/3rd-party/glib-2.16.6/docs/reference/glib/xml/error_reporting.xml

https://bitbucket.org/super119/plu2youku
XML | 688 lines | 614 code | 73 blank | 1 comment | 0 complexity | cabef492a488dc37213f6bfd9da72a4f MD5 | raw file
  1<refentry id="glib-Error-Reporting">
  2<refmeta>
  3<refentrytitle role="top_of_page" id="glib-Error-Reporting.top_of_page">Error Reporting</refentrytitle>
  4<manvolnum>3</manvolnum>
  5<refmiscinfo>GLIB Library</refmiscinfo>
  6</refmeta>
  7
  8<refnamediv>
  9<refname>Error Reporting</refname>
 10<refpurpose>a system for reporting errors</refpurpose>
 11<!--[<xref linkend="desc" endterm="desc.title"/>]-->
 12</refnamediv>
 13
 14<refsynopsisdiv id="glib-Error-Reporting.synopsis" role="synopsis">
 15<title role="synopsis.title">Synopsis</title>
 16
 17<synopsis>
 18
 19#include &lt;glib.h&gt;
 20
 21                    <link linkend="GError">GError</link>;
 22<link linkend="GError">GError</link>*             <link linkend="g-error-new">g_error_new</link>                         (<link linkend="GQuark">GQuark</link> domain,
 23                                                         <link linkend="gint">gint</link> code,
 24                                                         const <link linkend="gchar">gchar</link> *format,
 25                                                         ...);
 26<link linkend="GError">GError</link>*             <link linkend="g-error-new-literal">g_error_new_literal</link>                 (<link linkend="GQuark">GQuark</link> domain,
 27                                                         <link linkend="gint">gint</link> code,
 28                                                         const <link linkend="gchar">gchar</link> *message);
 29<link linkend="void">void</link>                <link linkend="g-error-free">g_error_free</link>                        (<link linkend="GError">GError</link> *error);
 30<link linkend="GError">GError</link>*             <link linkend="g-error-copy">g_error_copy</link>                        (const <link linkend="GError">GError</link> *error);
 31<link linkend="gboolean">gboolean</link>            <link linkend="g-error-matches">g_error_matches</link>                     (const <link linkend="GError">GError</link> *error,
 32                                                         <link linkend="GQuark">GQuark</link> domain,
 33                                                         <link linkend="gint">gint</link> code);
 34<link linkend="void">void</link>                <link linkend="g-set-error">g_set_error</link>                         (<link linkend="GError">GError</link> **err,
 35                                                         <link linkend="GQuark">GQuark</link> domain,
 36                                                         <link linkend="gint">gint</link> code,
 37                                                         const <link linkend="gchar">gchar</link> *format,
 38                                                         ...);
 39<link linkend="void">void</link>                <link linkend="g-propagate-error">g_propagate_error</link>                   (<link linkend="GError">GError</link> **dest,
 40                                                         <link linkend="GError">GError</link> *src);
 41<link linkend="void">void</link>                <link linkend="g-clear-error">g_clear_error</link>                       (<link linkend="GError">GError</link> **err);
 42<link linkend="void">void</link>                <link linkend="g-prefix-error">g_prefix_error</link>                      (<link linkend="GError">GError</link> **err,
 43                                                         const <link linkend="gchar">gchar</link> *format,
 44                                                         ...);
 45<link linkend="void">void</link>                <link linkend="g-propagate-prefixed-error">g_propagate_prefixed_error</link>          (<link linkend="GError">GError</link> **dest,
 46                                                         <link linkend="GError">GError</link> *src,
 47                                                         const <link linkend="gchar">gchar</link> *format,
 48                                                         ...);
 49</synopsis>
 50</refsynopsisdiv>
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60<refsect1 id="glib-Error-Reporting.description" role="desc">
 61<title role="desc.title">Description</title>
 62
 63<para>
 64GLib provides a standard method of reporting errors from a called function to
 65the calling code. (This is the same problem solved by exceptions in other
 66languages.) It's important to understand that this method is both a
 67<emphasis>data type</emphasis> (the <link linkend="GError"><type>GError</type></link> object) and a <emphasis>set of
 68rules.</emphasis> If you use <link linkend="GError"><type>GError</type></link> incorrectly, then your code will not
 69properly interoperate with other code that uses <link linkend="GError"><type>GError</type></link>, and users of your API
 70will probably get confused.
 71</para>
 72
 73<para>
 74First and foremost: <emphasis><link linkend="GError"><type>GError</type></link> should only be used to report
 75recoverable runtime errors, never to report programming errors.</emphasis> If
 76the programmer has screwed up, then you should use <link linkend="g-warning"><function>g_warning()</function></link>,
 77<link linkend="g-return-if-fail"><function>g_return_if_fail()</function></link>, <link linkend="g-assert"><function>g_assert()</function></link>, <link linkend="g-error"><function>g_error()</function></link>, or some similar facility.
 78(Incidentally, remember that the <link linkend="g-error"><function>g_error()</function></link> function should
 79<emphasis>only</emphasis> be used for programming errors, it should not be used
 80to print any error reportable via <link linkend="GError"><type>GError</type></link>.)
 81</para>
 82
 83<para>
 84Examples of recoverable runtime errors are "file not found" or "failed to parse
 85input." Examples of programming errors are "NULL passed to <link linkend="strcmp"><function>strcmp()</function></link>" or
 86"attempted to free the same pointer twice." These two kinds of errors are
 87fundamentally different: runtime errors should be handled or reported to the
 88user, programming errors should be eliminated by fixing the bug in the program.
 89This is why most functions in GLib and GTK+ do not use the <link linkend="GError"><type>GError</type></link> facility.
 90</para>
 91
 92<para>
 93Functions that can fail take a return location for a <link linkend="GError"><type>GError</type></link> as their last argument. 
 94For example:
 95<informalexample><programlisting>
 96gboolean g_file_get_contents (const gchar *filename, 
 97	                      gchar      **contents,
 98                              gsize       *length,
 99                              GError     **error);
100</programlisting></informalexample>
101If you pass a non-<link linkend="NULL:CAPS"><literal>NULL</literal></link> value for the <literal>error</literal> argument, it should 
102point to a location where an error can be placed. For example:
103<informalexample><programlisting>
104gchar *contents;
105GError *err = NULL;
106g_file_get_contents ("foo.txt", &amp;contents, NULL, &amp;err);
107g_assert ((contents == NULL &amp;&amp; err != NULL) || (contents != NULL &amp;&amp; err == NULL));
108if (err != NULL)
109  {
110    /* Report error to user, and free error */
111    g_assert (contents == NULL);
112    fprintf (stderr, "Unable to read file: &percnt;s\n", err->message);
113    g_error_free (err);
114  } 
115else
116  {
117    /* Use file contents */
118    g_assert (contents != NULL);
119  }
120</programlisting></informalexample>
121Note that <literal>err != NULL</literal> in this example is a
122<emphasis>reliable</emphasis> indicator of whether
123<link linkend="g-file-get-contents"><function>g_file_get_contents()</function></link> failed. Additionally, <link linkend="g-file-get-contents"><function>g_file_get_contents()</function></link> returns
124a boolean which indicates whether it was successful.
125</para>
126
127<para>
128Because <link linkend="g-file-get-contents"><function>g_file_get_contents()</function></link> returns <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> on failure, if you are only
129interested in whether it failed and don't need to display an error message, you
130can pass <link linkend="NULL:CAPS"><literal>NULL</literal></link> for the <literal>error</literal> argument:
131<informalexample><programlisting>
132if (g_file_get_contents ("foo.txt", &amp;contents, NULL, NULL)) /* ignore errors */
133  /* no error occurred */ ;
134else
135  /* error */ ;
136</programlisting></informalexample>
137</para>
138
139<para>
140The <link linkend="GError"><type>GError</type></link> object contains three fields: <literal>domain</literal> indicates
141the module the error-reporting function is located in, <literal>code</literal>
142indicates the specific error that occurred, and <literal>message</literal> is a
143user-readable error message with as many details as possible. Several functions
144are provided to deal with an error received from a called function:
145<link linkend="g-error-matches"><function>g_error_matches()</function></link> returns <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if the error matches a given domain and code,
146<link linkend="g-propagate-error"><function>g_propagate_error()</function></link> copies an error into an error location (so the calling
147function will receive it), and <link linkend="g-clear-error"><function>g_clear_error()</function></link> clears an error location by
148freeing the error and resetting the location to <link linkend="NULL:CAPS"><literal>NULL</literal></link>. To display an error to the
149user, simply display <literal>error-&gt;message</literal>, perhaps along with
150additional context known only to the calling function (the file being opened, or
151whatever -- though in the <link linkend="g-file-get-contents"><function>g_file_get_contents()</function></link> case,
152<literal>error-&gt;message</literal> already contains a filename).
153</para>
154
155<para>
156When implementing a function that can report errors, the basic tool is
157<link linkend="g-set-error"><function>g_set_error()</function></link>. Typically, if a fatal error occurs you want to <link linkend="g-set-error"><function>g_set_error()</function></link>,
158then return immediately. <link linkend="g-set-error"><function>g_set_error()</function></link> does nothing if the error location passed
159to it is <link linkend="NULL:CAPS"><literal>NULL</literal></link>. Here's an example:
160<informalexample><programlisting>
161gint
162foo_open_file (GError **error)
163{
164  gint fd;
165
166  fd = open ("file.txt", O_RDONLY);
167
168  if (fd &lt; 0)
169    {
170      g_set_error (error,
171                   FOO_ERROR,                 /* error domain */
172                   FOO_ERROR_BLAH,            /* error code */
173                   "Failed to open file: &percnt;s", /* error message format string */
174                   g_strerror (errno));
175      return -1;
176    }
177  else
178    return fd;
179}
180</programlisting></informalexample>
181</para>
182
183<para>
184Things are somewhat more complicated if you yourself call another function that
185can report a <link linkend="GError"><type>GError</type></link>. If the sub-function indicates fatal errors in some way
186other than reporting a <link linkend="GError"><type>GError</type></link>, such as by returning <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> on success, you can
187simply do the following:
188<informalexample><programlisting>
189gboolean
190my_function_that_can_fail (GError **err)
191{
192  g_return_val_if_fail (err == NULL || *err == NULL, FALSE);
193
194  if (!sub_function_that_can_fail (err))
195    {
196       /* assert that error was set by the sub-function */
197       g_assert (err == NULL || *err != NULL);  
198       return FALSE;
199    }
200
201  /* otherwise continue, no error occurred */
202  g_assert (err == NULL || *err == NULL);
203}
204</programlisting></informalexample>
205</para>
206
207<para>
208If the sub-function does not indicate errors other than by reporting a <link linkend="GError"><type>GError</type></link>, 
209you need to create a temporary <link linkend="GError"><type>GError</type></link> since the passed-in one may be <link linkend="NULL:CAPS"><literal>NULL</literal></link>.
210<link linkend="g-propagate-error"><function>g_propagate_error()</function></link> is intended for use in this case.
211<informalexample><programlisting>
212gboolean
213my_function_that_can_fail (GError **err)
214{
215  GError *tmp_error;
216
217  g_return_val_if_fail (err == NULL || *err == NULL, FALSE);
218
219  tmp_error = NULL;
220  sub_function_that_can_fail (&amp;tmp_error);
221
222  if (tmp_error != NULL)
223    {
224       /* store tmp_error in err, if err != NULL,
225        * otherwise call g_error_free(<!-- -->) on tmp_error 
226        */
227       g_propagate_error (err, tmp_error);
228       return FALSE;
229    }
230
231  /* otherwise continue, no error occurred */
232}
233</programlisting></informalexample>
234</para>
235
236<para>
237Error pileups are always a bug. For example, this code is incorrect:
238<informalexample><programlisting>
239gboolean
240my_function_that_can_fail (GError **err)
241{
242  GError *tmp_error;
243
244  g_return_val_if_fail (err == NULL || *err == NULL, FALSE);
245
246  tmp_error = NULL;
247  sub_function_that_can_fail (&amp;tmp_error);
248  other_function_that_can_fail (&amp;tmp_error);
249
250  if (tmp_error != NULL)
251    {
252       g_propagate_error (err, tmp_error);
253       return FALSE;
254    }
255}
256</programlisting></informalexample>
257<literal>tmp_error</literal> should be checked immediately after
258<function><link linkend="sub-function-that-can-fail"><function>sub_function_that_can_fail()</function></link></function>, and either cleared or propagated upward.  The rule
259is: <emphasis>after each error, you must either handle the error, or return it to the
260calling function</emphasis>.  Note that passing <link linkend="NULL:CAPS"><literal>NULL</literal></link> for the error location is the
261equivalent of handling an error by always doing nothing about it. So the
262following code is fine, assuming errors in <function><link linkend="sub-function-that-can-fail"><function>sub_function_that_can_fail()</function></link></function> are not
263fatal to <function><link linkend="my-function-that-can-fail"><function>my_function_that_can_fail()</function></link></function>:
264<informalexample><programlisting>
265gboolean
266my_function_that_can_fail (GError **err)
267{
268  GError *tmp_error;
269
270  g_return_val_if_fail (err == NULL || *err == NULL, FALSE);
271
272  sub_function_that_can_fail (NULL); /* ignore errors */
273
274  tmp_error = NULL;
275  other_function_that_can_fail (&amp;tmp_error);
276
277  if (tmp_error != NULL)
278    {
279       g_propagate_error (err, tmp_error);
280       return FALSE;
281    }
282}
283</programlisting></informalexample>
284</para>
285
286<para>
287Note that passing <link linkend="NULL:CAPS"><literal>NULL</literal></link> for the error location <emphasis>ignores</emphasis>
288errors; it's equivalent to <literal>try { <link linkend="sub-function-that-can-fail"><function>sub_function_that_can_fail()</function></link>; } catch
289(...) {}</literal> in C++. It does <emphasis>not</emphasis> mean to leave errors
290unhandled; it means to handle them by doing nothing.
291</para>
292
293<para>
294Error domains and codes are conventionally named as follows:
295<itemizedlist>
296<listitem>
297<para>
298The error domain is called 
299<literal>&lt;NAMESPACE&gt;_&lt;MODULE&gt;_ERROR</literal>, for example
300<link linkend="G-SPAWN-ERROR:CAPS"><literal>G_SPAWN_ERROR</literal></link> or <link linkend="G-THREAD-ERROR:CAPS"><literal>G_THREAD_ERROR</literal></link>:
301<informalexample><programlisting>
302#define G_SPAWN_ERROR g_spawn_error_quark (<!-- -->)
303
304GQuark
305g_spawn_error_quark (void)
306{
307  return g_quark_from_static_string ("g-spawn-error-quark");
308}
309</programlisting></informalexample>
310</para>
311</listitem>
312<listitem>
313<para>
314The error codes are in an enumeration called 
315<literal>&lt;Namespace&gt;&lt;Module&gt;Error</literal>; for example,
316<link linkend="GThreadError"><type>GThreadError</type></link> or <link linkend="GSpawnError"><type>GSpawnError</type></link>.
317</para>
318</listitem>
319<listitem>
320<para>
321Members of the error code enumeration are called <literal>&lt;NAMESPACE&gt;_&lt;MODULE&gt;_ERROR_&lt;CODE&gt;</literal>, for example <link linkend="G-SPAWN-ERROR-FORK:CAPS"><literal>G_SPAWN_ERROR_FORK</literal></link> or <link linkend="G-THREAD-ERROR-AGAIN:CAPS"><literal>G_THREAD_ERROR_AGAIN</literal></link>. 
322</para>
323</listitem>
324<listitem>
325<para>
326If there's a "generic" or "unknown" error code for unrecoverable errors it
327doesn't make sense to distinguish with specific codes, it should be called 
328<literal>&lt;NAMESPACE&gt;_&lt;MODULE&gt;_ERROR_FAILED</literal>, for 
329example <link linkend="G-SPAWN-ERROR-FAILED:CAPS"><literal>G_SPAWN_ERROR_FAILED</literal></link> or <link linkend="G-THREAD-ERROR-FAILED:CAPS"><literal>G_THREAD_ERROR_FAILED</literal></link>.
330</para>
331</listitem>
332</itemizedlist>
333</para>
334
335<para>
336Summary of rules for use of <link linkend="GError--"><type>""</type></link>
337      <itemizedlist>
338	<listitem>
339	  <para>
340           Do not report programming errors via <link linkend="GError"><type>GError</type></link>.
341	  </para>
342	</listitem>
343
344      <listitem>
345        <para>
346          The last argument of a function that returns an error should be a
347          location where a <link linkend="GError"><type>GError</type></link> can be placed (i.e. "<link linkend="GError"><type>GError</type></link>** error").  If
348          <link linkend="GError"><type>GError</type></link> is used with varargs, the <link linkend="GError"><type>GError</type></link>** should be the last
349          argument before the "...".
350        </para>
351      </listitem>
352
353      <listitem>
354        <para>
355          The caller may pass <link linkend="NULL:CAPS"><literal>NULL</literal></link> for the <link linkend="GError"><type>GError</type></link>** if they are not interested
356          in details of the exact error that occurred.
357        </para>
358      </listitem>
359
360	<listitem>
361	  <para>
362           If <link linkend="NULL:CAPS"><literal>NULL</literal></link> is passed for the <link linkend="GError"><type>GError</type></link>** argument, then errors should 
363           not be returned to the caller, but your function should still 
364           abort and return if an error occurs. That is, control flow should
365           not be affected by whether the caller wants to get a <link linkend="GError"><type>GError</type></link>.
366	  </para>
367	</listitem>
368
369      <listitem>
370        <para>
371          If a <link linkend="GError"><type>GError</type></link> is reported, then your function by definition  
372          <emphasis>had a fatal failure and did not complete whatever it was supposed
373            to do</emphasis>. If the failure was not fatal, then you handled it
374          and you should not report it. If it was fatal, then you must report it 
375          and discontinue whatever you were doing immediately.
376        </para>
377      </listitem>
378
379	<listitem>
380	  <para>
381          A <link linkend="GError"><type>GError</type></link>* must be initialized to <link linkend="NULL:CAPS"><literal>NULL</literal></link> before passing its address to
382          a function that can report errors.
383	  </para>
384	</listitem>
385
386	<listitem>
387	  <para>
388          "Piling up" errors is always a bug. That is, if you assign a new
389          <link linkend="GError"><type>GError</type></link> to a <link linkend="GError"><type>GError</type></link>* that is non-<link linkend="NULL:CAPS"><literal>NULL</literal></link>, thus overwriting the previous
390          error, it indicates that you should have aborted the operation instead
391          of continuing. If you were able to continue, you should have cleared
392          the previous error with <link linkend="g-clear-error"><function>g_clear_error()</function></link>. <link linkend="g-set-error"><function>g_set_error()</function></link> will complain
393          if you pile up errors.
394	  </para>
395	</listitem>
396
397
398	<listitem>
399	  <para>
400          By convention, if you return a boolean value indicating success 
401          then <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> means success and <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> means failure. If <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> is returned,
402          the error <emphasis>must</emphasis> be set to a non-<link linkend="NULL:CAPS"><literal>NULL</literal></link> value. 
403        </para>
404	</listitem>
405
406
407	<listitem>
408	  <para>
409          A <link linkend="NULL:CAPS"><literal>NULL</literal></link> return value is also frequently used to mean that an error
410          occurred.  You should make clear in your documentation whether <link linkend="NULL:CAPS"><literal>NULL</literal></link> is
411          a valid return value in non-error cases; if <link linkend="NULL:CAPS"><literal>NULL</literal></link> is a valid value,
412          then users must check whether an error was returned to see if the
413          function succeeded.
414	  </para>
415	</listitem>
416
417	<listitem>
418	  <para>
419          When implementing a function that can report errors, you may want to
420          add a check at the top of your function that the error return location
421          is either <link linkend="NULL:CAPS"><literal>NULL</literal></link> or contains a <link linkend="NULL:CAPS"><literal>NULL</literal></link> error
422          (e.g. <literal>g_return_if_fail (error == NULL || *error ==
423          NULL);</literal>).
424	  </para>
425	</listitem>
426
427
428</itemizedlist>
429</para>
430</refsect1>
431
432<refsect1 id="glib-Error-Reporting.details" role="details">
433<title role="details.title">Details</title>
434<refsect2 id="GError" role="struct">
435<title>GError</title>
436<indexterm zone="GError"><primary>GError</primary></indexterm><programlisting>typedef struct {
437  GQuark       domain;
438  gint         code;
439  gchar       *message;
440} GError;
441</programlisting>
442<para>
443The <structname>GError</structname> structure contains 
444information about an error that has occurred.
445</para><variablelist role="struct">
446<varlistentry>
447<term><link linkend="GQuark">GQuark</link>&nbsp;<structfield>domain</structfield>;</term>
448<listitem><simpara>error domain, e.g. <link linkend="G-FILE-ERROR:CAPS"><type>G_FILE_ERROR</type></link>.
449</simpara></listitem>
450</varlistentry>
451<varlistentry>
452<term><link linkend="gint">gint</link>&nbsp;<structfield>code</structfield>;</term>
453<listitem><simpara>error code, e.g. <link linkend="G-FILE-ERROR-NOENT:CAPS"><literal>G_FILE_ERROR_NOENT</literal></link>.
454</simpara></listitem>
455</varlistentry>
456<varlistentry>
457<term><link linkend="gchar">gchar</link>&nbsp;*<structfield>message</structfield>;</term>
458<listitem><simpara>human-readable informative error message.
459
460</simpara></listitem>
461</varlistentry>
462</variablelist></refsect2>
463<refsect2 id="g-error-new" role="function">
464<title>g_error_new ()</title>
465<indexterm zone="g-error-new"><primary>g_error_new</primary></indexterm><programlisting><link linkend="GError">GError</link>*             g_error_new                         (<link linkend="GQuark">GQuark</link> domain,
466                                                         <link linkend="gint">gint</link> code,
467                                                         const <link linkend="gchar">gchar</link> *format,
468                                                         ...);</programlisting>
469<para>
470Creates a new <link linkend="GError"><type>GError</type></link> with the given <parameter>domain</parameter> and <parameter>code</parameter>,
471and a message formatted with <parameter>format</parameter>.</para>
472<para>
473
474</para><variablelist role="params">
475<varlistentry><term><parameter>domain</parameter>&nbsp;:</term>
476<listitem><simpara> error domain 
477</simpara></listitem></varlistentry>
478<varlistentry><term><parameter>code</parameter>&nbsp;:</term>
479<listitem><simpara> error code
480</simpara></listitem></varlistentry>
481<varlistentry><term><parameter>format</parameter>&nbsp;:</term>
482<listitem><simpara> <link linkend="printf"><function>printf()</function></link>-style format for error message
483</simpara></listitem></varlistentry>
484<varlistentry><term><parameter>...</parameter>&nbsp;:</term>
485<listitem><simpara> parameters for message format
486</simpara></listitem></varlistentry>
487<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> a new <link linkend="GError"><type>GError</type></link>
488</simpara></listitem></varlistentry>
489</variablelist></refsect2>
490<refsect2 id="g-error-new-literal" role="function">
491<title>g_error_new_literal ()</title>
492<indexterm zone="g-error-new-literal"><primary>g_error_new_literal</primary></indexterm><programlisting><link linkend="GError">GError</link>*             g_error_new_literal                 (<link linkend="GQuark">GQuark</link> domain,
493                                                         <link linkend="gint">gint</link> code,
494                                                         const <link linkend="gchar">gchar</link> *message);</programlisting>
495<para>
496Creates a new <link linkend="GError"><type>GError</type></link>; unlike <link linkend="g-error-new"><function>g_error_new()</function></link>, <parameter>message</parameter> is not
497a <link linkend="printf"><function>printf()</function></link>-style format string. Use this 
498function if <parameter>message</parameter> contains text you don't have control over, 
499that could include <link linkend="printf"><function>printf()</function></link> escape sequences.</para>
500<para>
501
502</para><variablelist role="params">
503<varlistentry><term><parameter>domain</parameter>&nbsp;:</term>
504<listitem><simpara> error domain
505</simpara></listitem></varlistentry>
506<varlistentry><term><parameter>code</parameter>&nbsp;:</term>
507<listitem><simpara> error code
508</simpara></listitem></varlistentry>
509<varlistentry><term><parameter>message</parameter>&nbsp;:</term>
510<listitem><simpara> error message
511</simpara></listitem></varlistentry>
512<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> a new <link linkend="GError"><type>GError</type></link>
513</simpara></listitem></varlistentry>
514</variablelist></refsect2>
515<refsect2 id="g-error-free" role="function">
516<title>g_error_free ()</title>
517<indexterm zone="g-error-free"><primary>g_error_free</primary></indexterm><programlisting><link linkend="void">void</link>                g_error_free                        (<link linkend="GError">GError</link> *error);</programlisting>
518<para>
519Frees a <link linkend="GError"><type>GError</type></link> and associated resources.</para>
520<para>
521
522</para><variablelist role="params">
523<varlistentry><term><parameter>error</parameter>&nbsp;:</term>
524<listitem><simpara> a <link linkend="GError"><type>GError</type></link>
525</simpara></listitem></varlistentry>
526</variablelist></refsect2>
527<refsect2 id="g-error-copy" role="function">
528<title>g_error_copy ()</title>
529<indexterm zone="g-error-copy"><primary>g_error_copy</primary></indexterm><programlisting><link linkend="GError">GError</link>*             g_error_copy                        (const <link linkend="GError">GError</link> *error);</programlisting>
530<para>
531Makes a copy of <parameter>error</parameter>.</para>
532<para>
533
534</para><variablelist role="params">
535<varlistentry><term><parameter>error</parameter>&nbsp;:</term>
536<listitem><simpara> a <link linkend="GError"><type>GError</type></link>
537</simpara></listitem></varlistentry>
538<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> a new <link linkend="GError"><type>GError</type></link>
539</simpara></listitem></varlistentry>
540</variablelist></refsect2>
541<refsect2 id="g-error-matches" role="function">
542<title>g_error_matches ()</title>
543<indexterm zone="g-error-matches"><primary>g_error_matches</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            g_error_matches                     (const <link linkend="GError">GError</link> *error,
544                                                         <link linkend="GQuark">GQuark</link> domain,
545                                                         <link linkend="gint">gint</link> code);</programlisting>
546<para>
547Returns <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if <parameter>error</parameter> matches <parameter>domain</parameter> and <parameter>code</parameter>, <link linkend="FALSE:CAPS"><literal>FALSE</literal></link>
548otherwise.</para>
549<para>
550
551</para><variablelist role="params">
552<varlistentry><term><parameter>error</parameter>&nbsp;:</term>
553<listitem><simpara> a <link linkend="GError"><type>GError</type></link>
554</simpara></listitem></varlistentry>
555<varlistentry><term><parameter>domain</parameter>&nbsp;:</term>
556<listitem><simpara> an error domain
557</simpara></listitem></varlistentry>
558<varlistentry><term><parameter>code</parameter>&nbsp;:</term>
559<listitem><simpara> an error code
560</simpara></listitem></varlistentry>
561<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> whether <parameter>error</parameter> has <parameter>domain</parameter> and <parameter>code</parameter>
562</simpara></listitem></varlistentry>
563</variablelist></refsect2>
564<refsect2 id="g-set-error" role="function">
565<title>g_set_error ()</title>
566<indexterm zone="g-set-error"><primary>g_set_error</primary></indexterm><programlisting><link linkend="void">void</link>                g_set_error                         (<link linkend="GError">GError</link> **err,
567                                                         <link linkend="GQuark">GQuark</link> domain,
568                                                         <link linkend="gint">gint</link> code,
569                                                         const <link linkend="gchar">gchar</link> *format,
570                                                         ...);</programlisting>
571<para>
572Does nothing if <parameter>err</parameter> is <link linkend="NULL:CAPS"><literal>NULL</literal></link>; if <parameter>err</parameter> is non-<link linkend="NULL:CAPS"><literal>NULL</literal></link>, then *<parameter>err</parameter> must
573be <link linkend="NULL:CAPS"><literal>NULL</literal></link>. A new <link linkend="GError"><type>GError</type></link> is created and assigned to *<parameter>err</parameter>.</para>
574<para>
575
576</para><variablelist role="params">
577<varlistentry><term><parameter>err</parameter>&nbsp;:</term>
578<listitem><simpara> a return location for a <link linkend="GError"><type>GError</type></link>, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>
579</simpara></listitem></varlistentry>
580<varlistentry><term><parameter>domain</parameter>&nbsp;:</term>
581<listitem><simpara> error domain
582</simpara></listitem></varlistentry>
583<varlistentry><term><parameter>code</parameter>&nbsp;:</term>
584<listitem><simpara> error code 
585</simpara></listitem></varlistentry>
586<varlistentry><term><parameter>format</parameter>&nbsp;:</term>
587<listitem><simpara> <link linkend="printf"><function>printf()</function></link>-style format
588</simpara></listitem></varlistentry>
589<varlistentry><term><parameter>...</parameter>&nbsp;:</term>
590<listitem><simpara> args for <parameter>format</parameter> 
591</simpara></listitem></varlistentry>
592</variablelist></refsect2>
593<refsect2 id="g-propagate-error" role="function">
594<title>g_propagate_error ()</title>
595<indexterm zone="g-propagate-error"><primary>g_propagate_error</primary></indexterm><programlisting><link linkend="void">void</link>                g_propagate_error                   (<link linkend="GError">GError</link> **dest,
596                                                         <link linkend="GError">GError</link> *src);</programlisting>
597<para>
598If <parameter>dest</parameter> is <link linkend="NULL:CAPS"><literal>NULL</literal></link>, free <parameter>src</parameter>; otherwise, moves <parameter>src</parameter> into *<parameter>dest</parameter>.
599The error variable <parameter>dest</parameter> points to must be <link linkend="NULL:CAPS"><literal>NULL</literal></link>.</para>
600<para>
601
602</para><variablelist role="params">
603<varlistentry><term><parameter>dest</parameter>&nbsp;:</term>
604<listitem><simpara> error return location
605</simpara></listitem></varlistentry>
606<varlistentry><term><parameter>src</parameter>&nbsp;:</term>
607<listitem><simpara> error to move into the return location
608</simpara></listitem></varlistentry>
609</variablelist></refsect2>
610<refsect2 id="g-clear-error" role="function">
611<title>g_clear_error ()</title>
612<indexterm zone="g-clear-error"><primary>g_clear_error</primary></indexterm><programlisting><link linkend="void">void</link>                g_clear_error                       (<link linkend="GError">GError</link> **err);</programlisting>
613<para>
614If <parameter>err</parameter> is <link linkend="NULL:CAPS"><literal>NULL</literal></link>, does nothing. If <parameter>err</parameter> is non-<link linkend="NULL:CAPS"><literal>NULL</literal></link>,
615calls <link linkend="g-error-free"><function>g_error_free()</function></link> on *<parameter>err</parameter> and sets *<parameter>err</parameter> to <link linkend="NULL:CAPS"><literal>NULL</literal></link>.</para>
616<para>
617
618</para><variablelist role="params">
619<varlistentry><term><parameter>err</parameter>&nbsp;:</term>
620<listitem><simpara> a <link linkend="GError"><type>GError</type></link> return location
621</simpara></listitem></varlistentry>
622</variablelist></refsect2>
623<refsect2 id="g-prefix-error" role="function" condition="since:2.16">
624<title>g_prefix_error ()</title>
625<indexterm zone="g-prefix-error" role="2.16"><primary>g_prefix_error</primary></indexterm><programlisting><link linkend="void">void</link>                g_prefix_error                      (<link linkend="GError">GError</link> **err,
626                                                         const <link linkend="gchar">gchar</link> *format,
627                                                         ...);</programlisting>
628<para>
629Formats a string according to <parameter>format</parameter> and
630prefix it to an existing error message.  If
631<parameter>err</parameter> is <link linkend="NULL:CAPS"><literal>NULL</literal></link> (ie: no error variable) then do
632nothing.
633</para>
634<para>
635If *<parameter>err</parameter> is <link linkend="NULL:CAPS"><literal>NULL</literal></link> (ie: an error variable is
636present but there is no error condition) then
637also do nothing.  Whether or not it makes
638sense to take advantage of this feature is up
639to you.</para>
640<para>
641
642</para><variablelist role="params">
643<varlistentry><term><parameter>err</parameter>&nbsp;:</term>
644<listitem><simpara> a return location for a <link linkend="GError"><type>GError</type></link>, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>
645</simpara></listitem></varlistentry>
646<varlistentry><term><parameter>format</parameter>&nbsp;:</term>
647<listitem><simpara> <link linkend="printf"><function>printf()</function></link>-style format string
648</simpara></listitem></varlistentry>
649<varlistentry><term><parameter>...</parameter>&nbsp;:</term>
650<listitem><simpara> arguments to <parameter>format</parameter>
651</simpara></listitem></varlistentry>
652</variablelist><para role="since">Since  2.16
653</para></refsect2>
654<refsect2 id="g-propagate-prefixed-error" role="function" condition="since:2.16">
655<title>g_propagate_prefixed_error ()</title>
656<indexterm zone="g-propagate-prefixed-error" role="2.16"><primary>g_propagate_prefixed_error</primary></indexterm><programlisting><link linkend="void">void</link>                g_propagate_prefixed_error          (<link linkend="GError">GError</link> **dest,
657                                                         <link linkend="GError">GError</link> *src,
658                                                         const <link linkend="gchar">gchar</link> *format,
659                                                         ...);</programlisting>
660<para>
661If <parameter>dest</parameter> is <link linkend="NULL:CAPS"><literal>NULL</literal></link>, free <parameter>src</parameter>; otherwise,
662moves <parameter>src</parameter> into *<parameter>dest</parameter>. *<parameter>dest</parameter> must be <link linkend="NULL:CAPS"><literal>NULL</literal></link>.
663After the move, add a prefix as with 
664<link linkend="g-prefix-error"><function>g_prefix_error()</function></link>.</para>
665<para>
666
667</para><variablelist role="params">
668<varlistentry><term><parameter>dest</parameter>&nbsp;:</term>
669<listitem><simpara> error return location
670</simpara></listitem></varlistentry>
671<varlistentry><term><parameter>src</parameter>&nbsp;:</term>
672<listitem><simpara> error to move into the return location
673</simpara></listitem></varlistentry>
674<varlistentry><term><parameter>format</parameter>&nbsp;:</term>
675<listitem><simpara> <link linkend="printf"><function>printf()</function></link>-style format string
676</simpara></listitem></varlistentry>
677<varlistentry><term><parameter>...</parameter>&nbsp;:</term>
678<listitem><simpara> arguments to <parameter>format</parameter>
679</simpara></listitem></varlistentry>
680</variablelist><para role="since">Since  2.16
681</para></refsect2>
682
683</refsect1>
684
685
686
687
688</refentry>