*
* 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
- * reliable indicator of whether g_file_get_contents() failed.
- * Additionally, g_file_get_contents() returns a boolean which
+ * 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 @error argument:
- * |[
- * if (g_file_get_contents ("foo.txt", &contents, NULL, NULL)) /* ignore errors */
- * /* no error occurred */ ;
+ * |[<!-- 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: @domain indicates the module
* 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)
* {
* 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 ignores errors; it's
- * equivalent to
- * <literal>try { sub_function_that_can_fail (); } catch (...) {}</literal>
- * in C++. It does not 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>,
+ *
+ * - The quark function for the error domain is called
+ * <namespace>_<module>_error_quark,
* 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 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 had a
+ *
+ * - 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.
- * </para></listitem>
- * <listitem><para>
- * If a #GError is reported, out parameters are not guaranteed to
+ *
+ * - If a #GError is reported, out parameters are not guaranteed to
* be set to any defined value.
- * </para></listitem>
- * <listitem><para>
- * A #GError* must be initialized to %NULL before passing its address
+ *
+ * - 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 must 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"
* 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)
* 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,