* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
- * License along with this library; if not, write to the
- * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
- * Boston, MA 02111-1307, USA.
+ * License along with this library; if not, see <http://www.gnu.org/licenses/>.
*/
/*
* GLib provides a standard method of reporting errors from a called
* function to the calling code. (This is the same problem solved by
* exceptions in other languages.) It's important to understand that
- * this method is both a <emphasis>data type</emphasis> (the #GError
- * object) and a <emphasis>set of rules.</emphasis> If you use #GError
- * incorrectly, then your code will not properly interoperate with other
- * code that uses #GError, and users of your API will probably get confused.
- *
- * First and foremost: <emphasis>#GError should only be used to report
- * recoverable runtime errors, never to report programming
- * errors.</emphasis> If the programmer has screwed up, then you should
- * use g_warning(), g_return_if_fail(), g_assert(), g_error(), or some
- * similar facility. (Incidentally, remember that the g_error() function
- * should <emphasis>only</emphasis> be used for programming errors, it
- * should not be used to print any error reportable via #GError.)
+ * this method is both a data type (the #GError struct) and a set of
+ * rules. If you use #GError incorrectly, then your code will not
+ * properly interoperate with other code that uses #GError, and users
+ * of your API will probably get confused.
+ *
+ * First and foremost: #GError should only be used to report recoverable
+ * runtime errors, never to report programming errors. If the programmer
+ * has screwed up, then you should use g_warning(), g_return_if_fail(),
+ * g_assert(), g_error(), or some similar facility. (Incidentally,
+ * remember that the g_error() function should only be used for
+ * programming errors, it should not be used to print any error
+ * reportable via #GError.)
*
* Examples of recoverable runtime errors are "file not found" or
* "failed to parse input." Examples of programming errors are "NULL
*
* Functions that can fail take a return location for a #GError as their
* last argument. For example:
- * |[
+ * |[<!-- language="C" -->
* gboolean g_file_get_contents (const gchar *filename,
* gchar **contents,
* gsize *length,
* GError **error);
* ]|
- * If you pass a non-%NULL value for the <literal>error</literal>
- * argument, it should point to a location where an error can be placed.
- * For example:
- * |[
+ * If you pass a non-%NULL value for the `error` argument, it should
+ * point to a location where an error can be placed. For example:
+ * |[<!-- language="C" -->
* gchar *contents;
* GError *err = NULL;
- * g_file_get_contents ("foo.txt", &contents, NULL, &err);
- * g_assert ((contents == NULL && err != NULL) || (contents != NULL && 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 */
+ * // Report error to user, and free error
* g_assert (contents == NULL);
- * fprintf (stderr, "Unable to read file: %s\n", err->message);
+ * fprintf (stderr, "Unable to read file: %s\n", err->message);
* g_error_free (err);
* }
* else
* {
- * /* Use file contents */
+ * // Use file contents
* g_assert (contents != NULL);
* }
* ]|
- * Note that <literal>err != NULL</literal> in this example is a
- * <emphasis>reliable</emphasis> indicator of whether
- * g_file_get_contents() failed. Additionally, g_file_get_contents()
- * returns a boolean which indicates whether it was successful.
+ * Note that `err != NULL` in this example is a reliable indicator
+ * of whether g_file_get_contents() failed. Additionally,
+ * g_file_get_contents() returns a boolean which
+ * indicates whether it was successful.
*
* Because g_file_get_contents() returns %FALSE on failure, if you
* are only interested in whether it failed and don't need to display
- * an error message, you can pass %NULL for the <literal>error</literal>
- * argument:
- * |[
- * if (g_file_get_contents ("foo.txt", &contents, NULL, NULL)) /* ignore errors */
- * /* no error occurred */ ;
+ * an error message, you can pass %NULL for the @error argument:
+ * |[<!-- language="C" -->
+ * if (g_file_get_contents ("foo.txt", &contents, NULL, NULL)) // ignore errors
+ * // no error occurred
+ * ;
* else
- * /* error */ ;
+ * // error
+ * ;
* ]|
*
- * The #GError object contains three fields: <literal>domain</literal>
- * indicates the module the error-reporting function is located in,
- * <literal>code</literal> indicates the specific error that occurred,
- * and <literal>message</literal> is a user-readable error message with
+ * The #GError object contains three fields: @domain indicates the module
+ * the error-reporting function is located in, @code indicates the specific
+ * error that occurred, and @message is a user-readable error message with
* as many details as possible. Several functions are provided to deal
* with an error received from a called function: g_error_matches()
* returns %TRUE if the error matches a given domain and code,
* g_propagate_error() copies an error into an error location (so the
* calling function will receive it), and g_clear_error() clears an
* error location by freeing the error and resetting the location to
- * %NULL. To display an error to the user, simply display
- * <literal>error->message</literal>, perhaps along with additional
- * context known only to the calling function (the file being opened,
- * or whatever -- though in the g_file_get_contents() case,
- * <literal>error->message</literal> already contains a filename).
+ * %NULL. To display an error to the user, simply display the @message,
+ * perhaps along with additional context known only to the calling
+ * function (the file being opened, or whatever - though in the
+ * g_file_get_contents() case, the @message already contains a filename).
*
* When implementing a function that can report errors, the basic
* tool is g_set_error(). Typically, if a fatal error occurs you
* want to g_set_error(), then return immediately. g_set_error()
* does nothing if the error location passed to it is %NULL.
* Here's an example:
- * |[
+ * |[<!-- language="C" -->
* gint
* foo_open_file (GError **error)
* {
*
* fd = open ("file.txt", O_RDONLY);
*
- * if (fd < 0)
+ * 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 */
+ * FOO_ERROR, // error domain
+ * FOO_ERROR_BLAH, // error code
+ * "Failed to open file: %s", // error message format string
* g_strerror (errno));
* return -1;
* }
* function that can report a #GError. If the sub-function indicates
* fatal errors in some way other than reporting a #GError, such as
* by returning %TRUE on success, you can simply do the following:
- * |[
+ * |[<!-- language="C" -->
* gboolean
* my_function_that_can_fail (GError **err)
* {
*
* if (!sub_function_that_can_fail (err))
* {
- * /* assert that error was set by the sub-function */
+ * // assert that error was set by the sub-function
* g_assert (err == NULL || *err != NULL);
* return FALSE;
* }
*
- * /* otherwise continue, no error occurred */
+ * // otherwise continue, no error occurred
* g_assert (err == NULL || *err == NULL);
* }
* ]|
* reporting a #GError, you need to create a temporary #GError
* since the passed-in one may be %NULL. g_propagate_error() is
* intended for use in this case.
- * |[
+ * |[<!-- language="C" -->
* gboolean
* my_function_that_can_fail (GError **err)
* {
* g_return_val_if_fail (err == NULL || *err == NULL, FALSE);
*
* tmp_error = NULL;
- * sub_function_that_can_fail (&tmp_error);
+ * 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
- * */
+ * // 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 */
+ * // otherwise continue, no error occurred
* }
* ]|
*
* Error pileups are always a bug. For example, this code is incorrect:
- * |[
+ * |[<!-- language="C" -->
* gboolean
* my_function_that_can_fail (GError **err)
* {
* g_return_val_if_fail (err == NULL || *err == NULL, FALSE);
*
* tmp_error = NULL;
- * sub_function_that_can_fail (&tmp_error);
- * other_function_that_can_fail (&tmp_error);
+ * sub_function_that_can_fail (&tmp_error);
+ * other_function_that_can_fail (&tmp_error);
*
* if (tmp_error != NULL)
* {
* }
* }
* ]|
- * <literal>tmp_error</literal> should be checked immediately after
- * sub_function_that_can_fail(), and either cleared or propagated
- * upward. The rule is: <emphasis>after each error, you must either
- * handle the error, or return it to the calling function</emphasis>.
+ * @tmp_error should be checked immediately after sub_function_that_can_fail(),
+ * and either cleared or propagated upward. The rule is: after each error,
+ * you must either handle the error, or return it to the calling function.
+ *
* Note that passing %NULL for the error location is the equivalent
* of handling an error by always doing nothing about it. So the
* following code is fine, assuming errors in sub_function_that_can_fail()
* are not fatal to my_function_that_can_fail():
- * |[
+ * |[<!-- language="C" -->
* gboolean
* my_function_that_can_fail (GError **err)
* {
*
* g_return_val_if_fail (err == NULL || *err == NULL, FALSE);
*
- * sub_function_that_can_fail (NULL); /* ignore errors */
+ * sub_function_that_can_fail (NULL); // ignore errors
*
* tmp_error = NULL;
- * other_function_that_can_fail (&tmp_error);
+ * other_function_that_can_fail (&tmp_error);
*
* if (tmp_error != NULL)
* {
* }
* ]|
*
- * Note that passing %NULL for the error location
- * <emphasis>ignores</emphasis> errors; it's equivalent to
- * <literal>try { sub_function_that_can_fail (); } catch (...) {}</literal>
- * in C++. It does <emphasis>not</emphasis> mean to leave errors
- * unhandled; it means to handle them by doing nothing.
+ * Note that passing %NULL for the error location ignores errors;
+ * it's equivalent to
+ * `try { sub_function_that_can_fail (); } catch (...) {}`
+ * in C++. It does not mean to leave errors unhandled; it means
+ * to handle them by doing nothing.
*
* Error domains and codes are conventionally named as follows:
- * <itemizedlist>
- * <listitem><para>
- * The error domain is called
- * <literal><NAMESPACE>_<MODULE>_ERROR</literal>,
+ *
+ * - The error domain is called <NAMESPACE>_<MODULE>_ERROR,
* for example %G_SPAWN_ERROR or %G_THREAD_ERROR:
- * |[
- * #define G_SPAWN_ERROR g_spawn_error_quark ()
+ * |[<!-- language="C" -->
+ * #define G_SPAWN_ERROR g_spawn_error_quark ()
*
- * GQuark
- * g_spawn_error_quark (void)
- * {
- * return g_quark_from_static_string ("g-spawn-error-quark");
- * }
+ * GQuark
+ * g_spawn_error_quark (void)
+ * {
+ * return g_quark_from_static_string ("g-spawn-error-quark");
+ * }
* ]|
- * </para></listitem>
- * <listitem><para>
- * The quark function for the error domain is called
- * <literal><namespace>_<module>_error_quark</literal>,
- * for example g_spawn_error_quark() or %g_thread_error_quark().
- * </para></listitem>
- * <listitem><para>
- * The error codes are in an enumeration called
- * <literal><Namespace><Module>Error</literal>;
- * for example,#GThreadError or #GSpawnError.
- * </para></listitem>
- * <listitem><para>
- * Members of the error code enumeration are called
- * <literal><NAMESPACE>_<MODULE>_ERROR_<CODE></literal>,
+ *
+ * - The quark function for the error domain is called
+ * <namespace>_<module>_error_quark,
+ * for example g_spawn_error_quark() or g_thread_error_quark().
+ *
+ * - The error codes are in an enumeration called
+ * <Namespace><Module>Error;
+ * for example, #GThreadError or #GSpawnError.
+ *
+ * - Members of the error code enumeration are called
+ * <NAMESPACE>_<MODULE>_ERROR_<CODE>,
* for example %G_SPAWN_ERROR_FORK or %G_THREAD_ERROR_AGAIN.
- * </para></listitem>
- * <listitem><para>
- * If there's a "generic" or "unknown" error code for unrecoverable
+ *
+ * - If there's a "generic" or "unknown" error code for unrecoverable
* errors it doesn't make sense to distinguish with specific codes,
- * it should be called <literal><NAMESPACE>_<MODULE>_ERROR_FAILED</literal>,
- * for example %G_SPAWN_ERROR_FAILED.
- * </para></listitem>
- * </itemizedlist>
+ * it should be called <NAMESPACE>_<MODULE>_ERROR_FAILED,
+ * for example %G_SPAWN_ERROR_FAILED. In the case of error code
+ * enumerations that may be extended in future releases, you should
+ * generally not handle this error code explicitly, but should
+ * instead treat any unrecognized error code as equivalent to
+ * FAILED.
*
* Summary of rules for use of #GError:
- * <itemizedlist>
- * <listitem><para>
- * Do not report programming errors via #GError.
- * </para></listitem>
- * <listitem><para>
- * The last argument of a function that returns an error should
+ *
+ * - Do not report programming errors via #GError.
+ *
+ * - The last argument of a function that returns an error should
* be a location where a #GError can be placed (i.e. "#GError** error").
* If #GError is used with varargs, the #GError** should be the last
* argument before the "...".
- * </para></listitem>
- * <listitem><para>
- * The caller may pass %NULL for the #GError** if they are not interested
+ *
+ * - The caller may pass %NULL for the #GError** if they are not interested
* in details of the exact error that occurred.
- * </para></listitem>
- * <listitem><para>
- * If %NULL is passed for the #GError** argument, then errors should
+ *
+ * - If %NULL is passed for the #GError** argument, then errors should
* not be returned to the caller, but your function should still
* abort and return if an error occurs. That is, control flow should
* not be affected by whether the caller wants to get a #GError.
- * </para></listitem>
- * <listitem><para>
- * If a #GError is reported, then your function by definition
- * <emphasis>had a fatal failure and did not complete whatever
- * it was supposed to do</emphasis>. If the failure was not fatal,
- * then you handled it and you should not report it. If it was fatal,
- * then you must report it and discontinue whatever you were doing
- * immediately.
- * </para></listitem>
- * <listitem><para>
- * A #GError* must be initialized to %NULL before passing its address
+ *
+ * - If a #GError is reported, then your function by definition had a
+ * fatal failure and did not complete whatever it was supposed to do.
+ * If the failure was not fatal, then you handled it and you should not
+ * report it. If it was fatal, then you must report it and discontinue
+ * whatever you were doing immediately.
+ *
+ * - If a #GError is reported, out parameters are not guaranteed to
+ * be set to any defined value.
+ *
+ * - A #GError* must be initialized to %NULL before passing its address
* to a function that can report errors.
- * </para></listitem>
- * <listitem><para>
- * "Piling up" errors is always a bug. That is, if you assign a
+ *
+ * - "Piling up" errors is always a bug. That is, if you assign a
* new #GError to a #GError* that is non-%NULL, thus overwriting
* the previous error, it indicates that you should have aborted
* the operation instead of continuing. If you were able to continue,
* you should have cleared the previous error with g_clear_error().
* g_set_error() will complain if you pile up errors.
- * </para></listitem>
- * <listitem><para>
- * By convention, if you return a boolean value indicating success
- * then %TRUE means success and %FALSE means failure. If %FALSE is
- * returned, the error <emphasis>must</emphasis> be set to a non-%NULL
- * value.
- * </para></listitem>
- * <listitem><para>
- * A %NULL return value is also frequently used to mean that an error
+ *
+ * - By convention, if you return a boolean value indicating success
+ * then %TRUE means success and %FALSE means failure.
+ * <footnote><para>Avoid creating functions which have a boolean
+ * return value and a GError parameter, but where the boolean does
+ * something other than signal whether the GError is set. Among other
+ * problems, it requires C callers to allocate a temporary error. Instead,
+ * provide a "gboolean *" out parameter. There are functions in GLib
+ * itself such as g_key_file_has_key() that are deprecated because of this.
+ * </para></footnote>
+ * If %FALSE is
+ * returned, the error must be set to a non-%NULL value.
+ * <footnote><para>One exception to this is that in situations that are
+ * already considered to be undefined behaviour (such as when a
+ * g_return_val_if_fail() check fails), the error need not be set.
+ * Instead of checking separately whether the error is set, callers
+ * should ensure that they do not provoke undefined behaviour, then
+ * assume that the error will be set on failure.</para></footnote>
+ *
+ * - A %NULL return value is also frequently used to mean that an error
* occurred. You should make clear in your documentation whether %NULL
* is a valid return value in non-error cases; if %NULL is a valid value,
* then users must check whether an error was returned to see if the
* function succeeded.
- * </para></listitem>
- * <listitem><para>
- * When implementing a function that can report errors, you may want
+ *
+ * - When implementing a function that can report errors, you may want
* to add a check at the top of your function that the error return
* location is either %NULL or contains a %NULL error (e.g.
- * <literal>g_return_if_fail (error == NULL || *error == NULL);</literal>).
- * </para></listitem>
- * </itemizedlist>
+ * `g_return_if_fail (error == NULL || *error == NULL);`).
*/
#include "config.h"
{
GError *error;
+ /* Historically, GError allowed this (although it was never meant to work),
+ * and it has significant use in the wild, which g_return_val_if_fail
+ * would break. It should maybe g_return_val_if_fail in GLib 4.
+ * (GNOME#660371, GNOME#560482)
+ */
+ g_warn_if_fail (domain != 0);
+ g_warn_if_fail (format != NULL);
+
error = g_slice_new (GError);
error->domain = domain;
* Creates a new #GError with the given @domain and @code,
* and a message formatted with @format.
*
- * Return value: a new #GError
+ * Returns: a new #GError
*/
GError*
g_error_new (GQuark domain,
* @message contains text you don't have control over,
* that could include printf() escape sequences.
*
- * Return value: a new #GError
+ * Returns: a new #GError
**/
GError*
g_error_new_literal (GQuark domain,
*
* Makes a copy of @error.
*
- * Return value: a new #GError
+ * Returns: a new #GError
*/
GError*
g_error_copy (const GError *error)
GError *copy;
g_return_val_if_fail (error != NULL, NULL);
+ /* See g_error_new_valist for why these don't return */
+ g_warn_if_fail (error->domain != 0);
+ g_warn_if_fail (error->message != NULL);
copy = g_slice_new (GError);
/**
* g_error_matches:
- * @error: a #GError or %NULL
+ * @error: (allow-none): a #GError or %NULL
* @domain: an error domain
* @code: an error code
*
* otherwise. In particular, when @error is %NULL, %FALSE will
* be returned.
*
- * Return value: whether @error has @domain and @code
+ * If @domain contains a `FAILED` (or otherwise generic) error code,
+ * you should generally not check for it explicitly, but should
+ * instead treat any not-explicitly-recognized error code as being
+ * equilalent to the `FAILED` code. This way, if the domain is
+ * extended in the future to provide a more specific error code for
+ * a certain case, your code will still work.
+ *
+ * Returns: whether @error has @domain and @code
*/
gboolean
g_error_matches (const GError *error,
/**
* g_set_error:
- * @err: a return location for a #GError, or %NULL
+ * @err: (allow-none): a return location for a #GError, or %NULL
* @domain: error domain
* @code: error code
* @format: printf()-style format
if (*err == NULL)
*err = new;
else
- g_warning (ERROR_OVERWRITTEN_WARNING, new->message);
+ {
+ g_warning (ERROR_OVERWRITTEN_WARNING, new->message);
+ g_error_free (new);
+ }
}
/**
* g_set_error_literal:
- * @err: a return location for a #GError, or %NULL
+ * @err: (allow-none): a return location for a #GError, or %NULL
* @domain: error domain
* @code: error code
* @message: error message
gint code,
const gchar *message)
{
- GError *new;
-
if (err == NULL)
return;
- new = g_error_new_literal (domain, code, message);
if (*err == NULL)
- *err = new;
+ *err = g_error_new_literal (domain, code, message);
else
- g_warning (ERROR_OVERWRITTEN_WARNING, new->message);
+ g_warning (ERROR_OVERWRITTEN_WARNING, message);
}
/**
*
* If @dest is %NULL, free @src; otherwise, moves @src into *@dest.
* The error variable @dest points to must be %NULL.
+ *
+ * Note that @src is no longer valid after this call. If you want
+ * to keep using the same GError*, you need to set it to %NULL
+ * after calling this function on it.
*/
void
g_propagate_error (GError **dest,
else
{
if (*dest != NULL)
- g_warning (ERROR_OVERWRITTEN_WARNING, src->message);
+ {
+ g_warning (ERROR_OVERWRITTEN_WARNING, src->message);
+ g_error_free (src);
+ }
else
*dest = src;
}
}
}
+G_GNUC_PRINTF(2, 0)
static void
g_error_add_prefix (gchar **string,
const gchar *format,
/**
* g_prefix_error:
- * @err: a return location for a #GError, or %NULL
+ * @err: (allow-none): a return location for a #GError, or %NULL
* @format: printf()-style format string
* @...: arguments to @format
*
- * Formats a string according to @format and
- * prefix it to an existing error message. If
- * @err is %NULL (ie: no error variable) then do
+ * Formats a string according to @format and prefix it to an existing
+ * error message. If @err is %NULL (ie: no error variable) then do
* nothing.
*
- * If *@err is %NULL (ie: an error variable is
- * present but there is no error condition) then
- * also do nothing. Whether or not it makes
- * sense to take advantage of this feature is up
- * to you.
+ * If *@err is %NULL (ie: an error variable is present but there is no
+ * error condition) then also do nothing. Whether or not it makes sense
+ * to take advantage of this feature is up to you.
*
* Since: 2.16
*/
* @format: printf()-style format string
* @...: arguments to @format
*
- * If @dest is %NULL, free @src; otherwise,
- * moves @src into *@dest. *@dest must be %NULL.
- * After the move, add a prefix as with
+ * If @dest is %NULL, free @src; otherwise, moves @src into *@dest.
+ * *@dest must be %NULL. After the move, add a prefix as with
* g_prefix_error().
*
* Since: 2.16
projects / platform / upstream / glib.git / blobdiff