4
4
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
5
5
<title>Error Reporting</title>
6
<meta name="generator" content="DocBook XSL Stylesheets V1.74.3">
6
<meta name="generator" content="DocBook XSL Stylesheets V1.75.1">
7
7
<link rel="home" href="index.html" title="GLib Reference Manual">
8
8
<link rel="up" href="glib-core.html" title="GLib Core Application Support">
9
9
<link rel="prev" href="glib-IO-Channels.html" title="IO Channels">
44
44
<a href="#glib-Error-Reporting.description" class="shortcut">Description</a>
47
<div class="refentry" lang="en">
47
<div class="refentry" title="Error Reporting">
48
48
<a name="glib-Error-Reporting"></a><div class="titlepage"></div>
49
49
<div class="refnamediv"><table width="100%"><tr>
96
<div class="refsect1" lang="en">
96
<div class="refsect1" title="Description">
97
97
<a name="glib-Error-Reporting.description"></a><h2>Description</h2>
99
99
GLib provides a standard method of reporting errors from a called function to
319
319
Error domains and codes are conventionally named as follows:
321
<div class="itemizedlist"><ul type="disc">
321
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
322
<li class="listitem">
324
324
The error domain is called
325
325
<code class="literal"><NAMESPACE>_<MODULE>_ERROR</code>, for example
339
<li class="listitem"><p>
340
340
The error codes are in an enumeration called
341
341
<code class="literal"><Namespace><Module>Error</code>; for example,
342
342
<a class="link" href="glib-Threads.html#GThreadError" title="enum GThreadError"><span class="type">GThreadError</span></a> or <a class="link" href="glib-Spawning-Processes.html#GSpawnError" title="enum GSpawnError"><span class="type">GSpawnError</span></a>.
344
<li class="listitem"><p>
345
345
Members of the error code enumeration are called <code class="literal"><NAMESPACE>_<MODULE>_ERROR_<CODE></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>.
347
<li class="listitem"><p>
348
348
If there's a "generic" or "unknown" error code for unrecoverable errors it
349
349
doesn't make sense to distinguish with specific codes, it should be called
350
350
<code class="literal"><NAMESPACE>_<MODULE>_ERROR_FAILED</code>, for
357
357
Summary of rules for use of <span class="type">""</span>
359
<div class="itemizedlist"><ul type="disc">
359
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
360
<li class="listitem"><p>
361
361
Do not report programming errors via <a class="link" href="glib-Error-Reporting.html#GError" title="GError"><span class="type">GError</span></a>.
363
<li class="listitem"><p>
364
364
The last argument of a function that returns an error should be a
365
365
location where a <a class="link" href="glib-Error-Reporting.html#GError" title="GError"><span class="type">GError</span></a> can be placed (i.e. "<a class="link" href="glib-Error-Reporting.html#GError" title="GError"><span class="type">GError</span></a>** error"). If
366
366
<a class="link" href="glib-Error-Reporting.html#GError" title="GError"><span class="type">GError</span></a> is used with varargs, the <a class="link" href="glib-Error-Reporting.html#GError" title="GError"><span class="type">GError</span></a>** should be the last
367
367
argument before the "...".
369
<li class="listitem"><p>
370
370
The caller may pass <a class="link" href="glib-Standard-Macros.html#NULL--CAPS" title="NULL"><code class="literal">NULL</code></a> for the <a class="link" href="glib-Error-Reporting.html#GError" title="GError"><span class="type">GError</span></a>** if they are not interested
371
371
in details of the exact error that occurred.
373
<li class="listitem"><p>
374
374
If <a class="link" href="glib-Standard-Macros.html#NULL--CAPS" title="NULL"><code class="literal">NULL</code></a> is passed for the <a class="link" href="glib-Error-Reporting.html#GError" title="GError"><span class="type">GError</span></a>** argument, then errors should
375
375
not be returned to the caller, but your function should still
376
376
abort and return if an error occurs. That is, control flow should
377
377
not be affected by whether the caller wants to get a <a class="link" href="glib-Error-Reporting.html#GError" title="GError"><span class="type">GError</span></a>.
379
<li class="listitem"><p>
380
380
If a <a class="link" href="glib-Error-Reporting.html#GError" title="GError"><span class="type">GError</span></a> is reported, then your function by definition
381
381
<span class="emphasis"><em>had a fatal failure and did not complete whatever it was supposed
382
382
to do</em></span>. If the failure was not fatal, then you handled it
383
383
and you should not report it. If it was fatal, then you must report it
384
384
and discontinue whatever you were doing immediately.
386
<li class="listitem"><p>
387
387
A <a class="link" href="glib-Error-Reporting.html#GError" title="GError"><span class="type">GError</span></a>* must be initialized to <a class="link" href="glib-Standard-Macros.html#NULL--CAPS" title="NULL"><code class="literal">NULL</code></a> before passing its address to
388
388
a function that can report errors.
390
<li class="listitem"><p>
391
391
"Piling up" errors is always a bug. That is, if you assign a new
392
392
<a class="link" href="glib-Error-Reporting.html#GError" title="GError"><span class="type">GError</span></a> to a <a class="link" href="glib-Error-Reporting.html#GError" title="GError"><span class="type">GError</span></a>* that is non-<a class="link" href="glib-Standard-Macros.html#NULL--CAPS" title="NULL"><code class="literal">NULL</code></a>, thus overwriting the previous
393
393
error, it indicates that you should have aborted the operation instead
395
395
the previous error with <a class="link" href="glib-Error-Reporting.html#g-clear-error" title="g_clear_error ()"><code class="function">g_clear_error()</code></a>. <a class="link" href="glib-Error-Reporting.html#g-set-error" title="g_set_error ()"><code class="function">g_set_error()</code></a> will complain
396
396
if you pile up errors.
398
<li class="listitem"><p>
399
399
By convention, if you return a boolean value indicating success
400
400
then <a class="link" href="glib-Standard-Macros.html#TRUE--CAPS" title="TRUE"><code class="literal">TRUE</code></a> means success and <a class="link" href="glib-Standard-Macros.html#FALSE--CAPS" title="FALSE"><code class="literal">FALSE</code></a> means failure. If <a class="link" href="glib-Standard-Macros.html#FALSE--CAPS" title="FALSE"><code class="literal">FALSE</code></a> is returned,
401
401
the error <span class="emphasis"><em>must</em></span> be set to a non-<a class="link" href="glib-Standard-Macros.html#NULL--CAPS" title="NULL"><code class="literal">NULL</code></a> value.
403
<li class="listitem"><p>
404
404
A <a class="link" href="glib-Standard-Macros.html#NULL--CAPS" title="NULL"><code class="literal">NULL</code></a> return value is also frequently used to mean that an error
405
405
occurred. You should make clear in your documentation whether <a class="link" href="glib-Standard-Macros.html#NULL--CAPS" title="NULL"><code class="literal">NULL</code></a> is
406
406
a valid return value in non-error cases; if <a class="link" href="glib-Standard-Macros.html#NULL--CAPS" title="NULL"><code class="literal">NULL</code></a> is a valid value,
407
407
then users must check whether an error was returned to see if the
408
408
function succeeded.
410
<li class="listitem"><p>
411
411
When implementing a function that can report errors, you may want to
412
412
add a check at the top of your function that the error return location
413
413
is either <a class="link" href="glib-Standard-Macros.html#NULL--CAPS" title="NULL"><code class="literal">NULL</code></a> or contains a <a class="link" href="glib-Standard-Macros.html#NULL--CAPS" title="NULL"><code class="literal">NULL</code></a> error
421
<div class="refsect1" lang="en">
421
<div class="refsect1" title="Details">
422
422
<a name="glib-Error-Reporting.details"></a><h2>Details</h2>
423
<div class="refsect2" lang="en">
423
<div class="refsect2" title="GError">
424
424
<a name="GError"></a><h3>GError</h3>
425
425
<pre class="programlisting">typedef struct {
457
<div class="refsect2" lang="en">
457
<div class="refsect2" title="g_error_new ()">
458
458
<a name="g-error-new"></a><h3>g_error_new ()</h3>
459
459
<pre class="programlisting"><a class="link" href="glib-Error-Reporting.html#GError" title="GError">GError</a>* g_error_new (<a class="link" href="glib-Quarks.html#GQuark" title="GQuark">GQuark</a> domain,
460
460
<a class="link" href="glib-Basic-Types.html#gint" title="gint">gint</a> code,
500
<div class="refsect2" lang="en">
500
<div class="refsect2" title="g_error_new_literal ()">
501
501
<a name="g-error-new-literal"></a><h3>g_error_new_literal ()</h3>
502
502
<pre class="programlisting"><a class="link" href="glib-Error-Reporting.html#GError" title="GError">GError</a>* g_error_new_literal (<a class="link" href="glib-Quarks.html#GQuark" title="GQuark">GQuark</a> domain,
503
503
<a class="link" href="glib-Basic-Types.html#gint" title="gint">gint</a> code,
539
<div class="refsect2" lang="en">
539
<div class="refsect2" title="g_error_free ()">
540
540
<a name="g-error-free"></a><h3>g_error_free ()</h3>
541
541
<pre class="programlisting">void g_error_free (<a class="link" href="glib-Error-Reporting.html#GError" title="GError">GError</a> *error);</pre>
556
<div class="refsect2" lang="en">
556
<div class="refsect2" title="g_error_copy ()">
557
557
<a name="g-error-copy"></a><h3>g_error_copy ()</h3>
558
558
<pre class="programlisting"><a class="link" href="glib-Error-Reporting.html#GError" title="GError">GError</a>* g_error_copy (const <a class="link" href="glib-Error-Reporting.html#GError" title="GError">GError</a> *error);</pre>
580
<div class="refsect2" lang="en">
580
<div class="refsect2" title="g_error_matches ()">
581
581
<a name="g-error-matches"></a><h3>g_error_matches ()</h3>
582
582
<pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean">gboolean</a> g_error_matches (const <a class="link" href="glib-Error-Reporting.html#GError" title="GError">GError</a> *error,
583
583
<a class="link" href="glib-Quarks.html#GQuark" title="GQuark">GQuark</a> domain,
617
<div class="refsect2" lang="en">
617
<div class="refsect2" title="g_set_error ()">
618
618
<a name="g-set-error"></a><h3>g_set_error ()</h3>
619
619
<pre class="programlisting">void g_set_error (<a class="link" href="glib-Error-Reporting.html#GError" title="GError">GError</a> **err,
620
620
<a class="link" href="glib-Quarks.html#GQuark" title="GQuark">GQuark</a> domain,
661
<div class="refsect2" lang="en">
661
<div class="refsect2" title="g_set_error_literal ()">
662
662
<a name="g-set-error-literal"></a><h3>g_set_error_literal ()</h3>
663
663
<pre class="programlisting">void g_set_error_literal (<a class="link" href="glib-Error-Reporting.html#GError" title="GError">GError</a> **err,
664
664
<a class="link" href="glib-Quarks.html#GQuark" title="GQuark">GQuark</a> domain,
700
700
<p class="since">Since 2.18</p>
703
<div class="refsect2" lang="en">
703
<div class="refsect2" title="g_propagate_error ()">
704
704
<a name="g-propagate-error"></a><h3>g_propagate_error ()</h3>
705
705
<pre class="programlisting">void g_propagate_error (<a class="link" href="glib-Error-Reporting.html#GError" title="GError">GError</a> **dest,
706
706
<a class="link" href="glib-Error-Reporting.html#GError" title="GError">GError</a> *src);</pre>
729
<div class="refsect2" lang="en">
729
<div class="refsect2" title="g_clear_error ()">
730
730
<a name="g-clear-error"></a><h3>g_clear_error ()</h3>
731
731
<pre class="programlisting">void g_clear_error (<a class="link" href="glib-Error-Reporting.html#GError" title="GError">GError</a> **err);</pre>
747
<div class="refsect2" lang="en">
747
<div class="refsect2" title="g_prefix_error ()">
748
748
<a name="g-prefix-error"></a><h3>g_prefix_error ()</h3>
749
749
<pre class="programlisting">void g_prefix_error (<a class="link" href="glib-Error-Reporting.html#GError" title="GError">GError</a> **err,
750
750
const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar">gchar</a> *format,
786
786
<p class="since">Since 2.16</p>
789
<div class="refsect2" lang="en">
789
<div class="refsect2" title="g_propagate_prefixed_error ()">
790
790
<a name="g-propagate-prefixed-error"></a><h3>g_propagate_prefixed_error ()</h3>
791
791
<pre class="programlisting">void g_propagate_prefixed_error (<a class="link" href="glib-Error-Reporting.html#GError" title="GError">GError</a> **dest,
792
792
<a class="link" href="glib-Error-Reporting.html#GError" title="GError">GError</a> *src,
added
removed
docs/reference/glib/html/glib-Error-Reporting.html
