* 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);
* g_error_free (err);
* }
* else
* {
- * /* Use file contents */
+ * // Use file contents
* g_assert (contents != NULL);
* }
* ]|
* are only interested in whether it failed and don't need to display
* 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 */ ;
+ * 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
* 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;
* }
*
* 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);
* }
* ]|
*
* 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
* }
* ]|
*
*
* 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);
*
* Error domains and codes are conventionally named as follows:
*
- * - The error domain is called <NAMESPACE>_<MODULE>_ERROR,
+ * - The error domain is called <NAMESPACE>_<MODULE>_ERROR,
* for example %G_SPAWN_ERROR or %G_THREAD_ERROR:
* |[<!-- language="C" -->
* #define G_SPAWN_ERROR g_spawn_error_quark ()
* ]|
*
* - The quark function for the error domain is called
- * <namespace>_<module>_error_quark,
+ * <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.
+ * <Namespace><Module>Error;
+ * for example, #GThreadError or #GSpawnError.
*
* - Members of the error code enumeration are called
- * <NAMESPACE>_<MODULE>_ERROR_<CODE>,
+ * <NAMESPACE>_<MODULE>_ERROR_<CODE>,
* 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 <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:
*
* 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.
+ * <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,
* 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,
*
* 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,
projects / platform / upstream / glib.git / blobdiff