diff --git a/docs/reference/glib/tmpl/.gitignore b/docs/reference/glib/tmpl/.gitignore index e2c73597c..8ecb0272c 100644 --- a/docs/reference/glib/tmpl/.gitignore +++ b/docs/reference/glib/tmpl/.gitignore @@ -46,3 +46,4 @@ timers.sgml timezone.sgml unicode.sgml version.sgml +warnings.sgml diff --git a/docs/reference/glib/tmpl/warnings.sgml b/docs/reference/glib/tmpl/warnings.sgml deleted file mode 100644 index 6c2aad782..000000000 --- a/docs/reference/glib/tmpl/warnings.sgml +++ /dev/null @@ -1,236 +0,0 @@ - -Message Output and Debugging Functions - - -functions to output messages and help debug applications - - - -These functions provide support for outputting messages. - - -The g_return family of macros (g_return_if_fail(), -g_return_val_if_fail(), g_return_if_reached(), g_return_val_if_reached()) -should only be used for programming errors, a typical use case is -checking for invalid parameters at the beginning of a public function. -They should not be used if you just mean "if (error) return", they -should only be used if you mean "if (bug in program) return". -The program behavior is generally considered undefined after one of these -checks fails. They are not intended for normal control flow, only to -give a perhaps-helpful warning before giving up. - - - - - - - - - - - - - - - -Outputs a formatted message via the print handler. -The default print handler simply outputs the message to stdout. - - -g_print() should not be used from within libraries for debugging messages, -since it may be redirected by applications to special purpose message -windows or even files. -Instead, libraries should use g_log(), or the convenience functions -g_message(), g_warning() and g_error(). - - -@format: the message format. See the printf() documentation. -@Varargs: the parameters to insert into the format string. - - - - -Sets the print handler. -Any messages passed to g_print() will be output via the new handler. -The default handler simply outputs the message to stdout. -By providing your own handler you can redirect the output, to a GTK+ -widget or a log file for example. - - -@func: the new print handler. -@Returns: the old print handler. - - - - -Specifies the type of the print handler functions. -These are called with the complete formatted string to output. - - -@string: the message to be output. - - - - -Outputs a formatted message via the error message handler. -The default handler simply outputs the message to stderr. - - -g_printerr() should not be used from within libraries. Instead g_log() should -be used, or the convenience functions g_message(), g_warning() and g_error(). - - -@format: the message format. See the printf() documentation. -@Varargs: the parameters to insert into the format string. - - - - -Sets the handler for printing error messages. -Any messages passed to g_printerr() will be output via the new handler. -The default handler simply outputs the message to stderr. -By providing your own handler you can redirect the output, to a GTK+ -widget or a log file for example. - - -@func: the new error message handler. -@Returns: the old error message handler. - - - - -Returns from the current function if the expression is not true. -If the expression evaluates to %FALSE, a critical message is logged and -the function returns. This can only be used in functions which do not return -a value. - - -@expr: the expression to check. - - - - -Returns from the current function, returning the value @val, if the expression -is not true. -If the expression evaluates to %FALSE, a critical message is logged and -@val is returned. - - -@expr: the expression to check. -@val: the value to return from the current function if the expression is not -true. - - - - -Logs a critical message and returns from the current function. -This can only be used in functions which do not return a value. - - - - - - -Logs a critical message and returns @val. - - -@val: the value to return from the current function. - - - - -Logs a warning if the expression is not true. - - -@expr: the expression to check -@Since: 2.16 - - - - -Logs a critical warning. - - -@Since: 2.16 - - - - -Prompts the user with [E]xit, [H]alt, show [S]tack trace or [P]roceed. -This function is intended to be used for debugging use only. The following -example shows how it can be used together with the g_log() functions. - - -#include <glib.h> - -static void -log_handler (const gchar *log_domain, - GLogLevelFlags log_level, - const gchar *message, - gpointer user_data) -{ - g_log_default_handler (log_domain, log_level, message, user_data); - - g_on_error_query (MY_PROGRAM_NAME); -} - -int main (int argc, char *argv[]) -{ - g_log_set_handler (MY_LOG_DOMAIN, - G_LOG_LEVEL_WARNING | - G_LOG_LEVEL_ERROR | - G_LOG_LEVEL_CRITICAL, - log_handler, - NULL); - - /* ... */ - - -If [E]xit is selected, the application terminates with a call to -_exit(0). - - -If [H]alt is selected, the application enters an infinite loop. -The infinite loop can only be stopped by killing the application, -or by setting #glib_on_error_halt to %FALSE (possibly via a debugger). - - -If [S]tack trace is selected, g_on_error_stack_trace() is called. This -invokes gdb, which attaches to the current process and shows a stack trace. -The prompt is then shown again. - - -If [P]roceed is selected, the function returns. - - -This function may cause different actions on non-UNIX platforms. - - -@prg_name: the program name, needed by gdb for the [S]tack trace option. -If @prg_name is %NULL, g_get_prgname() is called to get the program name -(which will work correctly if gdk_init() or gtk_init() has been called). - - - - -Invokes gdb, which attaches to the current process and shows a stack trace. -Called by g_on_error_query() when the [S]tack trace option is selected. - - -This function may cause different actions on non-UNIX platforms. - - -@prg_name: the program name, needed by gdb for the [S]tack trace option. -If @prg_name is %NULL, g_get_prgname() is called to get the program name -(which will work correctly if gdk_init() or gtk_init() has been called). - - - - -Inserts a breakpoint instruction into the code. On x86 and alpha systems -this is implemented as a soft interrupt and on other architectures it raises -a %SIGTRAP signal. - - - - diff --git a/glib/gbacktrace.c b/glib/gbacktrace.c index ae16ef869..227d70426 100644 --- a/glib/gbacktrace.c +++ b/glib/gbacktrace.c @@ -91,6 +91,56 @@ static void stack_trace (char **args); extern volatile gboolean glib_on_error_halt; volatile gboolean glib_on_error_halt = TRUE; +/** + * g_on_error_query: + * @prg_name: the program name, needed by gdb + * for the [S]tack trace option. If @prg_name is %NULL, g_get_prgname() + * is called to get the program name (which will work correctly if + * gdk_init() or gtk_init() has been called) + * + * Prompts the user with + * [E]xit, [H]alt, show [S]tack trace or [P]roceed. + * This function is intended to be used for debugging use only. + * The following example shows how it can be used together with + * the g_log() functions. + * + * |[ + * #include <glib.h> + * + * static void + * log_handler (const gchar *log_domain, + * GLogLevelFlags log_level, + * const gchar *message, + * gpointer user_data) + * { + * g_log_default_handler (log_domain, log_level, message, user_data); + * + * g_on_error_query (MY_PROGRAM_NAME); + * } + * + * int + * main (int argc, char *argv[]) + * { + * g_log_set_handler (MY_LOG_DOMAIN, + * G_LOG_LEVEL_WARNING | + * G_LOG_LEVEL_ERROR | + * G_LOG_LEVEL_CRITICAL, + * log_handler, + * NULL); + * /* ... */ + * ]| + * + * If [E]xit is selected, the application terminates with a call + * to _exit(0). + * + * If [S]tack trace is selected, g_on_error_stack_trace() is called. + * This invokes gdb, which attaches to the current + * process and shows a stack trace. The prompt is then shown again. + * + * If [P]roceed is selected, the function returns. + * + * This function may cause different actions on non-UNIX platforms. + */ void g_on_error_query (const gchar *prg_name) { @@ -160,6 +210,19 @@ g_on_error_query (const gchar *prg_name) #endif } +/** + * g_on_error_stack_trace: + * @prg_name: the program name, needed by gdb + * for the [S]tack trace option. If @prg_name is %NULL, g_get_prgname() + * is called to get the program name (which will work correctly if + * gdk_init() or gtk_init() has been called) + * + * Invokes gdb, which attaches to the current + * process and shows a stack trace. Called by g_on_error_query() + * when the [S]tack trace option is selected. + * + * This function may cause different actions on non-UNIX platforms. + */ void g_on_error_stack_trace (const gchar *prg_name) { diff --git a/glib/gbacktrace.h b/glib/gbacktrace.h index 43a0c46a2..0ee3efd2f 100644 --- a/glib/gbacktrace.h +++ b/glib/gbacktrace.h @@ -36,20 +36,16 @@ G_BEGIN_DECLS -/* Fatal error handlers. - * g_on_error_query() will prompt the user to either - * [E]xit, [H]alt, [P]roceed or show [S]tack trace. - * g_on_error_stack_trace() invokes gdb, which attaches to the current - * process and shows a stack trace. - * These function may cause different actions on non-unix platforms. - * The prg_name arg is required by gdb to find the executable, if it is - * passed as NULL, g_on_error_query() will try g_get_prgname(). - */ void g_on_error_query (const gchar *prg_name); void g_on_error_stack_trace (const gchar *prg_name); -/* Hacker macro to place breakpoints for selected machines. - * Actual use is strongly discouraged of course ;) +/** + * G_BREAKPOINT: + * + * Inserts a breakpoint instruction into the code. + * + * On x86 and alpha systems this is implemented as a soft interrupt + * and on other architectures it raises a %SIGTRAP signal. */ #if (defined (__i386__) || defined (__x86_64__)) && defined (__GNUC__) && __GNUC__ >= 2 # define G_BREAKPOINT() G_STMT_START{ __asm__ __volatile__ ("int $03"); }G_STMT_END diff --git a/glib/gmessages.c b/glib/gmessages.c index 337d19a50..43b958fb0 100644 --- a/glib/gmessages.c +++ b/glib/gmessages.c @@ -28,6 +28,24 @@ * MT safe */ +/** + * SECTION:warnings + * @Title: Message Output and Debugging Functions + * @Short_description: functions to output messages and help debug applications + * + * These functions provide support for outputting messages. + * + * The g_return family of macros (g_return_if_fail(), + * g_return_val_if_fail(), g_return_if_reached(), g_return_val_if_reached()) + * should only be used for programming errors, a typical use case is + * checking for invalid parameters at the beginning of a public function. + * They should not be used if you just mean "if (error) return", they + * should only be used if you mean "if (bug in program) return". + * The program behavior is generally considered undefined after one + * of these checks fails. They are not intended for normal control + * flow, only to give a perhaps-helpful warning before giving up. + */ + #include "config.h" #include @@ -986,37 +1004,65 @@ g_log_default_handler (const gchar *log_domain, g_free (string); } +/** + * g_set_print_handler: + * @func: the new print handler + * + * Sets the print handler. + * + * Any messages passed to g_print() will be output via + * the new handler. The default handler simply outputs + * the message to stdout. By providing your own handler + * you can redirect the output, to a GTK+ widget or a + * log file for example. + * + * Returns: the old print handler + */ GPrintFunc g_set_print_handler (GPrintFunc func) { GPrintFunc old_print_func; - + g_mutex_lock (g_messages_lock); old_print_func = glib_print_func; glib_print_func = func; g_mutex_unlock (g_messages_lock); - + return old_print_func; } +/** + * g_print: + * @format: the message format. See the printf() documentation + * @Varargs: the parameters to insert into the format string + * + * Outputs a formatted message via the print handler. + * The default print handler simply outputs the message to stdout. + * + * g_print() should not be used from within libraries for debugging + * messages, since it may be redirected by applications to special + * purpose message windows or even files. Instead, libraries should + * use g_log(), or the convenience functions g_message(), g_warning() + * and g_error(). + */ void g_print (const gchar *format, - ...) + ...) { va_list args; gchar *string; GPrintFunc local_glib_print_func; - + g_return_if_fail (format != NULL); - + va_start (args, format); string = g_strdup_vprintf (format, args); va_end (args); - + g_mutex_lock (g_messages_lock); local_glib_print_func = glib_print_func; g_mutex_unlock (g_messages_lock); - + if (local_glib_print_func) local_glib_print_func (string); else @@ -1024,50 +1070,76 @@ g_print (const gchar *format, const gchar *charset; if (g_get_charset (&charset)) - fputs (string, stdout); /* charset is UTF-8 already */ + fputs (string, stdout); /* charset is UTF-8 already */ else - { - gchar *lstring = strdup_convert (string, charset); + { + gchar *lstring = strdup_convert (string, charset); - fputs (lstring, stdout); - g_free (lstring); - } + fputs (lstring, stdout); + g_free (lstring); + } fflush (stdout); } g_free (string); } +/** + * g_set_printerr_handler: + * @func: the new error message handler + * + * Sets the handler for printing error messages. + * + * Any messages passed to g_printerr() will be output via + * the new handler. The default handler simply outputs the + * message to stderr. By providing your own handler you can + * redirect the output, to a GTK+ widget or a log file for + * example. + * + * Returns: the old error message handler + */ GPrintFunc g_set_printerr_handler (GPrintFunc func) { GPrintFunc old_printerr_func; - + g_mutex_lock (g_messages_lock); old_printerr_func = glib_printerr_func; glib_printerr_func = func; g_mutex_unlock (g_messages_lock); - + return old_printerr_func; } +/** + * g_printerr: + * @format: the message format. See the printf() documentation + * @Varargs: the parameters to insert into the format string + * + * Outputs a formatted message via the error message handler. + * The default handler simply outputs the message to stderr. + * + * g_printerr() should not be used from within libraries. + * Instead g_log() should be used, or the convenience functions + * g_message(), g_warning() and g_error(). + */ void g_printerr (const gchar *format, - ...) + ...) { va_list args; gchar *string; GPrintFunc local_glib_printerr_func; - + g_return_if_fail (format != NULL); - + va_start (args, format); string = g_strdup_vprintf (format, args); va_end (args); - + g_mutex_lock (g_messages_lock); local_glib_printerr_func = glib_printerr_func; g_mutex_unlock (g_messages_lock); - + if (local_glib_printerr_func) local_glib_printerr_func (string); else @@ -1075,14 +1147,14 @@ g_printerr (const gchar *format, const gchar *charset; if (g_get_charset (&charset)) - fputs (string, stderr); /* charset is UTF-8 already */ + fputs (string, stderr); /* charset is UTF-8 already */ else - { - gchar *lstring = strdup_convert (string, charset); + { + gchar *lstring = strdup_convert (string, charset); - fputs (lstring, stderr); - g_free (lstring); - } + fputs (lstring, stderr); + g_free (lstring); + } fflush (stderr); } g_free (string); diff --git a/glib/gmessages.h b/glib/gmessages.h index 9acaec637..586341995 100644 --- a/glib/gmessages.h +++ b/glib/gmessages.h @@ -226,6 +226,13 @@ g_debug (const gchar *format, } #endif /* !__GNUC__ */ +/** + * GPrintFunc: + * @string: the message to output + * + * Specifies the type of the print handler functions. + * These are called with the complete formatted string to output. + */ typedef void (*GPrintFunc) (const gchar *string); void g_print (const gchar *format, ...) G_GNUC_PRINTF (1, 2); @@ -234,23 +241,73 @@ void g_printerr (const gchar *format, ...) G_GNUC_PRINTF (1, 2); GPrintFunc g_set_printerr_handler (GPrintFunc func); - -/* Provide macros for graceful error handling. - * The "return" macros will return from the current function. - * Two different definitions are given for the macros in - * order to support gcc's __PRETTY_FUNCTION__ capability. +/** + * g_warn_if_reached: + * + * Logs a critical warning. + * + * Since: 2.16 */ +#define g_warn_if_reached() \ + do { \ + g_warn_message (G_LOG_DOMAIN, __FILE__, __LINE__, G_STRFUNC, NULL); \ + } while (0) -#define g_warn_if_reached() do { g_warn_message (G_LOG_DOMAIN, __FILE__, __LINE__, G_STRFUNC, NULL); } while (0) -#define g_warn_if_fail(expr) do { if G_LIKELY (expr) ; else \ - g_warn_message (G_LOG_DOMAIN, __FILE__, __LINE__, G_STRFUNC, #expr); } while (0) +/** + * g_warn_if_fail: + * @expr: the expression to check + * + * Logs a warning if the expression is not true. + * + * Since: 2.16 + */ +#define g_warn_if_fail(expr) \ + do { \ + if G_LIKELY (expr) ; \ + else g_warn_message (G_LOG_DOMAIN, __FILE__, __LINE__, G_STRFUNC, #expr); \ + } while (0) #ifdef G_DISABLE_CHECKS -#define g_return_if_fail(expr) G_STMT_START{ (void)0; }G_STMT_END -#define g_return_val_if_fail(expr,val) G_STMT_START{ (void)0; }G_STMT_END -#define g_return_if_reached() G_STMT_START{ return; }G_STMT_END -#define g_return_val_if_reached(val) G_STMT_START{ return (val); }G_STMT_END +/** + * g_return_if_fail: + * @expr: the expression to check + * + * Returns from the current function if the expression + * is not true. If the expression evaluates to %FALSE, + * a critical message is logged and the function returns. + * This can only be used in functions which do not return + * a value. + */ +#define g_return_if_fail(expr) G_STMT_START{ (void)0; }G_STMT_END + +/** + * g_return_val_if_fail: + * @expr: the expression to check + * @val: the value to return from the current function + * if the expression is not true + * + * Returns from the current function, returning the value @val, + * if the expression is not true. If the expression evaluates + * to %FALSE, a critical message is logged and @val is returned. + */ +#define g_return_val_if_fail(expr,val) G_STMT_START{ (void)0; }G_STMT_END + +/** + * g_return_if_reached: + * + * Logs a critical message and returns from the current function. + * This can only be used in functions which do not return a value. + */ +#define g_return_if_reached() G_STMT_START{ return; }G_STMT_END + +/** + * g_return_val_if_reached: + * @val: the value to return from the current function + * + * Logs a critical message and returns @val. + */ +#define g_return_val_if_reached(val) G_STMT_START{ return (val); }G_STMT_END #else /* !G_DISABLE_CHECKS */