PageRenderTime 103ms CodeModel.GetById 34ms app.highlight 58ms RepoModel.GetById 1ms app.codeStats 1ms

/3rd-party/glib-2.16.6/docs/reference/glib/html/glib-Error-Reporting.html

https://bitbucket.org/super119/plu2youku
HTML | 814 lines | 785 code | 29 blank | 0 comment | 0 complexity | abb6c10b6fae80e6d6a7f4e9a79c88fb MD5 | raw file
  1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
  2<html>
  3<head>
  4<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
  5<title>Error Reporting</title>
  6<meta name="generator" content="DocBook XSL Stylesheets V1.74.0">
  7<link rel="home" href="index.html" title="GLib Reference Manual">
  8<link rel="up" href="glib-core.html" title="GLib Core Application Support">
  9<link rel="prev" href="glib-IO-Channels.html" title="IO Channels">
 10<link rel="next" href="glib-Warnings-and-Assertions.html" title="Message Output and Debugging Functions">
 11<meta name="generator" content="GTK-Doc V1.10 (XML mode)">
 12<link rel="stylesheet" href="style.css" type="text/css">
 13<link rel="chapter" href="glib.html" title="GLib Overview">
 14<link rel="chapter" href="glib-fundamentals.html" title="GLib Fundamentals">
 15<link rel="chapter" href="glib-core.html" title="GLib Core Application Support">
 16<link rel="chapter" href="glib-utilities.html" title="GLib Utilities">
 17<link rel="chapter" href="glib-data-types.html" title="GLib Data Types">
 18<link rel="chapter" href="tools.html" title="GLib Tools">
 19<link rel="index" href="ix01.html" title="Index">
 20<link rel="index" href="ix02.html" title="Index of deprecated symbols">
 21<link rel="index" href="ix03.html" title="Index of new symbols in 2.2">
 22<link rel="index" href="ix04.html" title="Index of new symbols in 2.4">
 23<link rel="index" href="ix05.html" title="Index of new symbols in 2.6">
 24<link rel="index" href="ix06.html" title="Index of new symbols in 2.8">
 25<link rel="index" href="ix07.html" title="Index of new symbols in 2.10">
 26<link rel="index" href="ix08.html" title="Index of new symbols in 2.12">
 27<link rel="index" href="ix09.html" title="Index of new symbols in 2.14">
 28<link rel="index" href="ix10.html" title="Index of new symbols in 2.16">
 29</head>
 30<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
 31<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2">
 32<tr valign="middle">
 33<td><a accesskey="p" href="glib-IO-Channels.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
 34<td><a accesskey="u" href="glib-core.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
 35<td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
 36<th width="100%" align="center">GLib Reference Manual</th>
 37<td><a accesskey="n" href="glib-Warnings-and-Assertions.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
 38</tr>
 39<tr><td colspan="5" class="shortcuts"><nobr><a href="#glib-Error-Reporting.synopsis" class="shortcut">Top</a>
 40                   | 
 41                  <a href="#glib-Error-Reporting.description" class="shortcut">Description</a></nobr></td></tr>
 42</table>
 43<div class="refentry" lang="en">
 44<a name="glib-Error-Reporting"></a><div class="titlepage"></div>
 45<div class="refnamediv"><table width="100%"><tr>
 46<td valign="top">
 47<h2><span class="refentrytitle"><a name="glib-Error-Reporting.top_of_page"></a>Error Reporting</span></h2>
 48<p>Error Reporting — a system for reporting errors</p>
 49</td>
 50<td valign="top" align="right"></td>
 51</tr></table></div>
 52<div class="refsynopsisdiv">
 53<a name="glib-Error-Reporting.synopsis"></a><h2>Synopsis</h2>
 54<pre class="synopsis">
 55
 56#include &lt;glib.h&gt;
 57
 58                    <a class="link" href="glib-Error-Reporting.html#GError" title="GError">GError</a>;
 59<a class="link" href="glib-Error-Reporting.html#GError" title="GError">GError</a>*             <a class="link" href="glib-Error-Reporting.html#g-error-new" title="g_error_new ()">g_error_new</a>                         (<a class="link" href="glib-Quarks.html#GQuark" title="GQuark">GQuark</a> domain,
 60                                                         <a class="link" href="glib-Basic-Types.html#gint" title="gint">gint</a> code,
 61                                                         const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar">gchar</a> *format,
 62                                                         ...);
 63<a class="link" href="glib-Error-Reporting.html#GError" title="GError">GError</a>*             <a class="link" href="glib-Error-Reporting.html#g-error-new-literal" title="g_error_new_literal ()">g_error_new_literal</a>                 (<a class="link" href="glib-Quarks.html#GQuark" title="GQuark">GQuark</a> domain,
 64                                                         <a class="link" href="glib-Basic-Types.html#gint" title="gint">gint</a> code,
 65                                                         const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar">gchar</a> *message);
 66void                <a class="link" href="glib-Error-Reporting.html#g-error-free" title="g_error_free ()">g_error_free</a>                        (<a class="link" href="glib-Error-Reporting.html#GError" title="GError">GError</a> *error);
 67<a class="link" href="glib-Error-Reporting.html#GError" title="GError">GError</a>*             <a class="link" href="glib-Error-Reporting.html#g-error-copy" title="g_error_copy ()">g_error_copy</a>                        (const <a class="link" href="glib-Error-Reporting.html#GError" title="GError">GError</a> *error);
 68<a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean">gboolean</a>            <a class="link" href="glib-Error-Reporting.html#g-error-matches" title="g_error_matches ()">g_error_matches</a>                     (const <a class="link" href="glib-Error-Reporting.html#GError" title="GError">GError</a> *error,
 69                                                         <a class="link" href="glib-Quarks.html#GQuark" title="GQuark">GQuark</a> domain,
 70                                                         <a class="link" href="glib-Basic-Types.html#gint" title="gint">gint</a> code);
 71void                <a class="link" href="glib-Error-Reporting.html#g-set-error" title="g_set_error ()">g_set_error</a>                         (<a class="link" href="glib-Error-Reporting.html#GError" title="GError">GError</a> **err,
 72                                                         <a class="link" href="glib-Quarks.html#GQuark" title="GQuark">GQuark</a> domain,
 73                                                         <a class="link" href="glib-Basic-Types.html#gint" title="gint">gint</a> code,
 74                                                         const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar">gchar</a> *format,
 75                                                         ...);
 76void                <a class="link" href="glib-Error-Reporting.html#g-propagate-error" title="g_propagate_error ()">g_propagate_error</a>                   (<a class="link" href="glib-Error-Reporting.html#GError" title="GError">GError</a> **dest,
 77                                                         <a class="link" href="glib-Error-Reporting.html#GError" title="GError">GError</a> *src);
 78void                <a class="link" href="glib-Error-Reporting.html#g-clear-error" title="g_clear_error ()">g_clear_error</a>                       (<a class="link" href="glib-Error-Reporting.html#GError" title="GError">GError</a> **err);
 79void                <a class="link" href="glib-Error-Reporting.html#g-prefix-error" title="g_prefix_error ()">g_prefix_error</a>                      (<a class="link" href="glib-Error-Reporting.html#GError" title="GError">GError</a> **err,
 80                                                         const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar">gchar</a> *format,
 81                                                         ...);
 82void                <a class="link" href="glib-Error-Reporting.html#g-propagate-prefixed-error" title="g_propagate_prefixed_error ()">g_propagate_prefixed_error</a>          (<a class="link" href="glib-Error-Reporting.html#GError" title="GError">GError</a> **dest,
 83                                                         <a class="link" href="glib-Error-Reporting.html#GError" title="GError">GError</a> *src,
 84                                                         const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar">gchar</a> *format,
 85                                                         ...);
 86</pre>
 87</div>
 88<div class="refsect1" lang="en">
 89<a name="glib-Error-Reporting.description"></a><h2>Description</h2>
 90<p>
 91GLib provides a standard method of reporting errors from a called function to
 92the calling code. (This is the same problem solved by exceptions in other
 93languages.) It's important to understand that this method is both a
 94<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
 95rules.</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
 96properly 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
 97will probably get confused.
 98</p>
 99<p>
100First 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
101recoverable runtime errors, never to report programming errors.</em></span> If
102the 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>,
103<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.
104(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
105<span class="emphasis"><em>only</em></span> be used for programming errors, it should not be used
106to print any error reportable via <a class="link" href="glib-Error-Reporting.html#GError" title="GError"><span class="type">GError</span></a>.)
107</p>
108<p>
109Examples of recoverable runtime errors are "file not found" or "failed to parse
110input." Examples of programming errors are "NULL passed to <code class="function">strcmp()</code>" or
111"attempted to free the same pointer twice." These two kinds of errors are
112fundamentally different: runtime errors should be handled or reported to the
113user, programming errors should be eliminated by fixing the bug in the program.
114This 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.
115</p>
116<p>
117Functions 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. 
118For example:
119</p>
120<div class="informalexample"><pre class="programlisting">
121gboolean g_file_get_contents (const gchar *filename, 
122	                      gchar      **contents,
123                              gsize       *length,
124                              GError     **error);
125</pre></div>
126<p>
127If 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 
128point to a location where an error can be placed. For example:
129</p>
130<div class="informalexample"><pre class="programlisting">
131gchar *contents;
132GError *err = NULL;
133g_file_get_contents ("foo.txt", &amp;contents, NULL, &amp;err);
134g_assert ((contents == NULL &amp;&amp; err != NULL) || (contents != NULL &amp;&amp; err == NULL));
135if (err != NULL)
136  {
137    /* Report error to user, and free error */
138    g_assert (contents == NULL);
139    fprintf (stderr, "Unable to read file: %s\n", err-&gt;message);
140    g_error_free (err);
141  } 
142else
143  {
144    /* Use file contents */
145    g_assert (contents != NULL);
146  }
147</pre></div>
148<p>
149Note that <code class="literal">err != NULL</code> in this example is a
150<span class="emphasis"><em>reliable</em></span> indicator of whether
151<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
152a boolean which indicates whether it was successful.
153</p>
154<p>
155Because <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
156interested in whether it failed and don't need to display an error message, you
157can 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:
158</p>
159<div class="informalexample"><pre class="programlisting">
160if (g_file_get_contents ("foo.txt", &amp;contents, NULL, NULL)) /* ignore errors */
161  /* no error occurred */ ;
162else
163  /* error */ ;
164</pre></div>
165<p>
166</p>
167<p>
168The <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
169the module the error-reporting function is located in, <code class="literal">code</code>
170indicates the specific error that occurred, and <code class="literal">message</code> is a
171user-readable error message with as many details as possible. Several functions
172are provided to deal with an error received from a called function:
173<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,
174<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
175function 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
176freeing 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
177user, simply display <code class="literal">error-&gt;message</code>, perhaps along with
178additional context known only to the calling function (the file being opened, or
179whatever -- 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,
180<code class="literal">error-&gt;message</code> already contains a filename).
181</p>
182<p>
183When implementing a function that can report errors, the basic tool is
184<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>,
185then 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
186to it is <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>. Here's an example:
187</p>
188<div class="informalexample"><pre class="programlisting">
189gint
190foo_open_file (GError **error)
191{
192  gint fd;
193
194  fd = open ("file.txt", O_RDONLY);
195
196  if (fd &lt; 0)
197    {
198      g_set_error (error,
199                   FOO_ERROR,                 /* error domain */
200                   FOO_ERROR_BLAH,            /* error code */
201                   "Failed to open file: %s", /* error message format string */
202                   g_strerror (errno));
203      return -1;
204    }
205  else
206    return fd;
207}
208</pre></div>
209<p>
210</p>
211<p>
212Things are somewhat more complicated if you yourself call another function that
213can 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
214other 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
215simply do the following:
216</p>
217<div class="informalexample"><pre class="programlisting">
218gboolean
219my_function_that_can_fail (GError **err)
220{
221  g_return_val_if_fail (err == NULL || *err == NULL, FALSE);
222
223  if (!sub_function_that_can_fail (err))
224    {
225       /* assert that error was set by the sub-function */
226       g_assert (err == NULL || *err != NULL);  
227       return FALSE;
228    }
229
230  /* otherwise continue, no error occurred */
231  g_assert (err == NULL || *err == NULL);
232}
233</pre></div>
234<p>
235</p>
236<p>
237If 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>, 
238you 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>.
239<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.
240</p>
241<div class="informalexample"><pre class="programlisting">
242gboolean
243my_function_that_can_fail (GError **err)
244{
245  GError *tmp_error;
246
247  g_return_val_if_fail (err == NULL || *err == NULL, FALSE);
248
249  tmp_error = NULL;
250  sub_function_that_can_fail (&amp;tmp_error);
251
252  if (tmp_error != NULL)
253    {
254       /* store tmp_error in err, if err != NULL,
255        * otherwise call g_error_free() on tmp_error 
256        */
257       g_propagate_error (err, tmp_error);
258       return FALSE;
259    }
260
261  /* otherwise continue, no error occurred */
262}
263</pre></div>
264<p>
265</p>
266<p>
267Error pileups are always a bug. For example, this code is incorrect:
268</p>
269<div class="informalexample"><pre class="programlisting">
270gboolean
271my_function_that_can_fail (GError **err)
272{
273  GError *tmp_error;
274
275  g_return_val_if_fail (err == NULL || *err == NULL, FALSE);
276
277  tmp_error = NULL;
278  sub_function_that_can_fail (&amp;tmp_error);
279  other_function_that_can_fail (&amp;tmp_error);
280
281  if (tmp_error != NULL)
282    {
283       g_propagate_error (err, tmp_error);
284       return FALSE;
285    }
286}
287</pre></div>
288<p>
289<code class="literal">tmp_error</code> should be checked immediately after
290<code class="function"><code class="function">sub_function_that_can_fail()</code></code>, and either cleared or propagated upward.  The rule
291is: <span class="emphasis"><em>after each error, you must either handle the error, or return it to the
292calling 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
293equivalent of handling an error by always doing nothing about it. So the
294following code is fine, assuming errors in <code class="function"><code class="function">sub_function_that_can_fail()</code></code> are not
295fatal to <code class="function"><code class="function">my_function_that_can_fail()</code></code>:
296</p>
297<div class="informalexample"><pre class="programlisting">
298gboolean
299my_function_that_can_fail (GError **err)
300{
301  GError *tmp_error;
302
303  g_return_val_if_fail (err == NULL || *err == NULL, FALSE);
304
305  sub_function_that_can_fail (NULL); /* ignore errors */
306
307  tmp_error = NULL;
308  other_function_that_can_fail (&amp;tmp_error);
309
310  if (tmp_error != NULL)
311    {
312       g_propagate_error (err, tmp_error);
313       return FALSE;
314    }
315}
316</pre></div>
317<p>
318</p>
319<p>
320Note 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>
321errors; it's equivalent to <code class="literal">try { <code class="function">sub_function_that_can_fail()</code>; } catch
322(...) {}</code> in C++. It does <span class="emphasis"><em>not</em></span> mean to leave errors
323unhandled; it means to handle them by doing nothing.
324</p>
325<p>
326Error domains and codes are conventionally named as follows:
327</p>
328<div class="itemizedlist"><ul type="disc">
329<li>
330<p>
331The error domain is called 
332<code class="literal">&lt;NAMESPACE&gt;_&lt;MODULE&gt;_ERROR</code>, for example
333<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>:
334</p>
335<div class="informalexample"><pre class="programlisting">
336#define G_SPAWN_ERROR g_spawn_error_quark ()
337
338GQuark
339g_spawn_error_quark (void)
340{
341  return g_quark_from_static_string ("g-spawn-error-quark");
342}
343</pre></div>
344<p>
345</p>
346</li>
347<li><p>
348The error codes are in an enumeration called 
349<code class="literal">&lt;Namespace&gt;&lt;Module&gt;Error</code>; for example,
350<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>.
351</p></li>
352<li><p>
353Members 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>. 
354</p></li>
355<li><p>
356If there's a "generic" or "unknown" error code for unrecoverable errors it
357doesn't make sense to distinguish with specific codes, it should be called 
358<code class="literal">&lt;NAMESPACE&gt;_&lt;MODULE&gt;_ERROR_FAILED</code>, for 
359example <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>.
360</p></li>
361</ul></div>
362<p>
363</p>
364<p>
365Summary of rules for use of <span class="type">""</span>
366      </p>
367<div class="itemizedlist"><ul type="disc">
368<li><p>
369           Do not report programming errors via <a class="link" href="glib-Error-Reporting.html#GError" title="GError"><span class="type">GError</span></a>.
370	  </p></li>
371<li><p>
372          The last argument of a function that returns an error should be a
373          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
374          <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
375          argument before the "...".
376        </p></li>
377<li><p>
378          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
379          in details of the exact error that occurred.
380        </p></li>
381<li><p>
382           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 
383           not be returned to the caller, but your function should still 
384           abort and return if an error occurs. That is, control flow should
385           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>.
386	  </p></li>
387<li><p>
388          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  
389          <span class="emphasis"><em>had a fatal failure and did not complete whatever it was supposed
390            to do</em></span>. If the failure was not fatal, then you handled it
391          and you should not report it. If it was fatal, then you must report it 
392          and discontinue whatever you were doing immediately.
393        </p></li>
394<li><p>
395          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
396          a function that can report errors.
397	  </p></li>
398<li><p>
399          "Piling up" errors is always a bug. That is, if you assign a new
400          <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
401          error, it indicates that you should have aborted the operation instead
402          of continuing. If you were able to continue, you should have cleared
403          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
404          if you pile up errors.
405	  </p></li>
406<li><p>
407          By convention, if you return a boolean value indicating success 
408          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,
409          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. 
410        </p></li>
411<li><p>
412          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
413          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
414          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,
415          then users must check whether an error was returned to see if the
416          function succeeded.
417	  </p></li>
418<li><p>
419          When implementing a function that can report errors, you may want to
420          add a check at the top of your function that the error return location
421          is either <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
422          (e.g. <code class="literal">g_return_if_fail (error == NULL || *error ==
423          NULL);</code>).
424	  </p></li>
425</ul></div>
426<p>
427</p>
428</div>
429<div class="refsect1" lang="en">
430<a name="glib-Error-Reporting.details"></a><h2>Details</h2>
431<div class="refsect2" lang="en">
432<a name="GError"></a><h3>GError</h3>
433<pre class="programlisting">typedef struct {
434  GQuark       domain;
435  gint         code;
436  gchar       *message;
437} GError;
438</pre>
439<p>
440The <span class="structname">GError</span> structure contains 
441information about an error that has occurred.
442</p>
443<div class="variablelist"><table border="0">
444<col align="left" valign="top">
445<tbody>
446<tr>
447<td><p><span class="term"><a class="link" href="glib-Quarks.html#GQuark" title="GQuark">GQuark</a> <em class="structfield"><code>domain</code></em>;</span></p></td>
448<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>.
449</td>
450</tr>
451<tr>
452<td><p><span class="term"><a class="link" href="glib-Basic-Types.html#gint" title="gint">gint</a> <em class="structfield"><code>code</code></em>;</span></p></td>
453<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>.
454</td>
455</tr>
456<tr>
457<td><p><span class="term"><a class="link" href="glib-Basic-Types.html#gchar" title="gchar">gchar</a> *<em class="structfield"><code>message</code></em>;</span></p></td>
458<td>human-readable informative error message.
459
460</td>
461</tr>
462</tbody>
463</table></div>
464</div>
465<hr>
466<div class="refsect2" lang="en">
467<a name="g-error-new"></a><h3>g_error_new ()</h3>
468<pre class="programlisting"><a class="link" href="glib-Error-Reporting.html#GError" title="GError">GError</a>*             g_error_new                         (<a class="link" href="glib-Quarks.html#GQuark" title="GQuark">GQuark</a> domain,
469                                                         <a class="link" href="glib-Basic-Types.html#gint" title="gint">gint</a> code,
470                                                         const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar">gchar</a> *format,
471                                                         ...);</pre>
472<p>
473Creates 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>,
474and a message formatted with <em class="parameter"><code>format</code></em>.</p>
475<p>
476
477</p>
478<div class="variablelist"><table border="0">
479<col align="left" valign="top">
480<tbody>
481<tr>
482<td><p><span class="term"><em class="parameter"><code>domain</code></em> :</span></p></td>
483<td> error domain 
484</td>
485</tr>
486<tr>
487<td><p><span class="term"><em class="parameter"><code>code</code></em> :</span></p></td>
488<td> error code
489</td>
490</tr>
491<tr>
492<td><p><span class="term"><em class="parameter"><code>format</code></em> :</span></p></td>
493<td> <code class="function">printf()</code>-style format for error message
494</td>
495</tr>
496<tr>
497<td><p><span class="term"><em class="parameter"><code>...</code></em> :</span></p></td>
498<td> parameters for message format
499</td>
500</tr>
501<tr>
502<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
503<td> a new <a class="link" href="glib-Error-Reporting.html#GError" title="GError"><span class="type">GError</span></a>
504</td>
505</tr>
506</tbody>
507</table></div>
508</div>
509<hr>
510<div class="refsect2" lang="en">
511<a name="g-error-new-literal"></a><h3>g_error_new_literal ()</h3>
512<pre class="programlisting"><a class="link" href="glib-Error-Reporting.html#GError" title="GError">GError</a>*             g_error_new_literal                 (<a class="link" href="glib-Quarks.html#GQuark" title="GQuark">GQuark</a> domain,
513                                                         <a class="link" href="glib-Basic-Types.html#gint" title="gint">gint</a> code,
514                                                         const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar">gchar</a> *message);</pre>
515<p>
516Creates 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 not
517a <code class="function">printf()</code>-style format string. Use this 
518function if <em class="parameter"><code>message</code></em> contains text you don't have control over, 
519that could include <code class="function">printf()</code> escape sequences.</p>
520<p>
521
522</p>
523<div class="variablelist"><table border="0">
524<col align="left" valign="top">
525<tbody>
526<tr>
527<td><p><span class="term"><em class="parameter"><code>domain</code></em> :</span></p></td>
528<td> error domain
529</td>
530</tr>
531<tr>
532<td><p><span class="term"><em class="parameter"><code>code</code></em> :</span></p></td>
533<td> error code
534</td>
535</tr>
536<tr>
537<td><p><span class="term"><em class="parameter"><code>message</code></em> :</span></p></td>
538<td> error message
539</td>
540</tr>
541<tr>
542<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
543<td> a new <a class="link" href="glib-Error-Reporting.html#GError" title="GError"><span class="type">GError</span></a>
544</td>
545</tr>
546</tbody>
547</table></div>
548</div>
549<hr>
550<div class="refsect2" lang="en">
551<a name="g-error-free"></a><h3>g_error_free ()</h3>
552<pre class="programlisting">void                g_error_free                        (<a class="link" href="glib-Error-Reporting.html#GError" title="GError">GError</a> *error);</pre>
553<p>
554Frees a <a class="link" href="glib-Error-Reporting.html#GError" title="GError"><span class="type">GError</span></a> and associated resources.</p>
555<p>
556
557</p>
558<div class="variablelist"><table border="0">
559<col align="left" valign="top">
560<tbody><tr>
561<td><p><span class="term"><em class="parameter"><code>error</code></em> :</span></p></td>
562<td> a <a class="link" href="glib-Error-Reporting.html#GError" title="GError"><span class="type">GError</span></a>
563</td>
564</tr></tbody>
565</table></div>
566</div>
567<hr>
568<div class="refsect2" lang="en">
569<a name="g-error-copy"></a><h3>g_error_copy ()</h3>
570<pre class="programlisting"><a class="link" href="glib-Error-Reporting.html#GError" title="GError">GError</a>*             g_error_copy                        (const <a class="link" href="glib-Error-Reporting.html#GError" title="GError">GError</a> *error);</pre>
571<p>
572Makes a copy of <em class="parameter"><code>error</code></em>.</p>
573<p>
574
575</p>
576<div class="variablelist"><table border="0">
577<col align="left" valign="top">
578<tbody>
579<tr>
580<td><p><span class="term"><em class="parameter"><code>error</code></em> :</span></p></td>
581<td> a <a class="link" href="glib-Error-Reporting.html#GError" title="GError"><span class="type">GError</span></a>
582</td>
583</tr>
584<tr>
585<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
586<td> a new <a class="link" href="glib-Error-Reporting.html#GError" title="GError"><span class="type">GError</span></a>
587</td>
588</tr>
589</tbody>
590</table></div>
591</div>
592<hr>
593<div class="refsect2" lang="en">
594<a name="g-error-matches"></a><h3>g_error_matches ()</h3>
595<pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean">gboolean</a>            g_error_matches                     (const <a class="link" href="glib-Error-Reporting.html#GError" title="GError">GError</a> *error,
596                                                         <a class="link" href="glib-Quarks.html#GQuark" title="GQuark">GQuark</a> domain,
597                                                         <a class="link" href="glib-Basic-Types.html#gint" title="gint">gint</a> code);</pre>
598<p>
599Returns <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>
600otherwise.</p>
601<p>
602
603</p>
604<div class="variablelist"><table border="0">
605<col align="left" valign="top">
606<tbody>
607<tr>
608<td><p><span class="term"><em class="parameter"><code>error</code></em> :</span></p></td>
609<td> a <a class="link" href="glib-Error-Reporting.html#GError" title="GError"><span class="type">GError</span></a>
610</td>
611</tr>
612<tr>
613<td><p><span class="term"><em class="parameter"><code>domain</code></em> :</span></p></td>
614<td> an error domain
615</td>
616</tr>
617<tr>
618<td><p><span class="term"><em class="parameter"><code>code</code></em> :</span></p></td>
619<td> an error code
620</td>
621</tr>
622<tr>
623<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
624<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>
625</td>
626</tr>
627</tbody>
628</table></div>
629</div>
630<hr>
631<div class="refsect2" lang="en">
632<a name="g-set-error"></a><h3>g_set_error ()</h3>
633<pre class="programlisting">void                g_set_error                         (<a class="link" href="glib-Error-Reporting.html#GError" title="GError">GError</a> **err,
634                                                         <a class="link" href="glib-Quarks.html#GQuark" title="GQuark">GQuark</a> domain,
635                                                         <a class="link" href="glib-Basic-Types.html#gint" title="gint">gint</a> code,
636                                                         const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar">gchar</a> *format,
637                                                         ...);</pre>
638<p>
639Does 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> must
640be <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>.</p>
641<p>
642
643</p>
644<div class="variablelist"><table border="0">
645<col align="left" valign="top">
646<tbody>
647<tr>
648<td><p><span class="term"><em class="parameter"><code>err</code></em> :</span></p></td>
649<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>
650</td>
651</tr>
652<tr>
653<td><p><span class="term"><em class="parameter"><code>domain</code></em> :</span></p></td>
654<td> error domain
655</td>
656</tr>
657<tr>
658<td><p><span class="term"><em class="parameter"><code>code</code></em> :</span></p></td>
659<td> error code 
660</td>
661</tr>
662<tr>
663<td><p><span class="term"><em class="parameter"><code>format</code></em> :</span></p></td>
664<td> <code class="function">printf()</code>-style format
665</td>
666</tr>
667<tr>
668<td><p><span class="term"><em class="parameter"><code>...</code></em> :</span></p></td>
669<td> args for <em class="parameter"><code>format</code></em> 
670</td>
671</tr>
672</tbody>
673</table></div>
674</div>
675<hr>
676<div class="refsect2" lang="en">
677<a name="g-propagate-error"></a><h3>g_propagate_error ()</h3>
678<pre class="programlisting">void                g_propagate_error                   (<a class="link" href="glib-Error-Reporting.html#GError" title="GError">GError</a> **dest,
679                                                         <a class="link" href="glib-Error-Reporting.html#GError" title="GError">GError</a> *src);</pre>
680<p>
681If <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>.
682The 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>.</p>
683<p>
684
685</p>
686<div class="variablelist"><table border="0">
687<col align="left" valign="top">
688<tbody>
689<tr>
690<td><p><span class="term"><em class="parameter"><code>dest</code></em> :</span></p></td>
691<td> error return location
692</td>
693</tr>
694<tr>
695<td><p><span class="term"><em class="parameter"><code>src</code></em> :</span></p></td>
696<td> error to move into the return location
697</td>
698</tr>
699</tbody>
700</table></div>
701</div>
702<hr>
703<div class="refsect2" lang="en">
704<a name="g-clear-error"></a><h3>g_clear_error ()</h3>
705<pre class="programlisting">void                g_clear_error                       (<a class="link" href="glib-Error-Reporting.html#GError" title="GError">GError</a> **err);</pre>
706<p>
707If <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>,
708calls <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>.</p>
709<p>
710
711</p>
712<div class="variablelist"><table border="0">
713<col align="left" valign="top">
714<tbody><tr>
715<td><p><span class="term"><em class="parameter"><code>err</code></em> :</span></p></td>
716<td> a <a class="link" href="glib-Error-Reporting.html#GError" title="GError"><span class="type">GError</span></a> return location
717</td>
718</tr></tbody>
719</table></div>
720</div>
721<hr>
722<div class="refsect2" lang="en">
723<a name="g-prefix-error"></a><h3>g_prefix_error ()</h3>
724<pre class="programlisting">void                g_prefix_error                      (<a class="link" href="glib-Error-Reporting.html#GError" title="GError">GError</a> **err,
725                                                         const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar">gchar</a> *format,
726                                                         ...);</pre>
727<p>
728Formats a string according to <em class="parameter"><code>format</code></em> and
729prefix it to an existing error message.  If
730<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
731nothing.
732</p>
733<p>
734If *<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
735present but there is no error condition) then
736also do nothing.  Whether or not it makes
737sense to take advantage of this feature is up
738to you.</p>
739<p>
740
741</p>
742<div class="variablelist"><table border="0">
743<col align="left" valign="top">
744<tbody>
745<tr>
746<td><p><span class="term"><em class="parameter"><code>err</code></em> :</span></p></td>
747<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>
748</td>
749</tr>
750<tr>
751<td><p><span class="term"><em class="parameter"><code>format</code></em> :</span></p></td>
752<td> <code class="function">printf()</code>-style format string
753</td>
754</tr>
755<tr>
756<td><p><span class="term"><em class="parameter"><code>...</code></em> :</span></p></td>
757<td> arguments to <em class="parameter"><code>format</code></em>
758</td>
759</tr>
760</tbody>
761</table></div>
762<p class="since">Since  2.16
763</p>
764</div>
765<hr>
766<div class="refsect2" lang="en">
767<a name="g-propagate-prefixed-error"></a><h3>g_propagate_prefixed_error ()</h3>
768<pre class="programlisting">void                g_propagate_prefixed_error          (<a class="link" href="glib-Error-Reporting.html#GError" title="GError">GError</a> **dest,
769                                                         <a class="link" href="glib-Error-Reporting.html#GError" title="GError">GError</a> *src,
770                                                         const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar">gchar</a> *format,
771                                                         ...);</pre>
772<p>
773If <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,
774moves <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>.
775After the move, add a prefix as with 
776<a class="link" href="glib-Error-Reporting.html#g-prefix-error" title="g_prefix_error ()"><code class="function">g_prefix_error()</code></a>.</p>
777<p>
778
779</p>
780<div class="variablelist"><table border="0">
781<col align="left" valign="top">
782<tbody>
783<tr>
784<td><p><span class="term"><em class="parameter"><code>dest</code></em> :</span></p></td>
785<td> error return location
786</td>
787</tr>
788<tr>
789<td><p><span class="term"><em class="parameter"><code>src</code></em> :</span></p></td>
790<td> error to move into the return location
791</td>
792</tr>
793<tr>
794<td><p><span class="term"><em class="parameter"><code>format</code></em> :</span></p></td>
795<td> <code class="function">printf()</code>-style format string
796</td>
797</tr>
798<tr>
799<td><p><span class="term"><em class="parameter"><code>...</code></em> :</span></p></td>
800<td> arguments to <em class="parameter"><code>format</code></em>
801</td>
802</tr>
803</tbody>
804</table></div>
805<p class="since">Since  2.16
806</p>
807</div>
808</div>
809</div>
810<div class="footer">
811<hr>
812          Generated by GTK-Doc V1.10</div>
813</body>
814</html>