📄 glib-error-reporting.html
字号:
<html xmlns:cf="http://docbook.sourceforge.net/xmlns/chunkfast/1.0"><head><meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"><title>Error Reporting</title><meta name="generator" content="DocBook XSL Stylesheets V1.69.0"><link rel="start" href="index.html" title="GLib Reference Manual"><link rel="up" href="glib-core.html" title="GLib Core Application Support"><link rel="prev" href="glib-IO-Channels.html" title="IO Channels"><link rel="next" href="glib-Warnings-and-Assertions.html" title="Message Output and Debugging Functions"><meta name="generator" content="GTK-Doc V1.4 (XML mode)"><link rel="stylesheet" href="style.css" type="text/css"><link rel="chapter" href="glib.html" title="GLib Overview"><link rel="chapter" href="glib-fundamentals.html" title="GLib Fundamentals"><link rel="chapter" href="glib-core.html" title="GLib Core Application Support"><link rel="chapter" href="glib-utilities.html" title="GLib Utilities"><link rel="chapter" href="glib-data-types.html" title="GLib Data Types"><link rel="chapter" href="tools.html" title="GLib Tools"><link rel="index" href="ix01.html" title="Index"><link rel="index" href="ix02.html" title="Index of deprecated symbols"><link rel="index" href="ix03.html" title="Index of new symbols in 2.2"><link rel="index" href="ix04.html" title="Index of new symbols in 2.4"><link rel="index" href="ix05.html" title="Index of new symbols in 2.6"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table class="navigation" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2"><tr valign="middle"><td><a accesskey="p" href="glib-IO-Channels.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td><td><a accesskey="u" href="glib-core.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td><td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td><th width="100%" align="center">GLib Reference Manual</th><td><a accesskey="n" href="glib-Warnings-and-Assertions.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td></tr></table><div class="refentry" lang="en"><a name="glib-Error-Reporting"></a><div class="titlepage"></div><div class="refnamediv"><table width="100%"><tr><td valign="top"><h2><span class="refentrytitle">Error Reporting</span></h2><p>Error Reporting — a system for reporting errors.</p></td><td valign="top" align="right"></td></tr></table></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">#include <glib.h> <a href="glib-Error-Reporting.html#GError">GError</a>;<a href="glib-Error-Reporting.html#GError">GError</a>* <a href="glib-Error-Reporting.html#g-error-new">g_error_new</a> (<a href="glib-Quarks.html#GQuark">GQuark</a> domain, <a href="glib-Basic-Types.html#gint">gint</a> code, const <a href="glib-Basic-Types.html#gchar">gchar</a> *format, ...);<a href="glib-Error-Reporting.html#GError">GError</a>* <a href="glib-Error-Reporting.html#g-error-new-literal">g_error_new_literal</a> (<a href="glib-Quarks.html#GQuark">GQuark</a> domain, <a href="glib-Basic-Types.html#gint">gint</a> code, const <a href="glib-Basic-Types.html#gchar">gchar</a> *message);void <a href="glib-Error-Reporting.html#g-error-free">g_error_free</a> (<a href="glib-Error-Reporting.html#GError">GError</a> *error);<a href="glib-Error-Reporting.html#GError">GError</a>* <a href="glib-Error-Reporting.html#g-error-copy">g_error_copy</a> (const <a href="glib-Error-Reporting.html#GError">GError</a> *error);<a href="glib-Basic-Types.html#gboolean">gboolean</a> <a href="glib-Error-Reporting.html#g-error-matches">g_error_matches</a> (const <a href="glib-Error-Reporting.html#GError">GError</a> *error, <a href="glib-Quarks.html#GQuark">GQuark</a> domain, <a href="glib-Basic-Types.html#gint">gint</a> code);void <a href="glib-Error-Reporting.html#g-set-error">g_set_error</a> (<a href="glib-Error-Reporting.html#GError">GError</a> **err, <a href="glib-Quarks.html#GQuark">GQuark</a> domain, <a href="glib-Basic-Types.html#gint">gint</a> code, const <a href="glib-Basic-Types.html#gchar">gchar</a> *format, ...);void <a href="glib-Error-Reporting.html#g-propagate-error">g_propagate_error</a> (<a href="glib-Error-Reporting.html#GError">GError</a> **dest, <a href="glib-Error-Reporting.html#GError">GError</a> *src);void <a href="glib-Error-Reporting.html#g-clear-error">g_clear_error</a> (<a href="glib-Error-Reporting.html#GError">GError</a> **err);</pre></div><div class="refsect1" lang="en"><a name="id2924366"></a><h2>Description</h2><p>GLib provides a standard method of reporting errors from a called function tothe calling code. (This is the same problem solved by exceptions in otherlanguages.) It's important to understand that this method is both a<span class="emphasis"><em>data type</em></span> (the <a href="glib-Error-Reporting.html#GError"><span class="type">GError</span></a> object) and a <span class="emphasis"><em>set ofrules.</em></span> If you use <a href="glib-Error-Reporting.html#GError"><span class="type">GError</span></a> incorrectly, then your code will notproperly interoperate with other code that uses <a href="glib-Error-Reporting.html#GError"><span class="type">GError</span></a>, and users of your APIwill probably get confused.</p><p>First and foremost: <span class="emphasis"><em><a href="glib-Error-Reporting.html#GError"><span class="type">GError</span></a> should only be used to reportrecoverable runtime errors, never to report programming errors.</em></span> Ifthe programmer has screwed up, then you should use <a href="glib-Message-Logging.html#g-warning"><code class="function">g_warning()</code></a>,<a href="glib-Warnings-and-Assertions.html#g-return-if-fail"><code class="function">g_return_if_fail()</code></a>, <a href="glib-Warnings-and-Assertions.html#g-assert"><code class="function">g_assert()</code></a>, <a href="glib-Message-Logging.html#g-error"><code class="function">g_error()</code></a>, or some similar facility.(Incidentally, remember that the <a href="glib-Message-Logging.html#g-error"><code class="function">g_error()</code></a> function should<span class="emphasis"><em>only</em></span> be used for programming errors, it should not be usedto print any error reportable via <a href="glib-Error-Reporting.html#GError"><span class="type">GError</span></a>.)</p><p>Examples of recoverable runtime errors are "file not found" or "failed to parseinput." Examples of programming errors are "NULL passed to <code class="function">strcmp()</code>" or"attempted to free the same pointer twice." These two kinds of errors arefundamentally different: runtime errors should be handled or reported to theuser, programming errors should be eliminated by fixing the bug in the program.This is why most functions in GLib and GTK+ do not use the <a href="glib-Error-Reporting.html#GError"><span class="type">GError</span></a> facility.</p><p>Functions that can fail take a return location for a <a href="glib-Error-Reporting.html#GError"><span class="type">GError</span></a> as their last argument. For example:</p><div class="informalexample"><pre class="programlisting">gboolean g_file_get_contents (const gchar *filename, gchar **contents, gsize *length, GError **error);</pre></div><p>If you pass a non-<code class="literal">NULL</code> value for the <code class="literal">error</code> argument, it should point to a location where an error can be placed. For example:</p><div class="informalexample"><pre class="programlisting">gchar *contents;GError *err = NULL;g_file_get_contents ("foo.txt", &contents, NULL, &err);g_assert ((contents == NULL && err != NULL) || (contents != NULL && err == NULL));if (err != NULL) { /* Report error to user, and free error */ g_assert (contents == NULL); fprintf (stderr, "Unable to read file: %s\n", err->message); g_error_free (err); } else { /* Use file contents */ g_assert (contents != NULL); }</pre></div><p>Note that <code class="literal">err != NULL</code> in this example is a<span class="emphasis"><em>reliable</em></span> indicator of whether<a href="glib-File-Utilities.html#g-file-get-contents"><code class="function">g_file_get_contents()</code></a> failed. Additionally, <a href="glib-File-Utilities.html#g-file-get-contents"><code class="function">g_file_get_contents()</code></a> returnsa boolean which indicates whether it was successful.</p><p>Because <a href="glib-File-Utilities.html#g-file-get-contents"><code class="function">g_file_get_contents()</code></a> returns <code class="literal">FALSE</code> on failure, if you are onlyinterested in whether it failed and don't need to display an error message, youcan pass <code class="literal">NULL</code> for the <code class="literal">error</code> argument:</p><div class="informalexample"><pre class="programlisting">if (g_file_get_contents ("foo.txt", &contents, NULL, NULL)) /* ignore errors */ /* no error occurred */ ;else /* error */ ;</pre></div><p></p><p>The <a href="glib-Error-Reporting.html#GError"><span class="type">GError</span></a> object contains three fields: <code class="literal">domain</code> indicatesthe module the error-reporting function is located in, <code class="literal">code</code>indicates the specific error that occurred, and <code class="literal">message</code> is auser-readable error message with as many details as possible. Several functionsare provided to deal with an error received from a called function:<a href="glib-Error-Reporting.html#g-error-matches"><code class="function">g_error_matches()</code></a> returns <code class="literal">TRUE</code> if the error matches a given domain and code,<a href="glib-Error-Reporting.html#g-propagate-error"><code class="function">g_propagate_error()</code></a> copies an error into an error location (so the callingfunction will receive it), and <a href="glib-Error-Reporting.html#g-clear-error"><code class="function">g_clear_error()</code></a> clears an error location byfreeing the error and resetting the location to <code class="literal">NULL</code>. To display an error to theuser, simply display <code class="literal">error->message</code>, perhaps along withadditional context known only to the calling function (the file being opened, orwhatever -- though in the <a href="glib-File-Utilities.html#g-file-get-contents"><code class="function">g_file_get_contents()</code></a> case,<code class="literal">error->message</code> already contains a filename).</p><p>When implementing a function that can report errors, the basic tool is<a href="glib-Error-Reporting.html#g-set-error"><code class="function">g_set_error()</code></a>. Typically, if a fatal error occurs you want to <a href="glib-Error-Reporting.html#g-set-error"><code class="function">g_set_error()</code></a>,then return immediately. <a href="glib-Error-Reporting.html#g-set-error"><code class="function">g_set_error()</code></a> does nothing if the error location passedto it is <code class="literal">NULL</code>. Here's an example:</p><div class="informalexample"><pre class="programlisting">gintfoo_open_file (GError **error){ gint fd; fd = open ("file.txt", O_RDONLY); if (fd < 0) { g_set_error (error, FOO_ERROR, /* error domain */ FOO_ERROR_BLAH, /* error code */ "Failed to open file: %s", /* error message format string */ g_strerror (errno)); return -1; } else return fd;}</pre></div><p></p><p>Things are somewhat more complicated if you yourself call another function thatcan report a <a href="glib-Error-Reporting.html#GError"><span class="type">GError</span></a>. If the sub-function indicates fatal errors in some wayother than reporting a <a href="glib-Error-Reporting.html#GError"><span class="type">GError</span></a>, such as by returning <code class="literal">TRUE</code> on success, you cansimply do the following:</p><div class="informalexample"><pre class="programlisting">gbooleanmy_function_that_can_fail (GError **err){ g_return_val_if_fail (err == NULL || *err == NULL, FALSE); if (!sub_function_that_can_fail (err)) { /* assert that error was set by the sub-function */ g_assert (err == NULL || *err != NULL); return FALSE; } /* otherwise continue, no error occurred */ g_assert (err == NULL || *err == NULL);}</pre></div><p></p><p>If the sub-function does not indicate errors other than by reporting a <a href="glib-Error-Reporting.html#GError"><span class="type">GError</span></a>, you need to create a temporary <a href="glib-Error-Reporting.html#GError"><span class="type">GError</span></a> since the passed-in one may be <code class="literal">NULL</code>.<a href="glib-Error-Reporting.html#g-propagate-error"><code class="function">g_propagate_error()</code></a> is intended for use in this case.</p><div class="informalexample"><pre class="programlisting">gbooleanmy_function_that_can_fail (GError **err){ GError *tmp_error; g_return_val_if_fail (err == NULL || *err == NULL, FALSE); tmp_error = NULL; sub_function_that_can_fail (&tmp_error); if (tmp_error != NULL) { /* store tmp_error in err, if err != NULL, * otherwise call g_error_free() on tmp_error */ g_propagate_error (err, tmp_error); return FALSE; } /* otherwise continue, no error occurred */}⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -