PageRenderTime 195ms CodeModel.GetById 21ms RepoModel.GetById 0ms app.codeStats 1ms

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

https://bitbucket.org/kokua/3p-glib
HTML | 1232 lines | 1204 code | 28 blank | 0 comment | 0 complexity | ca0d5e392677eda092891cc5ca04e263 MD5 | raw file
Possible License(s): LGPL-2.0, AGPL-3.0

Large files files are truncated, but you can click here to view the full file

    

  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: GLib Reference Manual</title>
    6. 

  6. <meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
    7. 

  7. <link rel="home" href="index.html" title="GLib Reference Manual">
    8. 

  8. <link rel="up" href="glib-core.html" title="GLib Core Application Support">
    9. 

  9. <link rel="prev" href="glib-IO-Channels.html" title="IO Channels">
    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.21.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="5"><tr valign="middle">
    16. 

  16. <td width="100%" align="left" class="shortcuts">
    17. 

  17. <a href="#" class="shortcut">Top</a><span id="nav_description">  <span class="dim">|</span> 
    18. 

  18.                   <a href="#glib-Error-Reporting.description" class="shortcut">Description</a></span>
    19. 

  19. </td>
    20. 

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

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

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

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

  24. </tr></table>
    25. 

  25. <div class="refentry">
    26. 

  26. <a name="glib-Error-Reporting"></a><div class="titlepage"></div>
    27. 

  27. <div class="refnamediv"><table width="100%"><tr>
    28. 

  28. <td valign="top">
    29. 

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

  30. <p>Error Reporting — a system for reporting errors</p>
    31. 

  31. </td>
    32. 

  32. <td class="gallery_image" valign="top" align="right"></td>
    33. 

  33. </tr></table></div>
    34. 

  34. <div class="refsect1">
    35. 

  35. <a name="glib-Error-Reporting.functions"></a><h2>Functions</h2>
    36. 

  36. <div class="informaltable"><table width="100%" border="0">
    37. 

  37. <colgroup>
    38. 

  38. <col width="150px" class="functions_return">
    39. 

  39. <col class="functions_name">
    40. 

  40. </colgroup>
    41. 

  41. <tbody>
    42. 

  42. <tr>
    43. 

  43. <td class="function_type">
    44. 

  44. <a class="link" href="glib-Error-Reporting.html#GError" title="struct GError"><span class="returnvalue">GError</span></a> *
    45. 

  45. </td>
    46. 

  46. <td class="function_name">
    47. 

  47. <a class="link" href="glib-Error-Reporting.html#g-error-new" title="g_error_new ()">g_error_new</a> <span class="c_punctuation">()</span>
    48. 

  48. </td>
    49. 

  49. </tr>
    50. 

  50. <tr>
    51. 

  51. <td class="function_type">
    52. 

  52. <a class="link" href="glib-Error-Reporting.html#GError" title="struct GError"><span class="returnvalue">GError</span></a> *
    53. 

  53. </td>
    54. 

  54. <td class="function_name">
    55. 

  55. <a class="link" href="glib-Error-Reporting.html#g-error-new-literal" title="g_error_new_literal ()">g_error_new_literal</a> <span class="c_punctuation">()</span>
    56. 

  56. </td>
    57. 

  57. </tr>
    58. 

  58. <tr>
    59. 

  59. <td class="function_type">
    60. 

  60. <a class="link" href="glib-Error-Reporting.html#GError" title="struct GError"><span class="returnvalue">GError</span></a> *
    61. 

  61. </td>
    62. 

  62. <td class="function_name">
    63. 

  63. <a class="link" href="glib-Error-Reporting.html#g-error-new-valist" title="g_error_new_valist ()">g_error_new_valist</a> <span class="c_punctuation">()</span>
    64. 

  64. </td>
    65. 

  65. </tr>
    66. 

  66. <tr>
    67. 

  67. <td class="function_type">
    68. 

  68. <span class="returnvalue">void</span>
    69. 

  69. </td>
    70. 

  70. <td class="function_name">
    71. 

  71. <a class="link" href="glib-Error-Reporting.html#g-error-free" title="g_error_free ()">g_error_free</a> <span class="c_punctuation">()</span>
    72. 

  72. </td>
    73. 

  73. </tr>
    74. 

  74. <tr>
    75. 

  75. <td class="function_type">
    76. 

  76. <a class="link" href="glib-Error-Reporting.html#GError" title="struct GError"><span class="returnvalue">GError</span></a> *
    77. 

  77. </td>
    78. 

  78. <td class="function_name">
    79. 

  79. <a class="link" href="glib-Error-Reporting.html#g-error-copy" title="g_error_copy ()">g_error_copy</a> <span class="c_punctuation">()</span>
    80. 

  80. </td>
    81. 

  81. </tr>
    82. 

  82. <tr>
    83. 

  83. <td class="function_type">
    84. 

  84. <a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>
    85. 

  85. </td>
    86. 

  86. <td class="function_name">
    87. 

  87. <a class="link" href="glib-Error-Reporting.html#g-error-matches" title="g_error_matches ()">g_error_matches</a> <span class="c_punctuation">()</span>
    88. 

  88. </td>
    89. 

  89. </tr>
    90. 

  90. <tr>
    91. 

  91. <td class="function_type">
    92. 

  92. <span class="returnvalue">void</span>
    93. 

  93. </td>
    94. 

  94. <td class="function_name">
    95. 

  95. <a class="link" href="glib-Error-Reporting.html#g-set-error" title="g_set_error ()">g_set_error</a> <span class="c_punctuation">()</span>
    96. 

  96. </td>
    97. 

  97. </tr>
    98. 

  98. <tr>
    99. 

  99. <td class="function_type">
    100. 

  100. <span class="returnvalue">void</span>
    101. 

  101. </td>
    102. 

  102. <td class="function_name">
    103. 

  103. <a class="link" href="glib-Error-Reporting.html#g-set-error-literal" title="g_set_error_literal ()">g_set_error_literal</a> <span class="c_punctuation">()</span>
    104. 

  104. </td>
    105. 

  105. </tr>
    106. 

  106. <tr>
    107. 

  107. <td class="function_type">
    108. 

  108. <span class="returnvalue">void</span>
    109. 

  109. </td>
    110. 

  110. <td class="function_name">
    111. 

  111. <a class="link" href="glib-Error-Reporting.html#g-propagate-error" title="g_propagate_error ()">g_propagate_error</a> <span class="c_punctuation">()</span>
    112. 

  112. </td>
    113. 

  113. </tr>
    114. 

  114. <tr>
    115. 

  115. <td class="function_type">
    116. 

  116. <span class="returnvalue">void</span>
    117. 

  117. </td>
    118. 

  118. <td class="function_name">
    119. 

  119. <a class="link" href="glib-Error-Reporting.html#g-clear-error" title="g_clear_error ()">g_clear_error</a> <span class="c_punctuation">()</span>
    120. 

  120. </td>
    121. 

  121. </tr>
    122. 

  122. <tr>
    123. 

  123. <td class="function_type">
    124. 

  124. <span class="returnvalue">void</span>
    125. 

  125. </td>
    126. 

  126. <td class="function_name">
    127. 

  127. <a class="link" href="glib-Error-Reporting.html#g-prefix-error" title="g_prefix_error ()">g_prefix_error</a> <span class="c_punctuation">()</span>
    128. 

  128. </td>
    129. 

  129. </tr>
    130. 

  130. <tr>
    131. 

  131. <td class="function_type">
    132. 

  132. <span class="returnvalue">void</span>
    133. 

  133. </td>
    134. 

  134. <td class="function_name">
    135. 

  135. <a class="link" href="glib-Error-Reporting.html#g-propagate-prefixed-error" title="g_propagate_prefixed_error ()">g_propagate_prefixed_error</a> <span class="c_punctuation">()</span>
    136. 

  136. </td>
    137. 

  137. </tr>
    138. 

  138. </tbody>
    139. 

  139. </table></div>
    140. 

  140. </div>
    141. 

  141. <div class="refsect1">
    142. 

  142. <a name="glib-Error-Reporting.other"></a><h2>Types and Values</h2>
    143. 

  143. <div class="informaltable"><table width="100%" border="0">
    144. 

  144. <colgroup>
    145. 

  145. <col width="150px" class="name">
    146. 

  146. <col class="description">
    147. 

  147. </colgroup>
    148. 

  148. <tbody><tr>
    149. 

  149. <td class="datatype_keyword">struct</td>
    150. 

  150. <td class="function_name"><a class="link" href="glib-Error-Reporting.html#GError" title="struct GError">GError</a></td>
    151. 

  151. </tr></tbody>
    152. 

  152. </table></div>
    153. 

  153. </div>
    154. 

  154. <div class="refsect1">
    155. 

  155. <a name="glib-Error-Reporting.includes"></a><h2>Includes</h2>
    156. 

  156. <pre class="synopsis">#include &lt;glib.h&gt;
    157. 

  157. </pre>
    158. 

  158. </div>
    159. 

  159. <div class="refsect1">
    160. 

  160. <a name="glib-Error-Reporting.description"></a><h2>Description</h2>
    161. 

  161. <p>GLib provides a standard method of reporting errors from a called
    162. 

  162. function to the calling code. (This is the same problem solved by
    163. 

  163. exceptions in other languages.) It's important to understand that
    164. 

  164. this method is both a data type (the <a class="link" href="glib-Error-Reporting.html#GError" title="struct GError"><span class="type">GError</span></a> struct) and a set of
    165. 

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

  166. properly interoperate with other code that uses <a class="link" href="glib-Error-Reporting.html#GError" title="struct GError"><span class="type">GError</span></a>, and users
    167. 

  167. of your API will probably get confused.</p>
    168. 

  168. <p>First and foremost: <a class="link" href="glib-Error-Reporting.html#GError" title="struct GError"><span class="type">GError</span></a> should only be used to report recoverable
    169. 

  169. runtime errors, never to report programming errors. If the programmer
    170. 

  170. 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>, <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>,
    171. 

  171. <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. (Incidentally,
    172. 

  172. 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 only be used for
    173. 

  173. programming errors, it should not be used to print any error
    174. 

  174. reportable via <a class="link" href="glib-Error-Reporting.html#GError" title="struct GError"><span class="type">GError</span></a>.)</p>
    175. 

  175. <p>Examples of recoverable runtime errors are "file not found" or
    176. 

  176. "failed to parse input." Examples of programming errors are "NULL
    177. 

  177. passed to <code class="function">strcmp()</code>" or "attempted to free the same pointer twice."
    178. 

  178. These two kinds of errors are fundamentally different: runtime errors
    179. 

  179. should be handled or reported to the user, programming errors should
    180. 

  180. be eliminated by fixing the bug in the program. This is why most
    181. 

  181. functions in GLib and GTK+ do not use the <a class="link" href="glib-Error-Reporting.html#GError" title="struct GError"><span class="type">GError</span></a> facility.</p>
    182. 

  182. <p>Functions that can fail take a return location for a <a class="link" href="glib-Error-Reporting.html#GError" title="struct GError"><span class="type">GError</span></a> as their
    183. 

  183. last argument. On error, a new <a class="link" href="glib-Error-Reporting.html#GError" title="struct GError"><span class="type">GError</span></a> instance will be allocated and
    184. 

  184. returned to the caller via this argument. For example:</p>
    185. 

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

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

  187.     <tbody>
    188. 

  188.       <tr>
    189. 

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

  190. 2
    191. 

  191. 3
    192. 

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

  193.         <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>
    194. 

  194. <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>
    195. 

  195. <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>
    196. 

  196. <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>
    197. 

  197.       </tr>
    198. 

  198.     </tbody>
    199. 

  199.   </table>
    200. 

  200. </div>
    201. 

  201. 

  202. <p>
    203. 

  203. 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
    204. 

  204. point to a location where an error can be placed. For example:</p>
    205. 

  205. <div class="informalexample">
    206. 

  206.   <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
    207. 

  207.     <tbody>
    208. 

  208.       <tr>
    209. 

  209.         <td class="listing_lines" align="right"><pre>1
    210. 

  210. 2
    211. 

  211. 3
    212. 

  212. 4
    213. 

  213. 5
    214. 

  214. 6
    215. 

  215. 7
    216. 

  216. 8
    217. 

  217. 9
    218. 

  218. 10
    219. 

  219. 11
    220. 

  220. 12
    221. 

  221. 13
    222. 

  222. 14
    223. 

  223. 15
    224. 

  224. 16
    225. 

  225. 17</pre></td>
    226. 

  226.         <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>
    227. 

  227. <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>
    228. 

  228. 

  229. <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>
    230. 

  230. <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>
    231. 

  231. <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>
    232. 

  232. <span class="normal">  </span><span class="cbracket">{</span>
    233. 

  233. <span class="normal">    </span><span class="comment">// Report error to user, and free error</span>
    234. 

  234. <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>
    235. 

  235. <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>
    236. 

  236. <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>
    237. 

  237. <span class="normal">  </span><span class="cbracket">}</span>
    238. 

  238. <span class="keyword">else</span>
    239. 

  239. <span class="normal">  </span><span class="cbracket">{</span>
    240. 

  240. <span class="normal">    </span><span class="comment">// Use file contents</span>
    241. 

  241. <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>
    242. 

  242. <span class="normal">  </span><span class="cbracket">}</span></pre></td>
    243. 

  243.       </tr>
    244. 

  244.     </tbody>
    245. 

  245.   </table>
    246. 

  246. </div>
    247. 

  247. 

  248. <p>
    249. 

  249. Note that <code class="literal">err != NULL</code> in this example is a reliable indicator
    250. 

  250. of whether <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,
    251. 

  251. <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 boolean which
    252. 

  252. indicates whether it was successful.</p>
    253. 

  253. <p>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
    254. 

  254. are only interested in whether it failed and don't need to display
    255. 

  255. an error message, you can pass <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> for the <em class="parameter"><code>error</code></em>
    256. 

  256.  argument:</p>
    257. 

  257. <div class="informalexample">
    258. 

  258.   <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
    259. 

  259.     <tbody>
    260. 

  260.       <tr>
    261. 

  261.         <td class="listing_lines" align="right"><pre>1
    262. 

  262. 2
    263. 

  263. 3
    264. 

  264. 4
    265. 

  265. 5
    266. 

  266. 6</pre></td>
    267. 

  267.         <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>
    268. 

  268. <span class="normal">  </span><span class="comment">// no error occurred </span>
    269. 

  269. <span class="normal">  </span><span class="symbol">;</span>
    270. 

  270. <span class="keyword">else</span>
    271. 

  271. <span class="normal">  </span><span class="comment">// error</span>
    272. 

  272. <span class="normal">  </span><span class="symbol">;</span></pre></td>
    273. 

  273.       </tr>
    274. 

  274.     </tbody>
    275. 

  275.   </table>
    276. 

  276. </div>
    277. 

  277. 

  278. <p></p>
    279. 

  279. <p>The <a class="link" href="glib-Error-Reporting.html#GError" title="struct GError"><span class="type">GError</span></a> object contains three fields: <em class="parameter"><code>domain</code></em>
    280. 

  280.  indicates the module
    281. 

  281. the error-reporting function is located in, <em class="parameter"><code>code</code></em>
    282. 

  282.  indicates the specific
    283. 

  283. error that occurred, and <em class="parameter"><code>message</code></em>
    284. 

  284.  is a user-readable error message with
    285. 

  285. as many details as possible. Several functions are provided to deal
    286. 

  286. with an error received from a called function: <a class="link" href="glib-Error-Reporting.html#g-error-matches" title="g_error_matches ()"><code class="function">g_error_matches()</code></a>
    287. 

  287. 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,
    288. 

  288. <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
    289. 

  289. calling 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
    290. 

  290. error location by freeing the error and resetting the location to
    291. 

  291. <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>. To display an error to the user, simply display the <em class="parameter"><code>message</code></em>
    292. 

  292. ,
    293. 

  293. perhaps along with additional context known only to the calling
    294. 

  294. function (the file being opened, or whatever - though in the
    295. 

  295. <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, the <em class="parameter"><code>message</code></em>
    296. 

  296.  already contains a filename).</p>
    297. 

  297. <p>When implementing a function that can report errors, the basic
    298. 

  298. tool is <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
    299. 

  299. 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>, 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>
    300. 

  300. does nothing if the error location passed to it is <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>.
    301. 

  301. Here's an example:</p>
    302. 

  302. <div class="informalexample">
    303. 

  303.   <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
    304. 

  304.     <tbody>
    305. 

  305.       <tr>
    306. 

  306.         <td class="listing_lines" align="right"><pre>1
    307. 

  307. 2
    308. 

  308. 3
    309. 

  309. 4
    310. 

  310. 5
    311. 

  311. 6
    312. 

  312. 7
    313. 

  313. 8
    314. 

  314. 9
    315. 

  315. 10
    316. 

  316. 11
    317. 

  317. 12
    318. 

  318. 13
    319. 

  319. 14
    320. 

  320. 15
    321. 

  321. 16
    322. 

  322. 17
    323. 

  323. 18
    324. 

  324. 19</pre></td>
    325. 

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

  326. <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>
    327. 

  327. <span class="cbracket">{</span>
    328. 

  328. <span class="normal">  </span><span class="usertype">gint</span><span class="normal"> fd</span><span class="symbol">;</span>
    329. 

  329. 

  330. <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>
    331. 

  331. 

  332. <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>
    333. 

  333. <span class="normal">    </span><span class="cbracket">{</span>
    334. 

  334. <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>
    335. 

  335. <span class="normal">                   FOO_ERROR</span><span class="symbol">,</span><span class="normal">                 </span><span class="comment">// error domain</span>
    336. 

  336. <span class="normal">                   FOO_ERROR_BLAH</span><span class="symbol">,</span><span class="normal">            </span><span class="comment">// error code</span>
    337. 

  337. <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>
    338. 

  338. <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>
    339. 

  339. <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>
    340. 

  340. <span class="normal">    </span><span class="cbracket">}</span>
    341. 

  341. <span class="normal">  </span><span class="keyword">else</span>
    342. 

  342. <span class="normal">    </span><span class="keyword">return</span><span class="normal"> fd</span><span class="symbol">;</span>
    343. 

  343. <span class="cbracket">}</span></pre></td>
    344. 

  344.       </tr>
    345. 

  345.     </tbody>
    346. 

  346.   </table>
    347. 

  347. </div>
    348. 

  348. 

  349. <p></p>
    350. 

  350. <p>Things are somewhat more complicated if you yourself call another
    351. 

  351. function that can report a <a class="link" href="glib-Error-Reporting.html#GError" title="struct GError"><span class="type">GError</span></a>. If the sub-function indicates
    352. 

  352. fatal errors in some way other than reporting a <a class="link" href="glib-Error-Reporting.html#GError" title="struct GError"><span class="type">GError</span></a>, such as
    353. 

  353. by returning <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> on success, you can simply do the following:</p>
    354. 

  354. <div class="informalexample">
    355. 

  355.   <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
    356. 

  356.     <tbody>
    357. 

  357.       <tr>
    358. 

  358.         <td class="listing_lines" align="right"><pre>1
    359. 

  359. 2
    360. 

  360. 3
    361. 

  361. 4
    362. 

  362. 5
    363. 

  363. 6
    364. 

  364. 7
    365. 

  365. 8
    366. 

  366. 9
    367. 

  367. 10
    368. 

  368. 11
    369. 

  369. 12
    370. 

  370. 13
    371. 

  371. 14
    372. 

  372. 15</pre></td>
    373. 

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

  374. <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>
    375. 

  375. <span class="cbracket">{</span>
    376. 

  376. <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>
    377. 

  377. 

  378. <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>
    379. 

  379. <span class="normal">    </span><span class="cbracket">{</span>
    380. 

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

  381. <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>
    382. 

  382. <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>
    383. 

  383. <span class="normal">    </span><span class="cbracket">}</span>
    384. 

  384. 

  385. <span class="normal">  </span><span class="comment">// otherwise continue, no error occurred</span>
    386. 

  386. <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>
    387. 

  387. <span class="cbracket">}</span></pre></td>
    388. 

  388.       </tr>
    389. 

  389.     </tbody>
    390. 

  390.   </table>
    391. 

  391. </div>
    392. 

  392. 

  393. <p></p>
    394. 

  394. <p>If the sub-function does not indicate errors other than by
    395. 

  395. reporting a <a class="link" href="glib-Error-Reporting.html#GError" title="struct GError"><span class="type">GError</span></a> (or if its return value does not reliably indicate
    396. 

  396. errors) you need to create a temporary <a class="link" href="glib-Error-Reporting.html#GError" title="struct GError"><span class="type">GError</span></a>
    397. 

  397. 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>. <a class="link" href="glib-Error-Reporting.html#g-propagate-error" title="g_propagate_error ()"><code class="function">g_propagate_error()</code></a> is
    398. 

  398. intended for use in this case.</p>
    399. 

  399. <div class="informalexample">
    400. 

  400.   <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
    401. 

  401.     <tbody>
    402. 

  402.       <tr>
    403. 

  403.         <td class="listing_lines" align="right"><pre>1
    404. 

  404. 2
    405. 

  405. 3
    406. 

  406. 4
    407. 

  407. 5
    408. 

  408. 6
    409. 

  409. 7
    410. 

  410. 8
    411. 

  411. 9
    412. 

  412. 10
    413. 

  413. 11
    414. 

  414. 12
    415. 

  415. 13
    416. 

  416. 14
    417. 

  417. 15
    418. 

  418. 16
    419. 

  419. 17
    420. 

  420. 18
    421. 

  421. 19
    422. 

  422. 20</pre></td>
    423. 

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

  424. <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>
    425. 

  425. <span class="cbracket">{</span>
    426. 

  426. <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>
    427. 

  427. 

  428. <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>
    429. 

  429. 

  430. <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>
    431. 

  431. <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>
    432. 

  432. 

  433. <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>
    434. 

  434. <span class="normal">    </span><span class="cbracket">{</span>
    435. 

  435. <span class="normal">      </span><span class="comment">// store tmp_error in err, if err != NULL,</span>
    436. 

  436. <span class="normal">      </span><span class="comment">// otherwise call g_error_free() on tmp_error</span>
    437. 

  437. <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>
    438. 

  438. <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>
    439. 

  439. <span class="normal">    </span><span class="cbracket">}</span>
    440. 

  440. 

  441. <span class="normal">  </span><span class="comment">// otherwise continue, no error occurred</span>
    442. 

  442. <span class="cbracket">}</span></pre></td>
    443. 

  443.       </tr>
    444. 

  444.     </tbody>
    445. 

  445.   </table>
    446. 

  446. </div>
    447. 

  447. 

  448. <p></p>
    449. 

  449. <p>Error pileups are always a bug. For example, this code is incorrect:</p>
    450. 

  450. <div class="informalexample">
    451. 

  451.   <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
    452. 

  452.     <tbody>
    453. 

  453.       <tr>
    454. 

  454.         <td class="listing_lines" align="right"><pre>1
    455. 

  455. 2
    456. 

  456. 3
    457. 

  457. 4
    458. 

  458. 5
    459. 

  459. 6
    460. 

  460. 7
    461. 

  461. 8
    462. 

  462. 9
    463. 

  463. 10
    464. 

  464. 11
    465. 

  465. 12
    466. 

  466. 13
    467. 

  467. 14
    468. 

  468. 15
    469. 

  469. 16
    470. 

  470. 17</pre></td>
    471. 

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

  472. <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>
    473. 

  473. <span class="cbracket">{</span>
    474. 

  474. <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>
    475. 

  475. 

  476. <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>
    477. 

  477. 

  478. <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>
    479. 

  479. <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>
    480. 

  480. <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>
    481. 

  481. 

  482. <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>
    483. 

  483. <span class="normal">    </span><span class="cbracket">{</span>
    484. 

  484. <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>
    485. 

  485. <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>
    486. 

  486. <span class="normal">    </span><span class="cbracket">}</span>
    487. 

  487. <span class="cbracket">}</span></pre></td>
    488. 

  488.       </tr>
    489. 

  489.     </tbody>
    490. 

  490.   </table>
    491. 

  491. </div>
    492. 

  492. 

  493. <p>
    494. 

  494. <em class="parameter"><code>tmp_error</code></em>
    495. 

  495.  should be checked immediately after <code class="function">sub_function_that_can_fail()</code>,
    496. 

  496. and either cleared or propagated upward. The rule is: after each error,
    497. 

  497. you must either handle the error, or return it to the calling function.</p>
    498. 

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

  499. of handling an error by always doing nothing about it. So the
    500. 

  500. following code is fine, assuming errors in <code class="function">sub_function_that_can_fail()</code>
    501. 

  501. are not fatal to <code class="function">my_function_that_can_fail()</code>:</p>
    502. 

  502. <div class="informalexample">
    503. 

  503.   <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
    504. 

  504.     <tbody>
    505. 

  505.       <tr>
    506. 

  506.         <td class="listing_lines" align="right"><pre>1
    507. 

  507. 2
    508. 

  508. 3
    509. 

  509. 4
    510. 

  510. 5
    511. 

  511. 6
    512. 

  512. 7
    513. 

  513. 8
    514. 

  514. 9
    515. 

  515. 10
    516. 

  516. 11
    517. 

  517. 12
    518. 

  518. 13
    519. 

  519. 14
    520. 

  520. 15
    521. 

  521. 16
    522. 

  522. 17
    523. 

  523. 18</pre></td>
    524. 

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

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

  526. <span class="cbracket">{</span>
    527. 

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

  528. 

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

  530. 

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

  532. 

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

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

  535. 

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

  537. <span class="normal">    </span><span class="cbracket">{</span>
    538. 

  538. <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>
    539. 

  539. <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>
    540. 

  540. <span class="normal">    </span><span class="cbracket">}</span>
    541. 

  541. <span class="cbracket">}</span></pre></td>
    542. 

  542.       </tr>
    543. 

  543.     </tbody>
    544. 

  544.   </table>
    545. 

  545. </div>
    546. 

  546. 

  547. <p></p>
    548. 

  548. <p>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 ignores errors;
    549. 

  549. it's equivalent to
    550. 

  550. <code class="literal">try { <code class="function">sub_function_that_can_fail()</code>; } catch (...) {}</code>
    551. 

  551. in C++. It does not mean to leave errors unhandled; it means
    552. 

  552. to handle them by doing nothing.</p>
    553. 

  553. <p>Error domains and codes are conventionally named as follows:</p>
    554. 

  554. <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
    555. 

  555. <li class="listitem">
    556. 

  556. <p>The error domain is called &lt;NAMESPACE&gt;_&lt;MODULE&gt;_ERROR,
    557. 

  557. for example <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>:</p>
    558. 

  558. <div class="informalexample">
    559. 

  559.   <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
    560. 

  560.     <tbody>
    561. 

  561.       <tr>
    562. 

  562.         <td class="listing_lines" align="right"><pre>1
    563. 

  563. 2
    564. 

  564. 3
    565. 

  565. 4
    566. 

  566. 5
    567. 

  567. 6
    568. 

  568. 7</pre></td>
    569. 

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

  570. 

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

  572. <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>
    573. 

  573. <span class="cbracket">{</span>
    574. 

  574. <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>
    575. 

  575. <span class="cbracket">}</span></pre></td>
    576. 

  576.       </tr>
    577. 

  577.     </tbody>
    578. 

  578.   </table>
    579. 

  579. </div>
    580. 

  580. 

  581. <p></p>
    582. 

  582. </li>
    583. 

  583. <li class="listitem"><p>The quark function for the error domain is called
    584. 

  584. &lt;namespace&gt;_&lt;module&gt;_error_quark,
    585. 

  585. for example <code class="function">g_spawn_error_quark()</code> or <code class="function">g_thread_error_quark()</code>.</p></li>
    586. 

  586. <li class="listitem"><p>The error codes are in an enumeration called
    587. 

  587. &lt;Namespace&gt;&lt;Module&gt;Error;
    588. 

  588. for example, <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>.</p></li>
    589. 

  589. <li class="listitem"><p>Members of the error code enumeration are called
    590. 

  590. &lt;NAMESPACE&gt;_&lt;MODULE&gt;_ERROR_&lt;CODE&gt;,
    591. 

  591. 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>.</p></li>
    592. 

  592. <li class="listitem"><p>If there's a "generic" or "unknown" error code for unrecoverable
    593. 

  593. errors it doesn't make sense to distinguish with specific codes,
    594. 

  594. it should be called &lt;NAMESPACE&gt;_&lt;MODULE&gt;_ERROR_FAILED,
    595. 

  595. for example <a class="link" href="glib-Spawning-Processes.html#G-SPAWN-ERROR-FAILED:CAPS"><code class="literal">G_SPAWN_ERROR_FAILED</code></a>. In the case of error code
    596. 

  596. enumerations that may be extended in future releases, you should
    597. 

  597. generally not handle this error code explicitly, but should
    598. 

  598. instead treat any unrecognized error code as equivalent to
    599. 

  599. FAILED.</p></li>
    600. 

  600. </ul></div>
    601. 

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

  602. <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
    603. 

  603. <li class="listitem"><p>Do not report programming errors via <a class="link" href="glib-Error-Reporting.html#GError" title="struct GError"><span class="type">GError</span></a>.</p></li>
    604. 

  604. <li class="listitem"><p>The last argument of a function that returns an error should
    605. 

  605. be a location where a <a class="link" href="glib-Error-Reporting.html#GError" title="struct GError"><span class="type">GError</span></a> can be placed (i.e. "<a class="link" href="glib-Error-Reporting.html#GError" title="struct GError"><span class="type">GError</span></a>** error").
    606. 

  606. If <a class="link" href="glib-Error-Reporting.html#GError" title="struct GError"><span class="type">GError</span></a> is used with varargs, the <a class="link" href="glib-Error-Reporting.html#GError" title="struct GError"><span class="type">GError</span></a>** should be the last
    607. 

  607. argument before the "...".</p></li>
    608. 

  608. <li class="listitem"><p>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="struct GError"><span class="type">GError</span></a>** if they are not interested
    609. 

  609. in details of the exact error that occurred.</p></li>
    610. 

  610. <li class="listitem"><p>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="struct GError"><span class="type">GError</span></a>** argument, then errors should
    611. 

  611. not be returned to the caller, but your function should still
    612. 

  612. abort and return if an error occurs. That is, control flow should
    613. 

  613. not be affected by whether the caller wants to get a <a class="link" href="glib-Error-Reporting.html#GError" title="struct GError"><span class="type">GError</span></a>.</p></li>
    614. 

  614. <li class="listitem"><p>If a <a class="link" href="glib-Error-Reporting.html#GError" title="struct GError"><span class="type">GError</span></a> is reported, then your function by definition had a
    615. 

  615. fatal failure and did not complete whatever it was supposed to do.
    616. 

  616. If the failure was not fatal, then you handled it and you should not
    617. 

  617. report it. If it was fatal, then you must report it and discontinue
    618. 

  618. whatever you were doing immediately.</p></li>
    619. 

  619. <li class="listitem"><p>If a <a class="link" href="glib-Error-Reporting.html#GError" title="struct GError"><span class="type">GError</span></a> is reported, out parameters are not guaranteed to
    620. 

  620. be set to any defined value.</p></li>
    621. 

  621. <li class="listitem"><p>A <a class="link" href="glib-Error-Reporting.html#GError" title="struct 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
    622. 

  622. to a function that can report errors.</p></li>
    623. 

  623. <li class="listitem"><p>"Piling up" errors is always a bug. That is, if you assign a
    624. 

  624. new <a class="link" href="glib-Error-Reporting.html#GError" title="struct GError"><span class="type">GError</span></a> to a <a class="link" href="glib-Error-Reporting.html#GError" title="struct 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
    625. 

  625. the previous error, it indicates that you should have aborted
    626. 

  626. the operation instead of continuing. If you were able to continue,
    627. 

  627. you should have cleared 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>.
    628. 

  628. <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 if you pile up errors.</p></li>
    629. 

  629. <li class="listitem"><p>By convention, if you return a boolean value indicating success
    630. 

  630. 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.
    631. 

  631. &lt;footnote&gt;&lt;para&gt;Avoid creating functions which have a boolean
    632. 

  632. return value and a GError parameter, but where the boolean does
    633. 

  633. something other than signal whether the GError is set.  Among other
    634. 

  634. problems, it requires C callers to allocate a temporary error.  Instead,
    635. 

  635. provide a "gboolean *" out parameter. There are functions in GLib
    636. 

  636. itself such as <a class="link" href="glib-Key-value-file-parser.html#g-key-file-has-key" title="g_key_file_has_key ()"><code class="function">g_key_file_has_key()</code></a> that are deprecated because of this.
    637. 

  637. &lt;/para&gt;&lt;/footnote&gt;
    638. 

  638. If <a class="link" href="glib-Standard-Macros.html#FALSE:CAPS" title="FALSE"><code class="literal">FALSE</code></a> is
    639. 

  639. returned, the error must be set to a non-<a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> value.
    640. 

  640. &lt;footnote&gt;&lt;para&gt;One exception to this is that in situations that are
    641. 

  641. already considered to be undefined behaviour (such as when a
    642. 

  642. <a class="link" href="glib-Warnings-and-Assertions.html#g-return-val-if-fail" title="g_return_val_if_fail()"><code class="function">g_return_val_if_fail()</code></a> check fails), the error need not be set.
    643. 

  643. Instead of checking separately whether the error is set, callers
    644. 

  644. should ensure that they do not provoke undefined behaviour, then
    645. 

  645. assume that the error will be set on failure.&lt;/para&gt;&lt;/footnote&gt;</p></li>
    646. 

  646. <li class="listitem"><p>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
    647. 

  647. 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>
    648. 

  648. is 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,
    649. 

  649. then users must check whether an error was returned to see if the
    650. 

  650. function succeeded.</p></li>
    651. 

  651. <li class="listitem"><p>When implementing a function that ca…
    652.

Large files files are truncated, but you can click here to view the full file