X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=glib%2Fgerror.c;h=db31692b0038ea71f379a544e142484ca5a8eb33;hb=30ed5f53e205e6bfc35126a9d3c62dac8a9c5dad;hp=5093876ffa7b09bb0bdf345549e3d0b64abc7e83;hpb=d76f4455f1248b88473d8acbb19a9152f800c269;p=platform%2Fupstream%2Fglib.git diff --git a/glib/gerror.c b/glib/gerror.c index 5093876..db31692 100644 --- a/glib/gerror.c +++ b/glib/gerror.c @@ -53,46 +53,48 @@ * * Functions that can fail take a return location for a #GError as their * last argument. For example: - * |[ + * |[ * gboolean g_file_get_contents (const gchar *filename, * gchar **contents, * gsize *length, * GError **error); * ]| - * 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: - * |[ + * 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: + * |[ * 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 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 + * 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 */ ; + * |[ + * 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 @@ -114,7 +116,7 @@ * 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: - * |[ + * |[ * gint * foo_open_file (GError **error) * { @@ -122,12 +124,12 @@ * * 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; * } @@ -140,7 +142,7 @@ * 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: - * |[ + * |[ * gboolean * my_function_that_can_fail (GError **err) * { @@ -148,12 +150,12 @@ * * 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); * } * ]| @@ -162,7 +164,7 @@ * 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. - * |[ + * |[ * gboolean * my_function_that_can_fail (GError **err) * { @@ -171,23 +173,22 @@ * 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: - * |[ + * |[ * gboolean * my_function_that_can_fail (GError **err) * { @@ -196,8 +197,8 @@ * 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) * { @@ -214,7 +215,7 @@ * 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(): - * |[ + * |[ * gboolean * my_function_that_can_fail (GError **err) * { @@ -222,10 +223,10 @@ * * 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) * { @@ -235,17 +236,17 @@ * } * ]| * - * 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. + * 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: * - * - The error domain is called <NAMESPACE>_<MODULE>_ERROR, + * - The error domain is called __ERROR, * for example %G_SPAWN_ERROR or %G_THREAD_ERROR: - * |[ + * |[ * #define G_SPAWN_ERROR g_spawn_error_quark () * * GQuark @@ -256,21 +257,25 @@ * ]| * * - The quark function for the error domain is called - * <namespace>_<module>_error_quark, + * __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. + * Error; + * for example, #GThreadError or #GSpawnError. * * - Members of the error code enumeration are called - * <NAMESPACE>_<MODULE>_ERROR_<CODE>, + * __ERROR_, * for example %G_SPAWN_ERROR_FORK or %G_THREAD_ERROR_AGAIN. * * - 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 <NAMESPACE>_<MODULE>_ERROR_FAILED, - * for example %G_SPAWN_ERROR_FAILED. + * it should be called __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: * @@ -309,9 +314,23 @@ * g_set_error() will complain if you pile up errors. * * - By convention, if you return a boolean value indicating success - * then %TRUE means success and %FALSE means failure. If %FALSE is + * then %TRUE means success and %FALSE means failure. + * 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. + * + * If %FALSE is * returned, the error must be set to a non-%NULL value. - * + * 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. + * * - 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, @@ -321,7 +340,7 @@ * - 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. - * g_return_if_fail (error == NULL || *error == NULL);). + * `g_return_if_fail (error == NULL || *error == NULL);`). */ #include "config.h" @@ -381,7 +400,7 @@ g_error_new_valist (GQuark 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, @@ -413,7 +432,7 @@ 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, @@ -456,7 +475,7 @@ g_error_free (GError *error) * * Makes a copy of @error. * - * Return value: a new #GError + * Returns: a new #GError */ GError* g_error_copy (const GError *error) @@ -487,7 +506,14 @@ 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,