PageRenderTime 74ms CodeModel.GetById 10ms RepoModel.GetById 0ms app.codeStats 1ms

/glib-2.25.17/docs/reference/glib/html/glib-Error-Reporting.html

https://bitbucket.org/ArminW/3p-glib
HTML | 1026 lines | 1015 code | 11 blank | 0 comment | 0 complexity | 69f4f01d0b03c5fc7ff16887ee124d1c MD5 | raw file
Possible License(s): AGPL-3.0, LGPL-2.0 
    

  1. <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
    2. 

  2. <html>
    3. 

  3. <head>
    4. 

  4. <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
    5. 

  5. <title>Error Reporting</title>
    6. 

  6. <meta name="generator" content="DocBook XSL Stylesheets V1.75.2">
    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">
    10. 

  10. <link rel="next" href="glib-Warnings-and-Assertions.html" title="Message Output and Debugging Functions">
    11. 

  11. <meta name="generator" content="GTK-Doc V1.15.1 (XML mode)">
    12. 

  12. <link rel="stylesheet" href="style.css" type="text/css">
    13. 

  13. </head>
    14. 

  14. <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
    15. 

  15. <table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2">
    16. 

  16. <tr valign="middle">
    17. 

  17. <td><a accesskey="p" href="glib-IO-Channels.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
    18. 

  18. <td><a accesskey="u" href="glib-core.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
    19. 

  19. <td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
    20. 

  20. <th width="100%" align="center">GLib Reference Manual</th>
    21. 

  21. <td><a accesskey="n" href="glib-Warnings-and-Assertions.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
    22. 

  22. </tr>
    23. 

  23. <tr><td colspan="5" class="shortcuts">
    24. 

  24. <a href="#glib-Error-Reporting.synopsis" class="shortcut">Top</a>
    25. 

  25.                    | 
    26. 

  26.                   <a href="#glib-Error-Reporting.description" class="shortcut">Description</a>
    27. 

  27. </td></tr>
    28. 

  28. </table>
    29. 

  29. <div class="refentry">
    30. 

  30. <a name="glib-Error-Reporting"></a><div class="titlepage"></div>
    31. 

  31. <div class="refnamediv"><table width="100%"><tr>
    32. 

  32. <td valign="top">
    33. 

  33. <h2><span class="refentrytitle"><a name="glib-Error-Reporting.top_of_page"></a>Error Reporting</span></h2>
    34. 

  34. <p>Error Reporting — a system for reporting errors</p>
    35. 

  35. </td>
    36. 

  36. <td valign="top" align="right"></td>
    37. 

  37. </tr></table></div>
    38. 

  38. <div class="refsynopsisdiv">
    39. 

  39. <a name="glib-Error-Reporting.synopsis"></a><h2>Synopsis</h2>
    40. 

  40. <pre class="synopsis">
    41. 

  41. #include &lt;glib.h&gt;
    42. 

  42. 

  43.                     <a class="link" href="glib-Error-Reporting.html#GError" title="GError">GError</a>;
    44. 

  44. <a class="link" href="glib-Error-Reporting.html#GError" title="GError"><span class="returnvalue">GError</span></a> *            <a class="link" href="glib-Error-Reporting.html#g-error-new" title="g_error_new ()">g_error_new</a>                         (<em class="parameter"><code><a class="link" href="glib-Quarks.html#GQuark" title="GQuark"><span class="type">GQuark</span></a> domain</code></em>,
    45. 

  45.                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="type">gint</span></a> code</code></em>,
    46. 

  46.                                                          <em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *format</code></em>,
    47. 

  47.                                                          <em class="parameter"><code>...</code></em>);
    48. 

  48. <a class="link" href="glib-Error-Reporting.html#GError" title="GError"><span class="returnvalue">GError</span></a> *            <a class="link" href="glib-Error-Reporting.html#g-error-new-literal" title="g_error_new_literal ()">g_error_new_literal</a>                 (<em class="parameter"><code><a class="link" href="glib-Quarks.html#GQuark" title="GQuark"><span class="type">GQuark</span></a> domain</code></em>,
    49. 

  49.                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="type">gint</span></a> code</code></em>,
    50. 

  50.                                                          <em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *message</code></em>);
    51. 

  51. <a class="link" href="glib-Error-Reporting.html#GError" title="GError"><span class="returnvalue">GError</span></a> *            <a class="link" href="glib-Error-Reporting.html#g-error-new-valist" title="g_error_new_valist ()">g_error_new_valist</a>                  (<em class="parameter"><code><a class="link" href="glib-Quarks.html#GQuark" title="GQuark"><span class="type">GQuark</span></a> domain</code></em>,
    52. 

  52.                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="type">gint</span></a> code</code></em>,
    53. 

  53.                                                          <em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *format</code></em>,
    54. 

  54.                                                          <em class="parameter"><code><span class="type">va_list</span> args</code></em>);
    55. 

  55. <span class="returnvalue">void</span>                <a class="link" href="glib-Error-Reporting.html#g-error-free" title="g_error_free ()">g_error_free</a>                        (<em class="parameter"><code><a class="link" href="glib-Error-Reporting.html#GError" title="GError"><span class="type">GError</span></a> *error</code></em>);
    56. 

  56. <a class="link" href="glib-Error-Reporting.html#GError" title="GError"><span class="returnvalue">GError</span></a> *            <a class="link" href="glib-Error-Reporting.html#g-error-copy" title="g_error_copy ()">g_error_copy</a>                        (<em class="parameter"><code>const <a class="link" href="glib-Error-Reporting.html#GError" title="GError"><span class="type">GError</span></a> *error</code></em>);
    57. 

  57. <a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            <a class="link" href="glib-Error-Reporting.html#g-error-matches" title="g_error_matches ()">g_error_matches</a>                     (<em class="parameter"><code>const <a class="link" href="glib-Error-Reporting.html#GError" title="GError"><span class="type">GError</span></a> *error</code></em>,
    58. 

  58.                                                          <em class="parameter"><code><a class="link" href="glib-Quarks.html#GQuark" title="GQuark"><span class="type">GQuark</span></a> domain</code></em>,
    59. 

  59.                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="type">gint</span></a> code</code></em>);
    60. 

  60. <span class="returnvalue">void</span>                <a class="link" href="glib-Error-Reporting.html#g-set-error" title="g_set_error ()">g_set_error</a>                         (<em class="parameter"><code><a class="link" href="glib-Error-Reporting.html#GError" title="GError"><span class="type">GError</span></a> **err</code></em>,
    61. 

  61.                                                          <em class="parameter"><code><a class="link" href="glib-Quarks.html#GQuark" title="GQuark"><span class="type">GQuark</span></a> domain</code></em>,
    62. 

  62.                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="type">gint</span></a> code</code></em>,
    63. 

  63.                                                          <em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *format</code></em>,
    64. 

  64.                                                          <em class="parameter"><code>...</code></em>);
    65. 

  65. <span class="returnvalue">void</span>                <a class="link" href="glib-Error-Reporting.html#g-set-error-literal" title="g_set_error_literal ()">g_set_error_literal</a>                 (<em class="parameter"><code><a class="link" href="glib-Error-Reporting.html#GError" title="GError"><span class="type">GError</span></a> **err</code></em>,
    66. 

  66.                                                          <em class="parameter"><code><a class="link" href="glib-Quarks.html#GQuark" title="GQuark"><span class="type">GQuark</span></a> domain</code></em>,
    67. 

  67.                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="type">gint</span></a> code</code></em>,
    68. 

  68.                                                          <em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *message</code></em>);
    69. 

  69. <span class="returnvalue">void</span>                <a class="link" href="glib-Error-Reporting.html#g-propagate-error" title="g_propagate_error ()">g_propagate_error</a>                   (<em class="parameter"><code><a class="link" href="glib-Error-Reporting.html#GError" title="GError"><span class="type">GError</span></a> **dest</code></em>,
    70. 

  70.                                                          <em class="parameter"><code><a class="link" href="glib-Error-Reporting.html#GError" title="GError"><span class="type">GError</span></a> *src</code></em>);
    71. 

  71. <span class="returnvalue">void</span>                <a class="link" href="glib-Error-Reporting.html#g-clear-error" title="g_clear_error ()">g_clear_error</a>                       (<em class="parameter"><code><a class="link" href="glib-Error-Reporting.html#GError" title="GError"><span class="type">GError</span></a> **err</code></em>);
    72. 

  72. <span class="returnvalue">void</span>                <a class="link" href="glib-Error-Reporting.html#g-prefix-error" title="g_prefix_error ()">g_prefix_error</a>                      (<em class="parameter"><code><a class="link" href="glib-Error-Reporting.html#GError" title="GError"><span class="type">GError</span></a> **err</code></em>,
    73. 

  73.                                                          <em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *format</code></em>,
    74. 

  74.                                                          <em class="parameter"><code>...</code></em>);
    75. 

  75. <span class="returnvalue">void</span>                <a class="link" href="glib-Error-Reporting.html#g-propagate-prefixed-error" title="g_propagate_prefixed_error ()">g_propagate_prefixed_error</a>          (<em class="parameter"><code><a class="link" href="glib-Error-Reporting.html#GError" title="GError"><span class="type">GError</span></a> **dest</code></em>,
    76. 

  76.                                                          <em class="parameter"><code><a class="link" href="glib-Error-Reporting.html#GError" title="GError"><span class="type">GError</span></a> *src</code></em>,
    77. 

  77.                                                          <em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *format</code></em>,
    78. 

  78.                                                          <em class="parameter"><code>...</code></em>);
    79. 

  79. </pre>
    80. 

  80. </div>
    81. 

  81. <div class="refsect1">
    82. 

  82. <a name="glib-Error-Reporting.description"></a><h2>Description</h2>
    83. 

  83. <p>
    84. 

  84. GLib provides a standard method of reporting errors from a called function to
    85. 

  85. the calling code. (This is the same problem solved by exceptions in other
    86. 

  86. languages.) It's important to understand that this method is both a
    87. 

  87. <span class="emphasis"><em>data type</em></span> (the <a class="link" href="glib-Error-Reporting.html#GError" title="GError"><span class="type">GError</span></a> object) and a <span class="emphasis"><em>set of
    88. 

  88. rules.</em></span> If you use <a class="link" href="glib-Error-Reporting.html#GError" title="GError"><span class="type">GError</span></a> incorrectly, then your code will not
    89. 

  89. properly interoperate with other code that uses <a class="link" href="glib-Error-Reporting.html#GError" title="GError"><span class="type">GError</span></a>, and users of your API
    90. 

  90. will probably get confused.
    91. 

  91. </p>
    92. 

  92. <p>
    93. 

  93. First and foremost: <span class="emphasis"><em><a class="link" href="glib-Error-Reporting.html#GError" title="GError"><span class="type">GError</span></a> should only be used to report
    94. 

  94. recoverable runtime errors, never to report programming errors.</em></span> If
    95. 

  95. the programmer has screwed up, then you should use <a class="link" href="glib-Message-Logging.html#g-warning" title="g_warning ()"><code class="function">g_warning()</code></a>,
    96. 

  96. <a class="link" href="glib-Warnings-and-Assertions.html#g-return-if-fail" title="g_return_if_fail()"><code class="function">g_return_if_fail()</code></a>, <a class="link" href="glib-Testing.html#g-assert" title="g_assert()"><code class="function">g_assert()</code></a>, <a class="link" href="glib-Message-Logging.html#g-error" title="g_error ()"><code class="function">g_error()</code></a>, or some similar facility.
    97. 

  97. (Incidentally, remember that the <a class="link" href="glib-Message-Logging.html#g-error" title="g_error ()"><code class="function">g_error()</code></a> function should
    98. 

  98. <span class="emphasis"><em>only</em></span> be used for programming errors, it should not be used
    99. 

  99. to print any error reportable via <a class="link" href="glib-Error-Reporting.html#GError" title="GError"><span class="type">GError</span></a>.)
    100. 

  100. </p>
    101. 

  101. <p>
    102. 

  102. Examples of recoverable runtime errors are "file not found" or "failed to parse
    103. 

  103. input." Examples of programming errors are "NULL passed to <code class="function">strcmp()</code>" or
    104. 

  104. "attempted to free the same pointer twice." These two kinds of errors are
    105. 

  105. fundamentally different: runtime errors should be handled or reported to the
    106. 

  106. user, programming errors should be eliminated by fixing the bug in the program.
    107. 

  107. This is why most functions in GLib and GTK+ do not use the <a class="link" href="glib-Error-Reporting.html#GError" title="GError"><span class="type">GError</span></a> facility.
    108. 

  108. </p>
    109. 

  109. <p>
    110. 

  110. Functions that can fail take a return location for a <a class="link" href="glib-Error-Reporting.html#GError" title="GError"><span class="type">GError</span></a> as their last argument.
    111. 

  111. For example:
    112. 

  112. </p>
    113. 

  113. <div class="informalexample">
    114. 

  114.   <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
    115. 

  115.     <tbody>
    116. 

  116.       <tr>
    117. 

  117.         <td class="listing_lines" align="right"><pre>1
    118. 

  118. 2
    119. 

  119. 3
    120. 

  120. 4</pre></td>
    121. 

  121.         <td class="listing_code"><pre class="programlisting"><span class="usertype">gboolean</span><span class="normal"> </span><span class="function"><a href="glib-File-Utilities.html#g-file-get-contents">g_file_get_contents</a></span><span class="normal"> </span><span class="symbol">(</span><span class="keyword">const</span><span class="normal"> </span><span class="usertype">gchar</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">filename</span><span class="symbol">,</span>
    122. 

  122. <span class="normal">                          </span><span class="usertype">gchar</span><span class="normal">      </span><span class="symbol">**</span><span class="normal">contents</span><span class="symbol">,</span>
    123. 

  123. <span class="normal">                              </span><span class="usertype">gsize</span><span class="normal">       </span><span class="symbol">*</span><span class="normal">length</span><span class="symbol">,</span>
    124. 

  124. <span class="normal">                              </span><span class="usertype">GError</span><span class="normal">     </span><span class="symbol">**</span><span class="normal">error</span><span class="symbol">);</span></pre></td>
    125. 

  125.       </tr>
    126. 

  126.     </tbody>
    127. 

  127.   </table>
    128. 

  128. </div>
    129. 

  129. 

  130. <p>
    131. 

  131. If you pass a non-<a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> value for the <code class="literal">error</code> argument, it should
    132. 

  132. point to a location where an error can be placed. For example:
    133. 

  133. </p>
    134. 

  134. <div class="informalexample">
    135. 

  135.   <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
    136. 

  136.     <tbody>
    137. 

  137.       <tr>
    138. 

  138.         <td class="listing_lines" align="right"><pre>1
    139. 

  139. 2
    140. 

  140. 3
    141. 

  141. 4
    142. 

  142. 5
    143. 

  143. 6
    144. 

  144. 7
    145. 

  145. 8
    146. 

  146. 9
    147. 

  147. 10
    148. 

  148. 11
    149. 

  149. 12
    150. 

  150. 13
    151. 

  151. 14
    152. 

  152. 15
    153. 

  153. 16</pre></td>
    154. 

  154.         <td class="listing_code"><pre class="programlisting"><span class="usertype">gchar</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">contents</span><span class="symbol">;</span>
    155. 

  155. <span class="usertype">GError</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">err </span><span class="symbol">=</span><span class="normal"> <a href="glib-Standard-Macros.html#NULL:CAPS">NULL</a></span><span class="symbol">;</span>
    156. 

  156. <span class="function"><a href="glib-File-Utilities.html#g-file-get-contents">g_file_get_contents</a></span><span class="normal"> </span><span class="symbol">(</span><span class="string">"foo.txt"</span><span class="symbol">,</span><span class="normal"> </span><span class="symbol">&amp;</span><span class="normal">contents</span><span class="symbol">,</span><span class="normal"> <a href="glib-Standard-Macros.html#NULL:CAPS">NULL</a></span><span class="symbol">,</span><span class="normal"> </span><span class="symbol">&amp;</span><span class="normal">err</span><span class="symbol">);</span>
    157. 

  157. <span class="function"><a href="glib-Testing.html#g-assert">g_assert</a></span><span class="normal"> </span><span class="symbol">((</span><span class="normal">contents </span><span class="symbol">==</span><span class="normal"> <a href="glib-Standard-Macros.html#NULL:CAPS">NULL</a> </span><span class="symbol">&amp;&amp;</span><span class="normal"> err </span><span class="symbol">!=</span><span class="normal"> <a href="glib-Standard-Macros.html#NULL:CAPS">NULL</a></span><span class="symbol">)</span><span class="normal"> </span><span class="symbol">||</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">contents </span><span class="symbol">!=</span><span class="normal"> <a href="glib-Standard-Macros.html#NULL:CAPS">NULL</a> </span><span class="symbol">&amp;&amp;</span><span class="normal"> err </span><span class="symbol">==</span><span class="normal"> <a href="glib-Standard-Macros.html#NULL:CAPS">NULL</a></span><span class="symbol">));</span>
    158. 

  158. <span class="keyword">if</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">err </span><span class="symbol">!=</span><span class="normal"> <a href="glib-Standard-Macros.html#NULL:CAPS">NULL</a></span><span class="symbol">)</span>
    159. 

  159. <span class="normal">  </span><span class="cbracket">{</span>
    160. 

  160. <span class="normal">    </span><span class="comment">/* Report error to user, and free error */</span>
    161. 

  161. <span class="normal">    </span><span class="function"><a href="glib-Testing.html#g-assert">g_assert</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">contents </span><span class="symbol">==</span><span class="normal"> <a href="glib-Standard-Macros.html#NULL:CAPS">NULL</a></span><span class="symbol">);</span>
    162. 

  162. <span class="normal">    </span><span class="function">fprintf</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">stderr</span><span class="symbol">,</span><span class="normal"> </span><span class="string">"Unable to read file: %s</span><span class="specialchar">\n</span><span class="string">"</span><span class="symbol">,</span><span class="normal"> err</span><span class="symbol">-&gt;</span><span class="normal">message</span><span class="symbol">);</span>
    163. 

  163. <span class="normal">    </span><span class="function"><a href="glib-Error-Reporting.html#g-error-free">g_error_free</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">err</span><span class="symbol">);</span>
    164. 

  164. <span class="normal">  </span><span class="cbracket">}</span>
    165. 

  165. <span class="keyword">else</span>
    166. 

  166. <span class="normal">  </span><span class="cbracket">{</span>
    167. 

  167. <span class="normal">    </span><span class="comment">/* Use file contents */</span>
    168. 

  168. <span class="normal">    </span><span class="function"><a href="glib-Testing.html#g-assert">g_assert</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">contents </span><span class="symbol">!=</span><span class="normal"> <a href="glib-Standard-Macros.html#NULL:CAPS">NULL</a></span><span class="symbol">);</span>
    169. 

  169. <span class="normal">  </span><span class="cbracket">}</span></pre></td>
    170. 

  170.       </tr>
    171. 

  171.     </tbody>
    172. 

  172.   </table>
    173. 

  173. </div>
    174. 

  174. 

  175. <p>
    176. 

  176. Note that <code class="literal">err != NULL</code> in this example is a
    177. 

  177. <span class="emphasis"><em>reliable</em></span> indicator of whether
    178. 

  178. <a class="link" href="glib-File-Utilities.html#g-file-get-contents" title="g_file_get_contents ()"><code class="function">g_file_get_contents()</code></a> failed. Additionally, <a class="link" href="glib-File-Utilities.html#g-file-get-contents" title="g_file_get_contents ()"><code class="function">g_file_get_contents()</code></a> returns
    179. 

  179. a boolean which indicates whether it was successful.
    180. 

  180. </p>
    181. 

  181. <p>
    182. 

  182. Because <a class="link" href="glib-File-Utilities.html#g-file-get-contents" title="g_file_get_contents ()"><code class="function">g_file_get_contents()</code></a> returns <a class="link" href="glib-Standard-Macros.html#FALSE:CAPS" title="FALSE"><code class="literal">FALSE</code></a> on failure, if you are only
    183. 

  183. interested in whether it failed and don't need to display an error message, you
    184. 

  184. can pass <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> for the <code class="literal">error</code> argument:
    185. 

  185. </p>
    186. 

  186. <div class="informalexample">
    187. 

  187.   <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
    188. 

  188.     <tbody>
    189. 

  189.       <tr>
    190. 

  190.         <td class="listing_lines" align="right"><pre>1
    191. 

  191. 2
    192. 

  192. 3
    193. 

  193. 4</pre></td>
    194. 

  194.         <td class="listing_code"><pre class="programlisting"><span class="keyword">if</span><span class="normal"> </span><span class="symbol">(</span><span class="function"><a href="glib-File-Utilities.html#g-file-get-contents">g_file_get_contents</a></span><span class="normal"> </span><span class="symbol">(</span><span class="string">"foo.txt"</span><span class="symbol">,</span><span class="normal"> </span><span class="symbol">&amp;</span><span class="normal">contents</span><span class="symbol">,</span><span class="normal"> <a href="glib-Standard-Macros.html#NULL:CAPS">NULL</a></span><span class="symbol">,</span><span class="normal"> <a href="glib-Standard-Macros.html#NULL:CAPS">NULL</a></span><span class="symbol">))</span><span class="normal"> </span><span class="comment">/* ignore errors */</span>
    195. 

  195. <span class="normal">  </span><span class="comment">/* no error occurred */</span><span class="normal"> </span><span class="symbol">;</span>
    196. 

  196. <span class="keyword">else</span>
    197. 

  197. <span class="normal">  </span><span class="comment">/* error */</span><span class="normal"> </span><span class="symbol">;</span></pre></td>
    198. 

  198.       </tr>
    199. 

  199.     </tbody>
    200. 

  200.   </table>
    201. 

  201. </div>
    202. 

  202. 

  203. <p>
    204. 

  204. </p>
    205. 

  205. <p>
    206. 

  206. The <a class="link" href="glib-Error-Reporting.html#GError" title="GError"><span class="type">GError</span></a> object contains three fields: <code class="literal">domain</code> indicates
    207. 

  207. the module the error-reporting function is located in, <code class="literal">code</code>
    208. 

  208. indicates the specific error that occurred, and <code class="literal">message</code> is a
    209. 

  209. user-readable error message with as many details as possible. Several functions
    210. 

  210. are provided to deal with an error received from a called function:
    211. 

  211. <a class="link" href="glib-Error-Reporting.html#g-error-matches" title="g_error_matches ()"><code class="function">g_error_matches()</code></a> returns <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> if the error matches a given domain and code,
    212. 

  212. <a class="link" href="glib-Error-Reporting.html#g-propagate-error" title="g_propagate_error ()"><code class="function">g_propagate_error()</code></a> copies an error into an error location (so the calling
    213. 

  213. function will receive it), and <a class="link" href="glib-Error-Reporting.html#g-clear-error" title="g_clear_error ()"><code class="function">g_clear_error()</code></a> clears an error location by
    214. 

  214. freeing the error and resetting the location to <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>. To display an error to the
    215. 

  215. user, simply display <code class="literal">error-&gt;message</code>, perhaps along with
    216. 

  216. additional context known only to the calling function (the file being opened, or
    217. 

  217. whatever -- though in the <a class="link" href="glib-File-Utilities.html#g-file-get-contents" title="g_file_get_contents ()"><code class="function">g_file_get_contents()</code></a> case,
    218. 

  218. <code class="literal">error-&gt;message</code> already contains a filename).
    219. 

  219. </p>
    220. 

  220. <p>
    221. 

  221. When implementing a function that can report errors, the basic tool is
    222. 

  222. <a class="link" href="glib-Error-Reporting.html#g-set-error" title="g_set_error ()"><code class="function">g_set_error()</code></a>. Typically, if a fatal error occurs you want to <a class="link" href="glib-Error-Reporting.html#g-set-error" title="g_set_error ()"><code class="function">g_set_error()</code></a>,
    223. 

  223. then return immediately. <a class="link" href="glib-Error-Reporting.html#g-set-error" title="g_set_error ()"><code class="function">g_set_error()</code></a> does nothing if the error location passed
    224. 

  224. to it is <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>. Here's an example:
    225. 

  225. </p>
    226. 

  226. <div class="informalexample">
    227. 

  227.   <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
    228. 

  228.     <tbody>
    229. 

  229.       <tr>
    230. 

  230.         <td class="listing_lines" align="right"><pre>1
    231. 

  231. 2
    232. 

  232. 3
    233. 

  233. 4
    234. 

  234. 5
    235. 

  235. 6
    236. 

  236. 7
    237. 

  237. 8
    238. 

  238. 9
    239. 

  239. 10
    240. 

  240. 11
    241. 

  241. 12
    242. 

  242. 13
    243. 

  243. 14
    244. 

  244. 15
    245. 

  245. 16
    246. 

  246. 17</pre></td>
    247. 

  247.         <td class="listing_code"><pre class="programlisting"><span class="normal"><a href="glib-Basic-Types.html#gint">gint</a></span>
    248. 

  248. <span class="function">foo_open_file</span><span class="normal"> </span><span class="symbol">(</span><span class="usertype">GError</span><span class="normal"> </span><span class="symbol">**</span><span class="normal">error</span><span class="symbol">)</span>
    249. 

  249. <span class="cbracket">{</span>
    250. 

  250. <span class="normal">  </span><span class="usertype">gint</span><span class="normal"> fd</span><span class="symbol">;</span>
    251. 

  251. <span class="normal">  fd </span><span class="symbol">=</span><span class="normal"> </span><span class="function">open</span><span class="normal"> </span><span class="symbol">(</span><span class="string">"file.txt"</span><span class="symbol">,</span><span class="normal"> O_RDONLY</span><span class="symbol">);</span>
    252. 

  252. <span class="normal">  </span><span class="keyword">if</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">fd </span><span class="symbol">&lt;</span><span class="normal"> </span><span class="number">0</span><span class="symbol">)</span>
    253. 

  253. <span class="normal">    </span><span class="cbracket">{</span>
    254. 

  254. <span class="normal">      </span><span class="function"><a href="glib-Error-Reporting.html#g-set-error">g_set_error</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">error</span><span class="symbol">,</span>
    255. 

  255. <span class="normal">                   FOO_ERROR</span><span class="symbol">,</span><span class="normal">                 </span><span class="comment">/* error domain */</span>
    256. 

  256. <span class="normal">                   FOO_ERROR_BLAH</span><span class="symbol">,</span><span class="normal">            </span><span class="comment">/* error code */</span>
    257. 

  257. <span class="normal">                   </span><span class="string">"Failed to open file: %s"</span><span class="symbol">,</span><span class="normal"> </span><span class="comment">/* error message format string */</span>
    258. 

  258. <span class="normal">                   </span><span class="function"><a href="glib-String-Utility-Functions.html#g-strerror">g_strerror</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">errno</span><span class="symbol">));</span>
    259. 

  259. <span class="normal">      </span><span class="keyword">return</span><span class="normal"> </span><span class="symbol">-</span><span class="number">1</span><span class="symbol">;</span>
    260. 

  260. <span class="normal">    </span><span class="cbracket">}</span>
    261. 

  261. <span class="normal">  </span><span class="keyword">else</span>
    262. 

  262. <span class="normal">    </span><span class="keyword">return</span><span class="normal"> fd</span><span class="symbol">;</span>
    263. 

  263. <span class="cbracket">}</span></pre></td>
    264. 

  264.       </tr>
    265. 

  265.     </tbody>
    266. 

  266.   </table>
    267. 

  267. </div>
    268. 

  268. 

  269. <p>
    270. 

  270. </p>
    271. 

  271. <p>
    272. 

  272. Things are somewhat more complicated if you yourself call another function that
    273. 

  273. can report a <a class="link" href="glib-Error-Reporting.html#GError" title="GError"><span class="type">GError</span></a>. If the sub-function indicates fatal errors in some way
    274. 

  274. other than reporting a <a class="link" href="glib-Error-Reporting.html#GError" title="GError"><span class="type">GError</span></a>, such as by returning <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> on success, you can
    275. 

  275. simply do the following:
    276. 

  276. </p>
    277. 

  277. <div class="informalexample">
    278. 

  278.   <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
    279. 

  279.     <tbody>
    280. 

  280.       <tr>
    281. 

  281.         <td class="listing_lines" align="right"><pre>1
    282. 

  282. 2
    283. 

  283. 3
    284. 

  284. 4
    285. 

  285. 5
    286. 

  286. 6
    287. 

  287. 7
    288. 

  288. 8
    289. 

  289. 9
    290. 

  290. 10
    291. 

  291. 11
    292. 

  292. 12
    293. 

  293. 13</pre></td>
    294. 

  294.         <td class="listing_code"><pre class="programlisting"><span class="normal"><a href="glib-Basic-Types.html#gboolean">gboolean</a></span>
    295. 

  295. <span class="function">my_function_that_can_fail</span><span class="normal"> </span><span class="symbol">(</span><span class="usertype">GError</span><span class="normal"> </span><span class="symbol">**</span><span class="normal">err</span><span class="symbol">)</span>
    296. 

  296. <span class="cbracket">{</span>
    297. 

  297. <span class="normal">  </span><span class="function"><a href="glib-Warnings-and-Assertions.html#g-return-val-if-fail">g_return_val_if_fail</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">err </span><span class="symbol">==</span><span class="normal"> <a href="glib-Standard-Macros.html#NULL:CAPS">NULL</a> </span><span class="symbol">||</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">err </span><span class="symbol">==</span><span class="normal"> <a href="glib-Standard-Macros.html#NULL:CAPS">NULL</a></span><span class="symbol">,</span><span class="normal"> <a href="glib-Standard-Macros.html#FALSE:CAPS">FALSE</a></span><span class="symbol">);</span>
    298. 

  298. <span class="normal">  </span><span class="keyword">if</span><span class="normal"> </span><span class="symbol">(!</span><span class="function">sub_function_that_can_fail</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">err</span><span class="symbol">))</span>
    299. 

  299. <span class="normal">    </span><span class="cbracket">{</span>
    300. 

  300. <span class="normal">       </span><span class="comment">/* assert that error was set by the sub-function */</span>
    301. 

  301. <span class="normal">       </span><span class="function"><a href="glib-Testing.html#g-assert">g_assert</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">err </span><span class="symbol">==</span><span class="normal"> <a href="glib-Standard-Macros.html#NULL:CAPS">NULL</a> </span><span class="symbol">||</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">err </span><span class="symbol">!=</span><span class="normal"> <a href="glib-Standard-Macros.html#NULL:CAPS">NULL</a></span><span class="symbol">);</span>
    302. 

  302. <span class="normal">       </span><span class="keyword">return</span><span class="normal"> <a href="glib-Standard-Macros.html#FALSE:CAPS">FALSE</a></span><span class="symbol">;</span>
    303. 

  303. <span class="normal">    </span><span class="cbracket">}</span>
    304. 

  304. <span class="normal">  </span><span class="comment">/* otherwise continue, no error occurred */</span>
    305. 

  305. <span class="normal">  </span><span class="function"><a href="glib-Testing.html#g-assert">g_assert</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">err </span><span class="symbol">==</span><span class="normal"> <a href="glib-Standard-Macros.html#NULL:CAPS">NULL</a> </span><span class="symbol">||</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">err </span><span class="symbol">==</span><span class="normal"> <a href="glib-Standard-Macros.html#NULL:CAPS">NULL</a></span><span class="symbol">);</span>
    306. 

  306. <span class="cbracket">}</span></pre></td>
    307. 

  307.       </tr>
    308. 

  308.     </tbody>
    309. 

  309.   </table>
    310. 

  310. </div>
    311. 

  311. 

  312. <p>
    313. 

  313. </p>
    314. 

  314. <p>
    315. 

  315. If the sub-function does not indicate errors other than by reporting a <a class="link" href="glib-Error-Reporting.html#GError" title="GError"><span class="type">GError</span></a>,
    316. 

  316. you need to create a temporary <a class="link" href="glib-Error-Reporting.html#GError" title="GError"><span class="type">GError</span></a> since the passed-in one may be <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>.
    317. 

  317. <a class="link" href="glib-Error-Reporting.html#g-propagate-error" title="g_propagate_error ()"><code class="function">g_propagate_error()</code></a> is intended for use in this case.
    318. 

  318. </p>
    319. 

  319. <div class="informalexample">
    320. 

  320.   <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
    321. 

  321.     <tbody>
    322. 

  322.       <tr>
    323. 

  323.         <td class="listing_lines" align="right"><pre>1
    324. 

  324. 2
    325. 

  325. 3
    326. 

  326. 4
    327. 

  327. 5
    328. 

  328. 6
    329. 

  329. 7
    330. 

  330. 8
    331. 

  331. 9
    332. 

  332. 10
    333. 

  333. 11
    334. 

  334. 12
    335. 

  335. 13
    336. 

  336. 14
    337. 

  337. 15
    338. 

  338. 16
    339. 

  339. 17</pre></td>
    340. 

  340.         <td class="listing_code"><pre class="programlisting"><span class="normal"><a href="glib-Basic-Types.html#gboolean">gboolean</a></span>
    341. 

  341. <span class="function">my_function_that_can_fail</span><span class="normal"> </span><span class="symbol">(</span><span class="usertype">GError</span><span class="normal"> </span><span class="symbol">**</span><span class="normal">err</span><span class="symbol">)</span>
    342. 

  342. <span class="cbracket">{</span>
    343. 

  343. <span class="normal">  </span><span class="usertype">GError</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">tmp_error</span><span class="symbol">;</span>
    344. 

  344. <span class="normal">  </span><span class="function"><a href="glib-Warnings-and-Assertions.html#g-return-val-if-fail">g_return_val_if_fail</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">err </span><span class="symbol">==</span><span class="normal"> <a href="glib-Standard-Macros.html#NULL:CAPS">NULL</a> </span><span class="symbol">||</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">err </span><span class="symbol">==</span><span class="normal"> <a href="glib-Standard-Macros.html#NULL:CAPS">NULL</a></span><span class="symbol">,</span><span class="normal"> <a href="glib-Standard-Macros.html#FALSE:CAPS">FALSE</a></span><span class="symbol">);</span>
    345. 

  345. <span class="normal">  tmp_error </span><span class="symbol">=</span><span class="normal"> <a href="glib-Standard-Macros.html#NULL:CAPS">NULL</a></span><span class="symbol">;</span>
    346. 

  346. <span class="normal">  </span><span class="function">sub_function_that_can_fail</span><span class="normal"> </span><span class="symbol">(&amp;</span><span class="normal">tmp_error</span><span class="symbol">);</span>
    347. 

  347. <span class="normal">  </span><span class="keyword">if</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">tmp_error </span><span class="symbol">!=</span><span class="normal"> <a href="glib-Standard-Macros.html#NULL:CAPS">NULL</a></span><span class="symbol">)</span>
    348. 

  348. <span class="normal">    </span><span class="cbracket">{</span>
    349. 

  349. <span class="normal">       </span><span class="comment">/* store tmp_error in err, if err != NULL,</span>
    350. 

  350. <span class="comment">        * otherwise call g_error_free() on tmp_error</span>
    351. 

  351. <span class="comment">        */</span>
    352. 

  352. <span class="normal">       </span><span class="function"><a href="glib-Error-Reporting.html#g-propagate-error">g_propagate_error</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">err</span><span class="symbol">,</span><span class="normal"> tmp_error</span><span class="symbol">);</span>
    353. 

  353. <span class="normal">       </span><span class="keyword">return</span><span class="normal"> <a href="glib-Standard-Macros.html#FALSE:CAPS">FALSE</a></span><span class="symbol">;</span>
    354. 

  354. <span class="normal">    </span><span class="cbracket">}</span>
    355. 

  355. <span class="normal">  </span><span class="comment">/* otherwise continue, no error occurred */</span>
    356. 

  356. <span class="cbracket">}</span></pre></td>
    357. 

  357.       </tr>
    358. 

  358.     </tbody>
    359. 

  359.   </table>
    360. 

  360. </div>
    361. 

  361. 

  362. <p>
    363. 

  363. </p>
    364. 

  364. <p>
    365. 

  365. Error pileups are always a bug. For example, this code is incorrect:
    366. 

  366. </p>
    367. 

  367. <div class="informalexample">
    368. 

  368.   <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
    369. 

  369.     <tbody>
    370. 

  370.       <tr>
    371. 

  371.         <td class="listing_lines" align="right"><pre>1
    372. 

  372. 2
    373. 

  373. 3
    374. 

  374. 4
    375. 

  375. 5
    376. 

  376. 6
    377. 

  377. 7
    378. 

  378. 8
    379. 

  379. 9
    380. 

  380. 10
    381. 

  381. 11
    382. 

  382. 12
    383. 

  383. 13
    384. 

  384. 14</pre></td>
    385. 

  385.         <td class="listing_code"><pre class="programlisting"><span class="normal"><a href="glib-Basic-Types.html#gboolean">gboolean</a></span>
    386. 

  386. <span class="function">my_function_that_can_fail</span><span class="normal"> </span><span class="symbol">(</span><span class="usertype">GError</span><span class="normal"> </span><span class="symbol">**</span><span class="normal">err</span><span class="symbol">)</span>
    387. 

  387. <span class="cbracket">{</span>
    388. 

  388. <span class="normal">  </span><span class="usertype">GError</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">tmp_error</span><span class="symbol">;</span>
    389. 

  389. <span class="normal">  </span><span class="function"><a href="glib-Warnings-and-Assertions.html#g-return-val-if-fail">g_return_val_if_fail</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">err </span><span class="symbol">==</span><span class="normal"> <a href="glib-Standard-Macros.html#NULL:CAPS">NULL</a> </span><span class="symbol">||</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">err </span><span class="symbol">==</span><span class="normal"> <a href="glib-Standard-Macros.html#NULL:CAPS">NULL</a></span><span class="symbol">,</span><span class="normal"> <a href="glib-Standard-Macros.html#FALSE:CAPS">FALSE</a></span><span class="symbol">);</span>
    390. 

  390. <span class="normal">  tmp_error </span><span class="symbol">=</span><span class="normal"> <a href="glib-Standard-Macros.html#NULL:CAPS">NULL</a></span><span class="symbol">;</span>
    391. 

  391. <span class="normal">  </span><span class="function">sub_function_that_can_fail</span><span class="normal"> </span><span class="symbol">(&amp;</span><span class="normal">tmp_error</span><span class="symbol">);</span>
    392. 

  392. <span class="normal">  </span><span class="function">other_function_that_can_fail</span><span class="normal"> </span><span class="symbol">(&amp;</span><span class="normal">tmp_error</span><span class="symbol">);</span>
    393. 

  393. <span class="normal">  </span><span class="keyword">if</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">tmp_error </span><span class="symbol">!=</span><span class="normal"> <a href="glib-Standard-Macros.html#NULL:CAPS">NULL</a></span><span class="symbol">)</span>
    394. 

  394. <span class="normal">    </span><span class="cbracket">{</span>
    395. 

  395. <span class="normal">       </span><span class="function"><a href="glib-Error-Reporting.html#g-propagate-error">g_propagate_error</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">err</span><span class="symbol">,</span><span class="normal"> tmp_error</span><span class="symbol">);</span>
    396. 

  396. <span class="normal">       </span><span class="keyword">return</span><span class="normal"> <a href="glib-Standard-Macros.html#FALSE:CAPS">FALSE</a></span><span class="symbol">;</span>
    397. 

  397. <span class="normal">    </span><span class="cbracket">}</span>
    398. 

  398. <span class="cbracket">}</span></pre></td>
    399. 

  399.       </tr>
    400. 

  400.     </tbody>
    401. 

  401.   </table>
    402. 

  402. </div>
    403. 

  403. 

  404. <p>
    405. 

  405. <code class="literal">tmp_error</code> should be checked immediately after
    406. 

  406. <code class="function"><code class="function">sub_function_that_can_fail()</code></code>, and either cleared or propagated upward.  The rule
    407. 

  407. is: <span class="emphasis"><em>after each error, you must either handle the error, or return it to the
    408. 

  408. calling function</em></span>.  Note that passing <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> for the error location is the
    409. 

  409. equivalent of handling an error by always doing nothing about it. So the
    410. 

  410. following code is fine, assuming errors in <code class="function"><code class="function">sub_function_that_can_fail()</code></code> are not
    411. 

  411. fatal to <code class="function"><code class="function">my_function_that_can_fail()</code></code>:
    412. 

  412. </p>
    413. 

  413. <div class="informalexample">
    414. 

  414.   <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
    415. 

  415.     <tbody>
    416. 

  416.       <tr>
    417. 

  417.         <td class="listing_lines" align="right"><pre>1
    418. 

  418. 2
    419. 

  419. 3
    420. 

  420. 4
    421. 

  421. 5
    422. 

  422. 6
    423. 

  423. 7
    424. 

  424. 8
    425. 

  425. 9
    426. 

  426. 10
    427. 

  427. 11
    428. 

  428. 12
    429. 

  429. 13
    430. 

  430. 14</pre></td>
    431. 

  431.         <td class="listing_code"><pre class="programlisting"><span class="normal"><a href="glib-Basic-Types.html#gboolean">gboolean</a></span>
    432. 

  432. <span class="function">my_function_that_can_fail</span><span class="normal"> </span><span class="symbol">(</span><span class="usertype">GError</span><span class="normal"> </span><span class="symbol">**</span><span class="normal">err</span><span class="symbol">)</span>
    433. 

  433. <span class="cbracket">{</span>
    434. 

  434. <span class="normal">  </span><span class="usertype">GError</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">tmp_error</span><span class="symbol">;</span>
    435. 

  435. <span class="normal">  </span><span class="function"><a href="glib-Warnings-and-Assertions.html#g-return-val-if-fail">g_return_val_if_fail</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">err </span><span class="symbol">==</span><span class="normal"> <a href="glib-Standard-Macros.html#NULL:CAPS">NULL</a> </span><span class="symbol">||</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">err </span><span class="symbol">==</span><span class="normal"> <a href="glib-Standard-Macros.html#NULL:CAPS">NULL</a></span><span class="symbol">,</span><span class="normal"> <a href="glib-Standard-Macros.html#FALSE:CAPS">FALSE</a></span><span class="symbol">);</span>
    436. 

  436. <span class="normal">  </span><span class="function">sub_function_that_can_fail</span><span class="normal"> </span><span class="symbol">(</span><span class="normal"><a href="glib-Standard-Macros.html#NULL:CAPS">NULL</a></span><span class="symbol">);</span><span class="normal"> </span><span class="comment">/* ignore errors */</span>
    437. 

  437. <span class="normal">  tmp_error </span><span class="symbol">=</span><span class="normal"> <a href="glib-Standard-Macros.html#NULL:CAPS">NULL</a></span><span class="symbol">;</span>
    438. 

  438. <span class="normal">  </span><span class="function">other_function_that_can_fail</span><span class="normal"> </span><span class="symbol">(&amp;</span><span class="normal">tmp_error</span><span class="symbol">);</span>
    439. 

  439. <span class="normal">  </span><span class="keyword">if</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">tmp_error </span><span class="symbol">!=</span><span class="normal"> <a href="glib-Standard-Macros.html#NULL:CAPS">NULL</a></span><span class="symbol">)</span>
    440. 

  440. <span class="normal">    </span><span class="cbracket">{</span>
    441. 

  441. <span class="normal">       </span><span class="function"><a href="glib-Error-Reporting.html#g-propagate-error">g_propagate_error</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">err</span><span class="symbol">,</span><span class="normal"> tmp_error</span><span class="symbol">);</span>
    442. 

  442. <span class="normal">       </span><span class="keyword">return</span><span class="normal"> <a href="glib-Standard-Macros.html#FALSE:CAPS">FALSE</a></span><span class="symbol">;</span>
    443. 

  443. <span class="normal">    </span><span class="cbracket">}</span>
    444. 

  444. <span class="cbracket">}</span></pre></td>
    445. 

  445.       </tr>
    446. 

  446.     </tbody>
    447. 

  447.   </table>
    448. 

  448. </div>
    449. 

  449. 

  450. <p>
    451. 

  451. </p>
    452. 

  452. <p>
    453. 

  453. Note that passing <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> for the error location <span class="emphasis"><em>ignores</em></span>
    454. 

  454. errors; it's equivalent to <code class="literal">try { <code class="function">sub_function_that_can_fail()</code>; } catch
    455. 

  455. (...) {}</code> in C++. It does <span class="emphasis"><em>not</em></span> mean to leave errors
    456. 

  456. unhandled; it means to handle them by doing nothing.
    457. 

  457. </p>
    458. 

  458. <p>
    459. 

  459. Error domains and codes are conventionally named as follows:
    460. 

  460. </p>
    461. 

  461. <div class="itemizedlist"><ul class="itemizedlist" type="disc">
    462. 

  462. <li class="listitem">
    463. 

  463. <p>
    464. 

  464. The error domain is called
    465. 

  465. <code class="literal">&lt;NAMESPACE&gt;_&lt;MODULE&gt;_ERROR</code>, for example
    466. 

  466. <a class="link" href="glib-Spawning-Processes.html#G-SPAWN-ERROR:CAPS" title="G_SPAWN_ERROR"><code class="literal">G_SPAWN_ERROR</code></a> or <a class="link" href="glib-Threads.html#G-THREAD-ERROR:CAPS" title="G_THREAD_ERROR"><code class="literal">G_THREAD_ERROR</code></a>:
    467. 

  467. </p>
    468. 

  468. <div class="informalexample">
    469. 

  469.   <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
    470. 

  470.     <tbody>
    471. 

  471.       <tr>
    472. 

  472.         <td class="listing_lines" align="right"><pre>1
    473. 

  473. 2
    474. 

  474. 3
    475. 

  475. 4
    476. 

  476. 5
    477. 

  477. 6</pre></td>
    478. 

  478.         <td class="listing_code"><pre class="programlisting"><span class="preproc">#define</span><span class="normal"> </span><span class="usertype">G_SPAWN_ERROR</span><span class="normal"> </span><span class="function">g_spawn_error_quark</span><span class="normal"> </span><span class="symbol">()</span>
    479. 

  479. <span class="normal"><a href="glib-Quarks.html#GQuark">GQuark</a></span>
    480. 

  480. <span class="function">g_spawn_error_quark</span><span class="normal"> </span><span class="symbol">(</span><span class="type">void</span><span class="symbol">)</span>
    481. 

  481. <span class="cbracket">{</span>
    482. 

  482. <span class="normal">  </span><span class="keyword">return</span><span class="normal"> </span><span class="function"><a href="glib-Quarks.html#g-quark-from-static-string">g_quark_from_static_string</a></span><span class="normal"> </span><span class="symbol">(</span><span class="string">"g-spawn-error-quark"</span><span class="symbol">);</span>
    483. 

  483. <span class="cbracket">}</span></pre></td>
    484. 

  484.       </tr>
    485. 

  485.     </tbody>
    486. 

  486.   </table>
    487. 

  487. </div>
    488. 

  488. 

  489. <p>
    490. 

  490. </p>
    491. 

  491. </li>
    492. 

  492. <li class="listitem"><p>
    493. 

  493. The quark function for the error domain is called <code class="literal">&lt;namespace&gt;_&lt;module&gt;_error_quark</code>, for example <code class="function">g_spawn_error_quark()</code> or %<code class="function">g_thread_error_quark()</code>.
    494. 

  494. </p></li>
    495. 

  495. <li class="listitem"><p>
    496. 

  496. The error codes are in an enumeration called
    497. 

  497. <code class="literal">&lt;Namespace&gt;&lt;Module&gt;Error</code>; for example,
    498. 

  498. <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>.
    499. 

  499. </p></li>
    500. 

  500. <li class="listitem"><p>
    501. 

  501. 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>.
    502. 

  502. </p></li>
    503. 

  503. <li class="listitem"><p>
    504. 

  504. If there's a "generic" or "unknown" error code for unrecoverable errors it
    505. 

  505. doesn't make sense to distinguish with specific codes, it should be called
    506. 

  506. <code class="literal">&lt;NAMESPACE&gt;_&lt;MODULE&gt;_ERROR_FAILED</code>, for
    507. 

  507. 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>.
    508. 

  508. </p></li>
    509. 

  509. </ul></div>
    510. 

  510. <p>
    511. 

  511. </p>
    512. 

  512. <p>
    513. 

  513. Summary of rules for use of <a class="link" href="glib-Error-Reporting.html#GError" title="GError"><span class="type">GError</span></a>:
    514. 

  514.       </p>
    515. 

  515. <div class="itemizedlist"><ul class="itemizedlist" type="disc">
    516. 

  516. <li class="listitem"><p>
    517. 

  517.            Do not report programming errors via <a class="link" href="glib-Error-Reporting.html#GError" title="GError"><span class="type">GError</span></a>.
    518. 

  518. 	  </p></li>
    519. 

  519. <li class="listitem"><p>
    520. 

  520.           The last argument of a function that returns an error should be a
    521. 

  521.           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
    522. 

  522.           <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
    523. 

  523.           argument before the "...".
    524. 

  524.         </p></li>
    525. 

  525. <li class="listitem"><p>
    526. 

  526.           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
    527. 

  527.           in details of the exact error that occurred.
    528. 

  528.         </p></li>
    529. 

  529. <li class="listitem"><p>
    530. 

  530.            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
    531. 

  531.            not be returned to the caller, but your function should still
    532. 

  532.            abort and return if an error occurs. That is, control flow should
    533. 

  533.            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>.
    534. 

  534. 	  </p></li>
    535. 

  535. <li class="listitem"><p>
    536. 

  536.           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
    537. 

  537.           <span class="emphasis"><em>had a fatal failure and did not complete whatever it was supposed
    538. 

  538.             to do</em></span>. If the failure was not fatal, then you handled it
    539. 

  539.           and you should not report it. If it was fatal, then you must report it
    540. 

  540.           and discontinue whatever you were doing immediately.
    541. 

  541.         </p></li>
    542. 

  542. <li class="listitem"><p>
    543. 

  543.           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
    544. 

  544.           a function that can report errors.
    545. 

  545. 	  </p></li>
    546. 

  546. <li class="listitem"><p>
    547. 

  547.           "Piling up" errors is always a bug. That is, if you assign a new
    548. 

  548.           <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
    549. 

  549.           error, it indicates that you should have aborted the operation instead
    550. 

  550.           of continuing. If you were able to continue, you should have cleared
    551. 

  551.           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
    552. 

  552.           if you pile up errors.
    553. 

  553. 	  </p></li>
    554. 

  554. <li class="listitem"><p>
    555. 

  555.           By convention, if you return a boolean value indicating success
    556. 

  556.           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,
    557. 

  557.           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.
    558. 

  558.         </p></li>
    559. 

  559. <li class="listitem"><p>
    560. 

  560.           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
    561. 

  561.           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
    562. 

  562.           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,
    563. 

  563.           then users must check whether an error was returned to see if the
    564. 

  564.           function succeeded.
    565. 

  565. 	  </p></li>
    566. 

  566. <li class="listitem"><p>
    567. 

  567.           When implementing a function that can report errors, you may want to
    568. 

  568.           add a check at the top of your function that the error return location
    569. 

  569.           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
    570. 

  570.           (e.g. <code class="literal">g_return_if_fail (error == NULL || *error ==
    571. 

  571.           NULL);</code>).
    572. 

  572. 	  </p></li>
    573. 

  573. </ul></div>
    574. 

  574. <p>
    575. 

  575. </p>
    576. 

  576. </div>
    577. 

  577. <div class="refsect1">
    578. 

  578. <a name="glib-Error-Reporting.details"></a><h2>Details</h2>
    579. 

  579. <div class="refsect2">
    580. 

  580. <a name="GError"></a><h3>GError</h3>
    581. 

  581. <pre class="programlisting">typedef struct {
    582. 

  582.   GQuark       domain;
    583. 

  583.   gint         code;
    584. 

  584.   gchar       *message;
    585. 

  585. } GError;
    586. 

  586. </pre>
    587. 

  587. <p>
    588. 

  588. The <span class="structname">GError</span> structure contains
    589. 

  589. information about an error that has occurred.
    590. 

  590. </p>
    591. 

  591. <div class="variablelist"><table border="0">
    592. 

  592. <col align="left" valign="top">
    593. 

  593. <tbody>
    594. 

  594. <tr>
    595. 

  595. <td><p><span class="term"><a class="link" href="glib-Quarks.html#GQuark" title="GQuark"><span class="type">GQuark</span></a> <em class="structfield"><code><a name="GError.domain"></a>domain</code></em>;</span></p></td>
    596. 

  596. <td>error domain, e.g. <a class="link" href="glib-File-Utilities.html#G-FILE-ERROR:CAPS" title="G_FILE_ERROR"><span class="type">G_FILE_ERROR</span></a>.
    597. 

  597. </td>
    598. 

  598. </tr>
    599. 

  599. <tr>
    600. 

  600. <td><p><span class="term"><a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="type">gint</span></a> <em class="structfield"><code><a name="GError.code"></a>code</code></em>;</span></p></td>
    601. 

  601. <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>.
    602. 

  602. </td>
    603. 

  603. </tr>
    604. 

  604. <tr>
    605. 

  605. <td><p><span class="term"><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *<em class="structfield"><code><a name="GError.message"></a>message</code></em>;</span></p></td>
    606. 

  606. <td>human-readable informative error message.
    607. 

  607. </td>
    608. 

  608. </tr>
    609. 

  609. </tbody>
    610. 

  610. </table></div>
    611. 

  611. </div>
    612. 

  612. <hr>
    613. 

  613. <div class="refsect2">
    614. 

  614. <a name="g-error-new"></a><h3>g_error_new ()</h3>
    615. 

  615. <pre class="programlisting"><a class="link" href="glib-Error-Reporting.html#GError" title="GError"><span class="returnvalue">GError</span></a> *            g_error_new                         (<em class="parameter"><code><a class="link" href="glib-Quarks.html#GQuark" title="GQuark"><span class="type">GQuark</span></a> domain</code></em>,
    616. 

  616.                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="type">gint</span></a> code</code></em>,
    617. 

  617.                                                          <em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *format</code></em>,
    618. 

  618.                                                          <em class="parameter"><code>...</code></em>);</pre>
    619. 

  619. <p>
    620. 

  620. Creates a new <a class="link" href="glib-Error-Reporting.html#GError" title="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>,
    621. 

  621. and a message formatted with <em class="parameter"><code>format</code></em>.
    622. 

  622. </p>
    623. 

  623. <div class="variablelist"><table border="0">
    624. 

  624. <col align="left" valign="top">
    625. 

  625. <tbody>
    626. 

  626. <tr>
    627. 

  627. <td><p><span class="term"><em class="parameter"><code>domain</code></em> :</span></p></td>
    628. 

  628. <td>error domain
    629. 

  629. </td>
    630. 

  630. </tr>
    631. 

  631. <tr>
    632. 

  632. <td><p><span class="term"><em class="parameter"><code>code</code></em> :</span></p></td>
    633. 

  633. <td>error code
    634. 

  634. </td>
    635. 

  635. </tr>
    636. 

  636. <tr>
    637. 

  637. <td><p><span class="term"><em class="parameter"><code>format</code></em> :</span></p></td>
    638. 

  638. <td>printf()-style format for error message
    639. 

  639. </td>
    640. 

  640. </tr>
    641. 

  641. <tr>
    642. 

  642. <td><p><span class="term"><em class="parameter"><code>...</code></em> :</span></p></td>
    643. 

  643. <td>parameters for message format
    644. 

  644. </td>
    645. 

  645. </tr>
    646. 

  646. <tr>
    647. 

  647. <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
    648. 

  648. <td> a new <a class="link" href="glib-Error-Reporting.html#GError" title="GError"><span class="type">GError</span></a>
    649. 

  649. </td>
    650. 

  650. </tr>
    651. 

  651. </tbody>
    652. 

  652. </table></div>
    653. 

  653. </div>
    654. 

  654. <hr>
    655. 

  655. <div class="refsect2">
    656. 

  656. <a name="g-error-new-literal"></a><h3>g_error_new_literal ()</h3>
    657. 

  657. <pre class="programlisting"><a class="link" href="glib-Error-Reporting.html#GError" title="GError"><span class="returnvalue">GError</span></a> *            g_error_new_literal                 (<em class="parameter"><code><a class="link" href="glib-Quarks.html#GQuark" title="GQuark"><span class="type">GQuark</span></a> domain</code></em>,
    658. 

  658.                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="type">gint</span></a> code</code></em>,
    659. 

  659.                                                          <em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *message</code></em>);</pre>
    660. 

  660. <p>
    661. 

  661. Creates a new <a class="link" href="glib-Error-Reporting.html#GError" title="GError"><span class="type">GError</span></a>; unlike <a class="link" href="glib-Error-Reporting.html#g-error-new" title="g_error_new ()"><code class="function">g_error_new()</code></a>, <em class="parameter"><code>message</code></em> is
    662. 

  662. not a <code class="function">printf()</code>-style format string. Use this function if
    663. 

  663. <em class="parameter"><code>message</code></em> contains text you don't have control over,
    664. 

  664. that could include <code class="function">printf()</code> escape sequences.
    665. 

  665. </p>
    666. 

  666. <div class="variablelist"><table border="0">
    667. 

  667. <col align="left" valign="top">
    668. 

  668. <tbody>
    669. 

  669. <tr>
    670. 

  670. <td><p><span class="term"><em class="parameter"><code>domain</code></em> :</span></p></td>
    671. 

  671. <td>error domain
    672. 

  672. </td>
    673. 

  673. </tr>
    674. 

  674. <tr>
    675. 

  675. <td><p><span class="term"><em class="parameter"><code>code</code></em> :</span></p></td>
    676. 

  676. <td>error code
    677. 

  677. </td>
    678. 

  678. </tr>
    679. 

  679. <tr>
    680. 

  680. <td><p><span class="term"><em class="parameter"><code>message</code></em> :</span></p></td>
    681. 

  681. <td>error message
    682. 

  682. </td>
    683. 

  683. </tr>
    684. 

  684. <tr>
    685. 

  685. <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
    686. 

  686. <td> a new <a class="link" href="glib-Error-Reporting.html#GError" title="GError"><span class="type">GError</span></a>
    687. 

  687. </td>
    688. 

  688. </tr>
    689. 

  689. </tbody>
    690. 

  690. </table></div>
    691. 

  691. </div>
    692. 

  692. <hr>
    693. 

  693. <div class="refsect2">
    694. 

  694. <a name="g-error-new-valist"></a><h3>g_error_new_valist ()</h3>
    695. 

  695. <pre class="programlisting"><a class="link" href="glib-Error-Reporting.html#GError" title="GError"><span class="returnvalue">GError</span></a> *            g_error_new_valist                  (<em class="parameter"><code><a class="link" href="glib-Quarks.html#GQuark" title="GQuark"><span class="type">GQuark</span></a> domain</code></em>,
    696. 

  696.                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="type">gint</span></a> code</code></em>,
    697. 

  697.                                                          <em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *format</code></em>,
    698. 

  698.                                                          <em class="parameter"><code><span class="type">va_list</span> args</code></em>);</pre>
    699. 

  699. <p>
    700. 

  700. Creates a new <a class="link" href="glib-Error-Reporting.html#GError" title="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>,
    701. 

  701. and a message formatted with <em class="parameter"><code>format</code></em>.
    702. 

  702. </p>
    703. 

  703. <div class="variablelist"><table border="0">
    704. 

  704. <col align="left" valign="top">
    705. 

  705. <tbody>
    706. 

  706. <tr>
    707. 

  707. <td><p><span class="term"><em class="parameter"><code>domain</code></em> :</span></p></td>
    708. 

  708. <td>error domain
    709. 

  709. </td>
    710. 

  710. </tr>
    711. 

  711. <tr>
    712. 

  712. <td><p><span class="term"><em class="parameter"><code>code</code></em> :</span></p></td>
    713. 

  713. <td>error code
    714. 

  714. </td>
    715. 

  715. </tr>
    716. 

  716. <tr>
    717. 

  717. <td><p><span class="term"><em class="parameter"><code>format</code></em> :</span></p></td>
    718. 

  718. <td>printf()-style format for error message
    719. 

  719. </td>
    720. 

  720. </tr>
    721. 

  721. <tr>
    722. 

  722. <td><p><span class="term"><em class="parameter"><code>args</code></em> :</span></p></td>
    723. 

  723. <td>
    724. 

  724. <span class="type">va_list</span> of parameters for the message format
    725. 

  725. </td>
    726. 

  726. </tr>
    727. 

  727. <tr>
    728. 

  728. <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
    729. 

  729. <td> a new <a class="link" href="glib-Error-Reporting.html#GError" title="GError"><span class="type">GError</span></a>
    730. 

  730. 

  731. </td>
    732. 

  732. </tr>
    733. 

  733. </tbody>
    734. 

  734. </table></div>
    735. 

  735. <p class="since">Since 2.22</p>
    736. 

  736. </div>
    737. 

  737. <hr>
    738. 

  738. <div class="refsect2">
    739. 

  739. <a name="g-error-free"></a><h3>g_error_free ()</h3>
    740. 

  740. <pre class="programlisting"><span class="returnvalue">void</span>                g_error_free                        (<em class="parameter"><code><a class="link" href="glib-Error-Reporting.html#GError" title="GError"><span class="type">GError</span></a> *error</code></em>);</pre>
    741. 

  741. <p>
    742. 

  742. Frees a <a class="link" href="glib-Error-Reporting.html#GError" title="GError"><span class="type">GError</span></a> and associated resources.
    743. 

  743. </p>
    744. 

  744. <div class="variablelist"><table border="0">
    745. 

  745. <col align="left" valign="top">
    746. 

  746. <tbody><tr>
    747. 

  747. <td><p><span class="term"><em class="parameter"><code>error</code></em> :</span></p></td>
    748. 

  748. <td>a <a class="link" href="glib-Error-Reporting.html#GError" title="GError"><span class="type">GError</span></a>
    749. 

  749. </td>
    750. 

  750. </tr></tbody>
    751. 

  751. </table></div>
    752. 

  752. </div>
    753. 

  753. <hr>
    754. 

  754. <div class="refsect2">
    755. 

  755. <a name="g-error-copy"></a><h3>g_error_copy ()</h3>
    756. 

  756. <pre class="programlisting"><a class="link" href="glib-Error-Reporting.html#GError" title="GError"><span class="returnvalue">GError</span></a> *            g_error_copy                        (<em class="parameter"><code>const <a class="link" href="glib-Error-Reporting.html#GError" title="GError"><span class="type">GError</span></a> *error</code></em>);</pre>
    757. 

  757. <p>
    758. 

  758. Makes a copy of <em class="parameter"><code>error</code></em>.
    759. 

  759. </p>
    760. 

  760. <div class="variablelist"><table border="0">
    761. 

  761. <col align="left" valign="top">
    762. 

  762. <tbody>
    763. 

  763. <tr>
    764. 

  764. <td><p><span class="term"><em class="parameter"><code>error</code></em> :</span></p></td>
    765. 

  765. <td>a <a class="link" href="glib-Error-Reporting.html#GError" title="GError"><span class="type">GError</span></a>
    766. 

  766. </td>
    767. 

  767. </tr>
    768. 

  768. <tr>
    769. 

  769. <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
    770. 

  770. <td> a new <a class="link" href="glib-Error-Reporting.html#GError" title="GError"><span class="type">GError</span></a>
    771. 

  771. </td>
    772. 

  772. </tr>
    773. 

  773. </tbody>
    774. 

  774. </table></div>
    775. 

  775. </div>
    776. 

  776. <hr>
    777. 

  777. <div class="refsect2">
    778. 

  778. <a name="g-error-matches"></a><h3>g_error_matches ()</h3>
    779. 

  779. <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            g_error_matches                     (<em class="parameter"><code>const <a class="link" href="glib-Error-Reporting.html#GError" title="GError"><span class="type">GError</span></a> *error</code></em>,
    780. 

  780.                                                          <em class="parameter"><code><a class="link" href="glib-Quarks.html#GQuark" title="GQuark"><span class="type">GQuark</span></a> domain</code></em>,
    781. 

  781.                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="type">gint</span></a> code</code></em>);</pre>
    782. 

  782. <p>
    783. 

  783. Returns <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> if <em class="parameter"><code>error</code></em> matches <em class="parameter"><code>domain</code></em> and <em class="parameter"><code>code</code></em>, <a class="link" href="glib-Standard-Macros.html#FALSE:CAPS" title="FALSE"><code class="literal">FALSE</code></a>
    784. 

  784. otherwise. In particular, when <em class="parameter"><code>error</code></em> is <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>, <a class="link" href="glib-Standard-Macros.html#FALSE:CAPS" title="FALSE"><code class="literal">FALSE</code></a> will
    785. 

  785. be returned.
    786. 

  786. </p>
    787. 

  787. <div class="variablelist"><table border="0">
    788. 

  788. <col align="left" valign="top">
    789. 

  789. <tbody>
    790. 

  790. <tr>
    791. 

  791. <td><p><span class="term"><em class="parameter"><code>error</code></em> :</span></p></td>
    792. 

  792. <td>a <a class="link" href="glib-Error-Reporting.html#GError" title="GError"><span class="type">GError</span></a> or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>
    793. 

  793. </td>
    794. 

  794. </tr>
    795. 

  795. <tr>
    796. 

  796. <td><p><span class="term"><em class="parameter"><code>domain</code></em> :</span></p></td>
    797. 

  797. <td>an error domain
    798. 

  798. </td>
    799. 

  799. </tr>
    800. 

  800. <tr>
    801. 

  801. <td><p><span class="term"><em class="parameter"><code>code</code></em> :</span></p></td>
    802. 

  802. <td>an error code
    803. 

  803. </td>
    804. 

  804. </tr>
    805. 

  805. <tr>
    806. 

  806. <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
    807. 

  807. <td> whether <em class="parameter"><code>error</code></em> has <em class="parameter"><code>domain</code></em> and <em class="parameter"><code>code</code></em>
    808. 

  808. </td>
    809. 

  809. </tr>
    810. 

  810. </tbody>
    811. 

  811. </table></div>
    812. 

  812. </div>
    813. 

  813. <hr>
    814. 

  814. <div class="refsect2">
    815. 

  815. <a name="g-set-error"></a><h3>g_set_error ()</h3>
    816. 

  816. <pre class="programlisting"><span class="returnvalue">void</span>                g_set_error                         (<em class="parameter"><code><a class="link" href="glib-Error-Reporting.html#GError" title="GError"><span class="type">GError</span></a> **err</code></em>,
    817. 

  817.                                                          <em class="parameter"><code><a class="link" href="glib-Quarks.html#GQuark" title="GQuark"><span class="type">GQuark</span></a> domain</code></em>,
    818. 

  818.                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="type">gint</span></a> code</code></em>,
    819. 

  819.                                                          <em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *format</code></em>,
    820. 

  820.                                                          <em class="parameter"><code>...</code></em>);</pre>
    821. 

  821. <p>
    822. 

  822. Does nothing if <em class="parameter"><code>err</code></em> is <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>; if <em class="parameter"><code>err</code></em> is non-<a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>, then *<em class="parameter"><code>err</code></em>
    823. 

  823. must be <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>. A new <a class="link" href="glib-Error-Reporting.html#GError" title="GError"><span class="type">GError</span></a> is created and assigned to *<em class="parameter"><code>err</code></em>.
    824. 

  824. </p>
    825. 

  825. <div class="variablelist"><table border="0">
    826. 

  826. <col align="left" valign="top">
    827. 

  827. <tbody>
    828. 

  828. <tr>
    829. 

  829. <td><p><span class="term"><em class="parameter"><code>err</code></em> :</span></p></td>
    830. 

  830. <td>a return location for a <a class="link" href="glib-Error-Reporting.html#GError" title="GError"><span class="type">GError</span></a>, or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>
    831. 

  831. </td>
    832. 

  832. </tr>
    833. 

  833. <tr>
    834. 

  834. <td><p><span class="term"><em class="parameter"><code>domain</code></em> :</span></p></td>
    835. 

  835. <td>error domain
    836. 

  836. </td>
    837. 

  837. </tr>
    838. 

  838. <tr>
    839. 

  839. <td><p><span class="term"><em class="parameter"><code>code</code></em> :</span></p></td>
    840. 

  840. <td>error code
    841. 

  841. </td>
    842. 

  842. </tr>
    843. 

  843. <tr>
    844. 

  844. <td><p><span class="term"><em class="parameter"><code>format</code></em> :</span></p></td>
    845. 

  845. <td>printf()-style format
    846. 

  846. </td>
    847. 

  847. </tr>
    848. 

  848. <tr>
    849. 

  849. <td><p><span class="term"><em class="parameter"><code>...</code></em> :</span></p></td>
    850. 

  850. <td>args for <em class="parameter"><code>format</code></em>
    851. 

  851. </td>
    852. 

  852. </tr>
    853. 

  853. </tbody>
    854. 

  854. </table></div>
    855. 

  855. </div>
    856. 

  856. <hr>
    857. 

  857. <div class="refsect2">
    858. 

  858. <a name="g-set-error-literal"></a><h3>g_set_error_literal ()</h3>
    859. 

  859. <pre class="programlisting"><span class="returnvalue">void</span>                g_set_error_literal                 (<em class="parameter"><code><a class="link" href="glib-Error-Reporting.html#GError" title="GError"><span class="type">GError</span></a> **err</code></em>,
    860. 

  860.                                                          <em class="parameter"><code><a class="link" href="glib-Quarks.html#GQuark" title="GQuark"><span class="type">GQuark</span></a> domain</code></em>,
    861. 

  861.                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="type">gint</span></a> code</code></em>,
    862. 

  862.                                                          <em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *message</code></em>);</pre>
    863. 

  863. <p>
    864. 

  864. Does nothing if <em class="parameter"><code>err</code></em> is <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>; if <em class="parameter"><code>err</code></em> is non-<a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>, then *<em class="parameter"><code>err</code></em>
    865. 

  865. must be <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>. A new <a class="link" href="glib-Error-Reporting.html#GError" title="GError"><span class="type">GError</span></a> is created and assigned to *<em class="parameter"><code>err</code></em>.
    866. 

  866. Unlike <a class="link" href="glib-Error-Reporting.html#g-set-error" title="g_set_error ()"><code class="function">g_set_error()</code></a>, <em class="parameter"><code>message</code></em> is not a <code class="function">printf()</code>-style format string.
    867. 

  867. Use this function if <em class="parameter"><code>message</code></em> contains text you don't have control over,
    868. 

  868. that could include <code class="function">printf()</code> escape sequences.
    869. 

  869. </p>
    870. 

  870. <div class="variablelist"><table border="0">
    871. 

  871. <col align="left" valign="top">
    872. 

  872. <tbody>
    873. 

  873. <tr>
    874. 

  874. <td><p><span class="term"><em class="parameter"><code>err</code></em> :</span></p></td>
    875. 

  875. <td>a return location for a <a class="link" href="glib-Error-Reporting.html#GError" title="GError"><span class="type">GError</span></a>, or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>
    876. 

  876. </td>
    877. 

  877. </tr>
    878. 

  878. <tr>
    879. 

  879. <td><p><span class="term"><em class="parameter"><code>domain</code></em> :</span></p></td>
    880. 

  880. <td>error domain
    881. 

  881. </td>
    882. 

  882. </tr>
    883. 

  883. <tr>
    884. 

  884. <td><p><span class="term"><em class="parameter"><code>code</code></em> :</span></p></td>
    885. 

  885. <td>error code
    886. 

  886. </td>
    887. 

  887. </tr>
    888. 

  888. <tr>
    889. 

  889. <td><p><span class="term"><em class="parameter"><code>message</code></em> :</span></p></td>
    890. 

  890. <td>error message
    891. 

  891. </td>
    892. 

  892. </tr>
    893. 

  893. </tbody>
    894. 

  894. </table></div>
    895. 

  895. <p class="since">Since 2.18</p>
    896. 

  896. </div>
    897. 

  897. <hr>
    898. 

  898. <div class="refsect2">
    899. 

  899. <a name="g-propagate-error"></a><h3>g_propagate_error ()</h3>
    900. 

  900. <pre class="programlisting"><span class="returnvalue">void</span>                g_propagate_error                   (<em class="parameter"><code><a class="link" href="glib-Error-Reporting.html#GError" title="GError"><span class="type">GError</span></a> **dest</code></em>,
    901. 

  901.                                                          <em class="parameter"><code><a class="link" href="glib-Error-Reporting.html#GError" title="GError"><span class="type">GError</span></a> *src</code></em>);</pre>
    902. 

  902. <p>
    903. 

  903. If <em class="parameter"><code>dest</code></em> is <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>, free <em class="parameter"><code>src</code></em>; otherwise, moves <em class="parameter"><code>src</code></em> into *<em class="parameter"><code>dest</code></em>.
    904. 

  904. The error variable <em class="parameter"><code>dest</code></em> points to must be <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>.
    905. 

  905. </p>
    906. 

  906. <div class="variablelist"><table border="0">
    907. 

  907. <col align="left" valign="top">
    908. 

  908. <tbody>
    909. 

  909. <tr>
    910. 

  910. <td><p><span class="term"><em class="parameter"><code>dest</code></em> :</span></p></td>
    911. 

  911. <td>error return location
    912. 

  912. </td>
    913. 

  913. </tr>
    914. 

  914. <tr>
    915. 

  915. <td><p><span class="term"><em class="parameter"><code>src</code></em> :</span></p></td>
    916. 

  916. <td>error to move into the return location
    917. 

  917. </td>
    918. 

  918. </tr>
    919. 

  919. </tbody>
    920. 

  920. </table></div>
    921. 

  921. </div>
    922. 

  922. <hr>
    923. 

  923. <div class="refsect2">
    924. 

  924. <a name="g-clear-error"></a><h3>g_clear_error ()</h3>
    925. 

  925. <pre class="programlisting"><span class="returnvalue">void</span>                g_clear_error                       (<em class="parameter"><code><a class="link" href="glib-Error-Reporting.html#GError" title="GError"><span class="type">GError</span></a> **err</code></em>);</pre>
    926. 

  926. <p>
    927. 

  927. If <em class="parameter"><code>err</code></em> is <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>, does nothing. If <em class="parameter"><code>err</code></em> is non-<a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>,
    928. 

  928. calls <a class="link" href="glib-Error-Reporting.html#g-error-free" title="g_error_free ()"><code class="function">g_error_free()</code></a> on *<em class="parameter"><code>err</code></em> and sets *<em class="parameter"><code>err</code></em> to <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>.
    929. 

  929. </p>
    930. 

  930. <div class="variablelist"><table border="0">
    931. 

  931. <col align="left" valign="top">
    932. 

  932. <tbody><tr>
    933. 

  933. <td><p><span class="term"><em class="parameter"><code>err</code></em> :</span></p></td>
    934. 

  934. <td>a <a class="link" href="glib-Error-Reporting.html#GError" title="GError"><span class="type">GError</span></a> return location
    935. 

  935. </td>
    936. 

  936. </tr></tbody>
    937. 

  937. </table></div>
    938. 

  938. </div>
    939. 

  939. <hr>
    940. 

  940. <div class="refsect2">
    941. 

  941. <a name="g-prefix-error"></a><h3>g_prefix_error ()</h3>
    942. 

  942. <pre class="programlisting"><span class="returnvalue">void</span>                g_prefix_error                      (<em class="parameter"><code><a class="link" href="glib-Error-Reporting.html#GError" title="GError"><span class="type">GError</span></a> **err</code></em>,
    943. 

  943.                                                          <em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *format</code></em>,
    944. 

  944.                                                          <em class="parameter"><code>...</code></em>);</pre>
    945. 

  945. <p>
    946. 

  946. Formats a string according to <em class="parameter"><code>format</code></em> and
    947. 

  947. prefix it to an existing error message.  If
    948. 

  948. <em class="parameter"><code>err</code></em> is <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> (ie: no error variable) then do
    949. 

  949. nothing.
    950. 

  950. </p>
    951. 

  951. <p>
    952. 

  952. If *<em class="parameter"><code>err</code></em> is <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> (ie: an error variable is
    953. 

  953. present but there is no error condition) then
    954. 

  954. also do nothing.  Whether or not it makes
    955. 

  955. sense to take advantage of this feature is up
    956. 

  956. to you.
    957. 

  957. </p>
    958. 

  958. <div class="variablelist"><table border="0">
    959. 

  959. <col align="left" valign="top">
    960. 

  960. <tbody>
    961. 

  961. <tr>
    962. 

  962. <td><p><span class="term"><em class="parameter"><code>err</code></em> :</span></p></td>
    963. 

  963. <td>a return location for a <a class="link" href="glib-Error-Reporting.html#GError" title="GError"><span class="type">GError</span></a>, or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>
    964. 

  964. </td>
    965. 

  965. </tr>
    966. 

  966. <tr>
    967. 

  967. <td><p><span class="term"><em class="parameter"><code>format</code></em> :</span></p></td>
    968. 

  968. <td>printf()-style format string
    969. 

  969. </td>
    970. 

  970. </tr>
    971. 

  971. <tr>
    972. 

  972. <td><p><span class="term"><em class="parameter"><code>...</code></em> :</span></p></td>
    973. 

  973. <td>arguments to <em class="parameter"><code>format</code></em>
    974. 

  974. </td>
    975. 

  975. </tr>
    976. 

  976. </tbody>
    977. 

  977. </table></div>
    978. 

  978. <p class="since">Since 2.16</p>
    979. 

  979. </div>
    980. 

  980. <hr>
    981. 

  981. <div class="refsect2">
    982. 

  982. <a name="g-propagate-prefixed-error"></a><h3>g_propagate_prefixed_error ()</h3>
    983. 

  983. <pre class="programlisting"><span class="returnvalue">void</span>                g_propagate_prefixed_error          (<em class="parameter"><code><a class="link" href="glib-Error-Reporting.html#GError" title="GError"><span class="type">GError</span></a> **dest</code></em>,
    984. 

  984.                                                          <em class="parameter"><code><a class="link" href="glib-Error-Reporting.html#GError" title="GError"><span class="type">GError</span></a> *src</code></em>,
    985. 

  985.                                                          <em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *format</code></em>,
    986. 

  986.                                                          <em class="parameter"><code>...</code></em>);</pre>
    987. 

  987. <p>
    988. 

  988. If <em class="parameter"><code>dest</code></em> is <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>, free <em class="parameter"><code>src</code></em>; otherwise,
    989. 

  989. moves <em class="parameter"><code>src</code></em> into *<em class="parameter"><code>dest</code></em>. *<em class="parameter"><code>dest</code></em> must be <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>.
    990. 

  990. After the move, add a prefix as with
    991. 

  991. <a class="link" href="glib-Error-Reporting.html#g-prefix-error" title="g_prefix_error ()"><code class="function">g_prefix_error()</code></a>.
    992. 

  992. </p>
    993. 

  993. <div class="variablelist"><table border="0">
    994. 

  994. <col align="left" valign="top">
    995. 

  995. <tbody>
    996. 

  996. <tr>
    997. 

  997. <td><p><span class="term"><em class="parameter"><code>dest</code></em> :</span></p></td>
    998. 

  998. <td>error return location
    999. 

  999. </td>
    1000. 

  1000. </tr>
    1001. 

  1001. <tr>
    1002. 

  1002. <td><p><span class="term"><em class="parameter"><code>src</code></em> :</span></p></td>
    1003. 

  1003. <td>error to move into the return location
    1004. 

  1004. </td>
    1005. 

  1005. </tr>
    1006. 

  1006. <tr>
    1007. 

  1007. <td><p><span class="term"><em class="parameter"><code>format</code></em> :</span></p></td>
    1008. 

  1008. <td>printf()-style format string
    1009. 

  1009. </td>
    1010. 

  1010. </tr>
    1011. 

  1011. <tr>
    1012. 

  1012. <td><p><span class="term"><em class="parameter"><code>...</code></em> :</span></p></td>
    1013. 

  1013. <td>arguments to <em class="parameter"><code>format</code></em>
    1014. 

  1014. </td>
    1015. 

  1015. </tr>
    1016. 

  1016. </tbody>
    1017. 

  1017. </table></div>
    1018. 

  1018. <p class="since">Since 2.16</p>
    1019. 

  1019. </div>
    1020. 

  1020. </div>
    1021. 

  1021. </div>
    1022. 

  1022. <div class="footer">
    1023. 

  1023. <hr>
    1024. 

  1024.           Generated by GTK-Doc V1.15.1</div>
    1025. 

  1025. </body>
    1026. 

  1026. </html>
    1027.